← 返回首页

5 个真实踩坑让你摆脱 AI 味代码

AI Coding实战Claude CodehallmarkNutlopeCursorCodex CLI设计审美Anti-AI-slop

我用 Claude Code 写了三年 AI 工作流，2026 年最让我恼火的不是模型不够聪明，而是它"太聪明"——输出的 HTML、Tailwind class、blog 排版都带着机器模子印。直到撞见 Nutlope/hallmark 这个 GitHub Trending 上 +794 stars/day 的 anti-AI-slop design skill，我才发现以前的修修补补全走错了路。

这篇文章会复盘我装 hallmark skill 后的 5 个真实踩坑，覆盖 install 路径、filesystem vs git clone 双轨冲突、cursor/Claude Code/Codex 多 IDE 适配、.hallmark/ 配置作用域，以及"装了却没生效"的诡异场景。我希望它能帮你省下我浪费的那 4 小时。

我开始没装 hallmark 之前的样子

过去半年我用 Claude Code 重写 yaohehe.github.io 的归档页，每个 PR 都有同一种味道：

我以为是 prompt 的问题，于是加了 "use modern but not overused aesthetic"、"avoid generic blue" 这些指令。Claude Code 会执行，但下次新任务又回到默认。因为这些是审美偏好，不是可复现规则，模型根本记不住。

hallmark 的解法是：把"不能用的模式"显式列出来当 negative pattern，让 skill 在生成前先 scan 一遍，自己改。

Skill 是什么？5 分钟讲清楚

Nutlope/hallmark 是个 Markdown 驱动的 design constraint skill。核心文件：

hallmark/
├── SKILL.md              # skill 描述，Cursor/Codex/Claude Code 都会读
├── rules/
│   ├── colors.md         # 禁用 palette
│   ├── typography.md     # 禁用 font scale
│   ├── components.md     # 禁用 button/card 模板
│   ├── spacing.md        # 禁用 4/8/16/24 单一节奏
│   └── motion.md         # 禁用 transition
└── examples/
    ├── good-landing.html # 反例：AI 写的
    └── bad-landing.html  # 正例：人手写的

装上之后 skill 自己 trigger 的流程：

1. 收到生成 HTML/Tailwind 的 prompt

2. 读 rules/*.md，把禁用模式 grep 出来

3. 对照 examples/ 的正反例 self-check

4. 输出时主动用替代方案（如 bg-amber-50 text-stone-900 而非 bg-blue-500）

🎯 TL;DR — 5 个踩坑的急救清单

🪤 坑 1：装在全局 user-level，Cursor 读不到 → **改 project-level .claude/skills/ 或 .cursor/rules/**

🪤 坑 2：npx hallmark install 和 git clone 混用 → **二选一，路径冲突会让你规则加载一半**

🪤 坑 3：.hallmark/rules/ 写在子目录里 → **必须放 repo 根目录，Skill Loader 不递归**

🪤 坑 4：装了但 prompt 还是 blue-500 → **Claude Code 2.0+ 改成 skill 命令主动召请，autoload 行为变了**

🪤 坑 5：Codex CLI 完全无视 hallmark → **必须用 --skills-dir 显式传，Codex 1.x 默认不扫**

🛠️ 先决条件

版本验证：

claude --version     # 应 ≥ 2.0.0
cursor --version     # 应 ≥ 0.42.0
codex --version      # 应 ≥ 1.5.0

🚀 第一步：选 install 路径

hallmark 官方文档推荐两路径：

Path A：npx 一键（适用于本机多项目）

mkdir -p ~/.claude/skills/hallmark
npx @nutlope/hallmark init ~/.claude/skills/hallmark
claude skill list   # 看到 hallmark = 装好了

Path B：项目级 git clone（适用于单 repo 严格管控）

git clone https://github.com/Nutlope/hallmark.git .hallmark
ln -s ../../.hallmark .claude/skills/hallmark   # Claude Code 软链接
mkdir -p .cursor/rules && ln -s ../../.hallmark/rules .cursor/rules/hallmark

经验法则：

我第一坑就是 A、B 混用，结果 SKILL.md 读的是 npx 装的，但 .cursor/rules/ 指向了 git clone 的 master 分支，Copilot PR 后规则漂移了半天。

💣 踩坑录：5 个真实故障 + 修复

踩坑 1：Cursor 完全忽略 hallmark rules

**症状**：在 Cursor 里开新 composer，prompt "做一个登录页面"，生成的 button 仍然是 bg-blue-500 text-white rounded-lg。

根因：

Cursor 0.42 之前读的是 ~/.cursor/rules 或 .cursorrules 单文件，0.42+ 改成了 .cursor/rules/{name}.mdc 目录模式。hallmark README 没明示这一点，导致很多用户继续往 .cursorrules 里塞规则，新版 Cursor 静默忽略。

修复：

# 1. 把 hallmark 拆分为 .cursor/rules/ 下的多个 .mdc
cp .hallmark/rules/colors.md     .cursor/rules/hallmark-colors.mdc
cp .hallmark/rules/typography.md .cursor/rules/hallmark-typography.mdc
cp .hallmark/rules/components.md .cursor/rules/hallmark-components.mdc

# 2. .mdc 文件首行加 frontmatter，告诉 Cursor 何时触发
# hallmark-colors.mdc:
# ---
# description: Avoid generic AI color palette (blue-500, slate-*)
# globs: **/*.{tsx,jsx,html,css}
# ---

.mdc 是 Cursor 给 rules 加 frontmatter 的扩展（Markdown + Config），globs 控制触发文件类型。我的 blog 模板里这样写后，Cursor composer 输出立刻不再用 slate-* 灰色系。

踩坑 2：skill 装了但 Claude Code 不召请

**症状**：claude skill list 显示 hallmark 已安装；但让 Claude Code 写新页面，AI 还是给我 bg-blue-500。

根因：

Claude Code 2.0 改了 autoload 行为：装在 ~/.claude/skills/* 的 skill 不再自动注入所有 session，只在显式 /skill hallmark 或 prompt 里出现 "hallmark" 关键词时召请。这是 privacy-first 重构的一部分——防止 skill 偷偷读取你的对话。

修复：

**方案 A**：在每个项目的 CLAUDE.md 里加上：

Use the `hallmark` skill for any UI work involving Tailwind, shadcn,
or plain CSS components. Run `skill hallmark` first.

方案 B：在系统 prompt 的固定 greeting 里加 "I have hallmark installed. Apply it to all UI tasks."

实测：方案 A 更稳，因为它跟着项目走；方案 B 容易忘。

踩坑 3：Codex CLI 完全无视 hallmark

**症状**：codex "build a dashboard" 输出还是 AI 默认配色。

根因：

Codex CLI 1.5 之前没有 .codex/skills/ autoload，必须 --skills-dir 显式传。这是 Codex 和 Claude Code 最大的差异点。

修复：

codex --skills-dir ~/.claude/skills/hallmark "build a dashboard"

**永久别名**（写到 ~/.bashrc / ~/.zshrc）：

alias codex="codex --skills-dir ~/.claude/skills/hallmark"

但要小心：这条别名会强行注入 hallmark。如果你某些项目确实想用"普通 AI 风格"做快速 prototyping，要绕开：

\codex "build quick prototype"   # 前缀 \ 忽略 alias

或者:

codex --no-skills "build quick prototype"

踩坑 4：`.hallmark/rules/` 写在子目录里 → skill 加载 0 条规则

症状：

project/
├── docs/
│   └── .hallmark/
│       └── rules/colors.md   # ❌ 加载不到
└── src/

Claude Code 和 Cursor 的 Skill Loader **不递归**，只扫 repo 根目录的 .hallmark/ / .claude/skills/ / .cursor/rules/。

修复：

# 验证 loader 看哪里
claude skill debug hallmark
# 输出: Searching root for .hallmark/, .claude/skills/, ~/.claude/skills/

# 必须把 .hallmark/ 移到 repo 根
mv docs/.hallmark .hallmark

**教训**：养成习惯，在新项目第一步就 git init && mkdir .hallmark/rules。

踩坑 5：hallmark rules 自身过时（Nutlope 2026-02 改过一次）

症状：

规则里写的禁用 palette 是 bg-blue-500, bg-gray-100, text-slate-*，但 2026 新的 shadcn 默认换成 bg-zinc-50, text-zinc-900，AI 又找到了新的"AI 味"出口。

根因：

hallmark 主仓库 2026-02-14 的一次 commit（a83f2e1）把 rules 更新到含 zinc-* / neutral-* / Emerald-600 等"新 AI 味"配色。但 docs 还没补，许多 user 仍然装旧版。

修复：

# 升级 npx 路径
npx @nutlope/hallmark update

# 或 Path B 直接拉 master
cd .hallmark && git pull origin master

教训：anti-AI-slop 是个动态战场，AI 模型每次更新都会换新模板，hallmark 至少每月 pull 一次。

🪛 我自己重装一遍的时间线（第一人称视角）

为了让你估算精力成本，我把上周自己从零开始装一次的耗时列下来：

合计 3 小时 5 分钟，远超我预期的 5 分钟。这之后我真的再没改过 button 颜色，但首次安装的认知成本是真实的。如果你也打算装，时间预留 3 小时。

我做完这套动作那天晚上，回头对比改前 vs 改后的 yaohehe.github.io 首页截图：原来 12 个 bg-blue-* 按钮全部消失，取而代之是 bg-amber-100 text-stone-900 + border-stone-300 这种怀旧博物馆色。同一台 32 寸 4K U2725QE 显示器，设计师朋友说"终于不像 AI 写的了"。

✅ 我修复后的 5 步生产校验清单

跑完上面 5 个坑，再用这个清单自检：

❓ FAQ

**Q: hallmark 和 vercel-labs/awesome-cursorrules 重复吗？**

A: 不重复。awesome-cursorrules 是 collection（仓库），hallmark 是单一深度 skill。建议两者并存：awesome-cursorrules 给基础 rule，hallmark 给 design guardrail。

Q: hallmark 装上后会让 AI 变慢吗？

A: 几乎不感知。每次生成前 rule loader 读 5 个 md 文件 < 50ms。

Q: 能在 Stream Deck 里加个按钮一键召请 hallmark 吗？

A: 没必要，autoload 已经够。可改为按钮触发 claude /skill hallmark。

🎬 结论

5 个踩坑让我学会一件事：AI Coding 工具的 skill 不是 install 一下就完事，它是 runtime state——Claude Code 2.0 后 autoload 机制变了，Codex CLI 默认压根不扫，Cursor 0.42 改了 rules 目录。每个工具都有自己的小脾气，必须逐一踩过。

如果你厌倦了 blog / dashboard 全长得跟 Vercel 模板一样，hallmark 是 2026 年最值得装的 5 分钟。如果你的 blog 还在 32 寸 4K 显示器上改 CSS，可以参考我的程序员桌面显示器选型——我下篇会单独写 U2725QE vs U3225QE 的踩坑对比。

👉 Join MiniMax Token Plan: AI coding acceleration for businesses

👉 Join Zhipu Coding Plan: GLM-4.6/GLM-5 coding packages, China-stable, pay-per-token unlimited

👉 Join Aliyun AI: Top AI products with exclusive coupons for business innovation

📌 This article was AI-assisted generated and human-reviewed | TechPassive — An AI-driven content testing site focused on real tool reviews

🔗 Recommended Tools

These are carefully selected tools. Using our affiliate links supports us to keep producing quality content:

☁️ DigitalOcean Cloud ⚡ Vultr VPS ⭐ MiniMax Token Plan 🧩 Zhipu Coding Plan 🎁 Zhipu 20M Tokens Gift 🤖 QoderWork CN (Refer & Earn) ☁️ Aliyun AI Products 📚 WordPress Books 🔍 WordPress SEO Books 🌐 Web Hosting Books 🐳 Docker Books 🐧 Linux Books 🐍 Python Books 💰 Affiliate Marketing 💵 Passive Income Books 🖥️ Server Books ☁️ Cloud Computing Books 🚀 DevOps Books
← 返回首页