个人开发者 Claude Code Harness 最佳实践（2025–2026）

核心结论复制标题链接

• 最高杠杆的做法：把 CLAUDE.md 当代码来精简（目标 80–120 行），其余一切做成按需加载的 skill，用 hook 强制执行那些"绝对不能跳过"的规则——这套组合比任何数量的 MCP server 或花哨的 prompt 都管用。
• 装 Jesse Vincent 的 Superpowers 插件（GitHub：obra）作为默认纪律层（brainstorm → plan → TDD → subagent review），然后在此基础上加 5–10 个项目专属 skill，而不是 20–30 个。超过默认 skill 列表预算（~32 个，占 200K 上下文的 1%）后，Claude Code 会静默截断 skill 描述，你装的那些自动发现能力就白费了。
• 个人 iOS/FastAPI/Go 工作的双工具方案：Claude Code 作主力（plan + 实现），Codex CLI 在第二个终端做对抗性 review，一个提交到 git 的 AGENTS.md 作跨工具单一真相源，CLAUDE.md 只是薄薄一层 @AGENTS.md 的 re-export。 只有同时用超过两个 CLI 时才需要 cc-switch。

核心发现复制标题链接

1. CLAUDE.md** 有硬性指令预算上限。** Anthropic 文档与 HumanLayer 分析一致：Claude Code 自身的 system prompt 已经消耗了模型能可靠关注的约 150–200 条指令中的 ~50 条。超过约 200 行后，不是末尾内容被截断——而是所有指令的遵循质量均匀下降。实验最优区间：根文件 80–120 行，monorepo 中每个子包文件 30–60 行。
2. Skill 受"列表预算"约束，大多数人从未意识到这点。 Anthropic 官方 skill 文档：Claude Code 将上下文窗口的 1%（skillListingBudgetFraction = 0.01）分配给 skill 名称+描述，每条描述无论预算如何都硬性上限 1,536 字符。200K 上下文下约为 7,050 字符用于描述。Carlos Delgado 在 DEV Community 的分析直白说："32 个 skill，预算刚好满。33 个，就有东西要让步。" 超出预算后，Claude 静默截断你最少调用的那些 skill 的描述——也就是说，你安装它们的自动发现能力悄悄失效了。
3. Hook 比 skill 更适合"必须执行"的事。 Skill 是 Claude 可以忽略的建议；PreToolUse/PostToolUse hook 是 harness 在 Claude 推理循环之外强制执行的确定性约束。用 hook 做：写入时 lint、密钥扫描、危险命令拦截、pnpm vs npm 强制。用 skill 做：Claude 怎么思考和工作。
4. AGENTS.md** 现在是可移植的跨工具标准。** 由 OpenAI 于 2025 年 8 月发布，2025 年 12 月捐赠给 Linux Foundation 旗下 Agentic AI Foundation。已有 60,000+ 开源项目采用，覆盖 Amp、Codex、Cursor、Devin、Factory、Gemini CLI、GitHub Copilot、Jules、VS Code 等。推荐做法：实质内容放 AGENTS.md，CLAUDE.md 只写 See @AGENTS.md 加上 Claude 专有补充。
5. OpenSpec 以最小仪式感提供 spec 驱动纪律。 安装三个斜杠命令（/openspec:proposal、/openspec:apply、/openspec:archive）和一个 openspec/ 目录。Hashrocket 对比 Spec Kit 发现：OpenSpec 生成约 250 行产物，Spec Kit 生成约 800 行——review 成本低得多。
6. Superpowers 是最接近"默认纪律插件"的东西。 Jesse Vincent 创建（GitHub obra），强制执行 brainstorm → plan → TDD → subagent 实现流程，内置代码审查。跨 harness 兼容：Claude Code、Codex CLI、OpenCode、Gemini CLI、Cursor、Copilot CLI、Factory Droid。
7. 上下文腐烂是最常见的失败模式。 Anthropic 工程博客明确指出：即使在 1M 窗口内，性能也会随上下文填满而下降。Marmelab 从生产使用中得出结论："默认不要用 Opus 的 1M 上下文。约 400K token 后，agent 相关性就变差了。"
8. "越多越好"的直觉是所有常见反模式的根源：臃肿的 CLAUDE.md、30+ skill、一堆 MCP server、大量自定义斜杠命令。Shrivu Shankar 的规则："如果你用了超过 20K token 的 MCP，你就是在把 Claude 打残。那只剩 20K token 做实际工作，上下文一会儿就熟了。"

详细说明复制标题链接

1. CLAUDE.md 最佳实践复制标题链接

最优长度： Anthropic 官方建议"简短、人类可读"。HumanLayer 分析和 Bijit Ghosh 的 Medium 指南都汇聚于根文件 80–120 行。臃肿的文件不会从末尾被截断——而是随长度增长全局均匀降质。

应该写什么（五类有效内容）：

1. 构建/测试/lint 命令 —— 单个最高价值的部分。没有它，Claude 会浪费三轮去猜 npm test，而你的仓库用的是 pnpm vitest。
2. 项目结构/代码住哪 —— monorepo 尤为关键。
3. 防止特定错误的约定 —— 不是人格指令（"你是一位高级工程师"）。诊断问题："去掉这条，Claude 会犯什么错？" 没错就删。
4. 有硬性约束的工作流规则 —— 例如"永远不要提交密钥"、"跑单个测试，不要全套"、"用 ES modules，不用 CommonJS"。
5. 指针，不是内容 —— FastAPI 相关 API 约定见 docs/api-conventions.md。不要 @ 导入大文件，那会破坏 progressive disclosure。

层级结构：

• ~/.claude/CLAUDE.md —— 所有 session 生效（个人风格、语言偏好）
• ./CLAUDE.md —— 项目根，提交到 git
• ./CLAUDE.local.md —— 个人项目笔记，加入 .gitignore
• ./subdir/CLAUDE.md —— 只有 Claude 在该子目录工作时才按需加载（monorepo 神器）
• 父 CLAUDE.md 文件在子目录工作时自动加载

@import** 语法示例：**

# 项目约定
构建命令和架构见 @AGENTS.md。

# Claude Code 专有
- 开 PR 前用 `/self-review`
- 用 subagent 调查代码，汇报摘要
- 个人覆盖：@~/.claude/my-project-instructions.md

SwiftUI/FastAPI/Go 个人开发者的具体示例：

# 个人开发 Harness — 多栈

构建、测试、lint 命令见 @AGENTS.md。

## 本工作区的栈
- `apps/ios/` — SwiftUI + SwiftData，Xcode 16，iOS 18 目标
- `apps/api/` — Python 3.12 + FastAPI + uv，async 优先
- `apps/svc/` — Go 1.23 微服务，std library + chi router

## 硬性规则
- 重要：编辑前先读现有文件；不要凭空发明 import
- 任何代码变动后跑 `mise run check`；暴露失败
- 不提交到 `main`；创建 `feat/<topic>` 分支
- 跑单个测试（`pytest tests/test_x.py::test_y`）；编辑期间不跑全套
- 优先用 skill（`.claude/skills/`），不在这里写长篇流程指令

## 不确定时看哪里
- iOS：`apps/ios/docs/swiftdata-patterns.md`
- FastAPI：`apps/api/docs/async-conventions.md`
- Go：`apps/svc/docs/error-handling.md`

大约 25 行。超出约定和指针的内容，都应放进 skill、ADR 或 rules 文件。Claude 犯错时，**让它去更新 **CLAUDE.md——这是会持续复利的反馈循环。

2. Skills（.claude/skills/）复制标题链接

Progressive disclosure 的三层机制：

1. YAML frontmatter —— 启动时始终加载。每个 skill 约 100 token。只有 name + description。
2. SKILL.md** 正文** —— 只有 Claude 判断该 skill 相关时才加载。目标 1,500–2,000 词；Anthropic 文档建议性能优化上限 500 行。
3. scripts/、references/、assets/ —— SKILL.md 引用时通过 Bash/Read 按需加载。脚本是执行的，不是加载进上下文的——这就是为什么捆绑 Python 工具比让 Claude 重新生成等效代码便宜得多。

Skill 列表预算的现实： 每条描述上限 1,536 字符。200K 上下文，1% 预算约 2,000 字符用于名称，剩余约 5,050 字符用于描述正文。32 个 skill 刚好装满，第 33 个开始静默截断。 把 skillListingBudgetFraction 提到 0.02 会从你的消息窗口每次 session 偷走约 3K token。

实际装多少：

• 5–10 个精选项目专属 skill + Superpowers 这一个框架，是个人开发者的最优解。 MindStudio 建议"每个上下文 5–8 个活跃工具"作为强制约束。
• 两周没用的 skill，在 .claude/settings.local.json 里用 skillOverrides 设为 "off" 或 "name-only"。
• 不要投机性安装——每个 skill 的描述 token 永远都在。

一个好的 SKILL.md 长什么样：

---
name: fastapi-endpoint
description: 按项目约定新增一个 FastAPI endpoint。用户要求"加一个路由"、"创建 endpoint"、"暴露 API 方法"时使用。
allowed-tools: Read Edit Write Bash Grep
---

## 何时使用
用户说"加 endpoint"、"暴露路由"、"新 API 方法"时触发。

## 流程
1. 读 `apps/api/app/api/__init__.py` 确认 router 结构。
2. 读同模块中现有的一个 endpoint 作为模式参考。
3. 新增 endpoint，包含：
   - `schemas/` 中的 Pydantic request/response model
   - `api/routes/<resource>.py` 中的 async handler
   - 依赖注入的 `get_db` 用于 DB 访问
4. 在 `tests/api/test_<resource>.py` 中用 `client` fixture 新增 pytest 测试用例。
5. 跑 `pytest tests/api/test_<resource>.py -q`，直到绿灯。

## 参考
- Async 约定：`references/async-patterns.md`
- 错误格式：`references/errors.md`

description 是触发器，不是摘要。 用第三人称，用用户会真实说出的关键词。

Skill vs MCP vs Hook 决策树：

• Skill —— 改变 Claude 怎么思考/工作（约定、流程、领域知识）。按需加载。用于"按我们的模式做 X"。
• MCP —— 给 Claude 访问外部系统的能力（数据库、GitHub API、Sentry、Playwright）。只有没有干净 CLI 替代品时才用。Marmelab 和 Shrivu Shankar 都建议把 Jira、AWS、GitHub 等无状态工具从 MCP 迁移到 bash CLI，只保留 Playwright 这类有状态环境的 MCP。
• Hook —— 保证某件事在生命周期事件时发生，不管 Claude 的推理怎么走。用于：写入时格式化、提交前测试、拦截危险命令。

Roland Huß 的结论："措辞更强硬没用。我试过'必须'、'始终'、'关键'、加粗、大写，都不管用。" 需要保证，用 hook，不是更响亮的 skill。

3. Hooks —— 实用示例复制标题链接

Hook 在 .claude/settings.json（项目）或 ~/.claude/settings.json（全局）中配置，在生命周期事件时触发。

写入时自动格式化（PostToolUse）：

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Write|Edit",
      "hooks": [{
        "type": "command",
        "command": "path=$(jq -r '.tool_input.file_path'); case \\"$path\\" in *.py) ruff format \\"$path\\"; ruff check --fix \\"$path\\";; *.go) gofmt -w \\"$path\\";; *.swift) swiftformat \\"$path\\";; esac",
        "timeout": 15
      }]
    }]
  }
}

拦截危险 bash（PreToolUse）：

#!/usr/bin/env bash
cmd=$(jq -r '.tool_input.command // ""')
for pat in 'rm\\s+-rf\\s+/' 'git\\s+reset\\s+--hard\\s+origin' 'git\\s+push.*--force\\b.*\\bmain\\b'; do
  if echo "$cmd" | grep -Eiq "$pat"; then
    echo "拦截：匹配 '$pat'。用更安全的替代方案，或解释为什么需要这么做。" 1>&2
    exit 2  # exit 2 阻断工具调用并把信息展示给 Claude
  fi
done
exit 0

提交前门控（PreToolUse 匹配 git commit）： 在任何提交落地前跑测试套件或类型检查。

何时该用 hook 而不是 skill： 当你在 CLAUDE.md 里写了"总是做 X"或"从不做 Y"，而 Claude 还是无视了。CLAUDE.md 指令是建议；hook 是基础设施。

4. 在 Claude Code / Codex / OpenCode 之间切换复制标题链接

cc-switch 生态（farion1231/cc-switch）是一个 Tauri 桌面应用，跨 Claude Code、Codex、Gemini CLI、OpenCode、OpenClaw 管理 provider、MCP server、skill 和 prompt，支持一键切换、系统托盘快速切换、统一的 MCP/Skills 面板。也有 CLI 版本（saladday/cc-switch-cli）和 web-server 版本（Laliet/cc-switch-web）用于无头环境。

个人开发者：用两个以上 CLI 并同时切换多个 provider 之前，跳过 cc-switch。 一个 shell alias 加 AGENTS.md 对双终端模式已经够了。

双终端"Plan in Claude，QA in Codex"模式：

# 终端 1：规划 + 实现
cd ~/code/myproject
claude
# > /plan create user-auth feature

# 终端 2：在 git worktree 里做对抗性审查
git worktree add ../myproject-review review
cd ../myproject-review
codex
# > 读 ../myproject/.plans/user-auth.md。
# > 以 staff engineer 视角批评这个方案。什么会出问题？

Codex 天然擅长对抗——给它一个方案，它会找出问题。真实报告显示，这能抓到 Claude 容易漏掉的二阶效应：一个状态变更破坏了两个不相关的页面、一个 onboarding 流假设所有用户都是新用户，等等。

跨工具 AGENTS.md 设置（推荐）：

.
├── AGENTS.md          # 通用：构建命令、约定、架构
├── CLAUDE.md          # 一行：See @AGENTS.md + Claude 专有补充
├── .codex/config.toml # 可选：project_doc_fallback_filenames = ["CLAUDE.md"]
└── .claude/
    ├── skills/
    ├── settings.json  # hooks
    └── commands/

5. OpenSpec + Harness 集成复制标题链接

OpenSpec（Fission-AI/OpenSpec）是一个 TypeScript CLI，安装三个斜杠命令和一个 openspec/ 目录。npm install -g openspec 然后 openspec init。

目录结构：

openspec/
├── project.md           # 项目约定
├── specs/               # 当前事实——已构建的内容
│   └── <capability>/spec.md
└── changes/             # 提议中的变更
    ├── <change-name>/
    │   ├── proposal.md
    │   ├── tasks.md
    │   ├── design.md
    │   └── specs/       # delta specs（ADDED / MODIFIED / REMOVED）
    └── archive/         # 已完成的变更

propose → apply → archive 工作流：

/openspec:proposal add-japanese-localization
# → 在 openspec/changes/add-japanese-localization/ 生成 proposal.md、tasks.md、design.md、delta specs

/openspec:apply
# → 逐条打勾执行 tasks.md，配合 Superpowers 可做 TDD

/openspec:archive
# → 将 delta specs 合并进 openspec/specs/<capability>/spec.md，变更文件夹移入 archive

值得加的 harness 防护措施：

• git commit 的 PreToolUse hook，openspec validate <change-id> --strict 失败则阻断提交
• CLAUDE.md 补充：修改某个 capability 之前，始终先读 openspec/specs/<相关>/spec.md
• 一个 /spec-status 斜杠命令，跑 openspec list && openspec diff <active-change>，让提案与实现的差距保持可见

诚实的注意事项： Marmelab 的分析指出，SDD 在绿地项目上很好用，在大型棕地代码库上会适得其反——规格经常跟不上实现。个人开发者建议：跨多个文件或 session 的 feature 才用 OpenSpec，一行小修和探索性原型直接跳过。

6. Superpowers（obra/superpowers）复制标题链接

作者：Jesse Vincent（GitHub obra，博客 blog.fsck.com，Request Tracker 作者、前 Perl 5 release manager、Keyboardio 联合创始人，现在 Prime Radiant）。Anthropic 官方插件页显示："Made by Jesse Vincent · 安装量 652,113"。

安装方式：

# 在 Claude Code 内
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# 或通过 Anthropic 官方市场
/plugin install superpowers@claude-plugins-official

跨 harness：Codex 官方市场、OpenCode 插件安装、Cursor、Gemini CLI、Copilot CLI、Factory Droid。每个 harness 单独安装。

核心 skill 清单：

个人开发者最有用的 skill（按优先级）：

1. brainstorming —— 任何非平凡 feature 最大的质量杠杆
2. test-driven-development —— 消灭 AI agent 永远"之后再写测试"的陷阱
3. systematic-debugging —— 把 print-debug-and-guess 的循环替换成方法论
4. writing-plans —— 生成可以在新 session 里继续的方案，每个任务都有明确复选框
5. using-git-worktrees —— 随时开侧实验而不破坏主线

不该装 Superpowers 的情况： 快速一次性原型、探索阶段。纪律开销在你不打算保留代码时是净负担。Superpowers 适合你打算维护的代码。

7. 上下文管理复制标题链接

心理模型： Claude 的上下文窗口是被 system prompt、CLAUDE.md、自动记忆、加载的 skill 正文、工具定义、对话历史、文件内容共享的有限资源。性能在窗口满之前就开始下降——这叫"上下文腐烂"。

实用规则：

• /context 随时查看 token 去哪了
• /clear 在不相关任务之间。新任务 = 新 session。Anthropic 工程博客明确："开始新任务时，也应该开始新 session。"
• 在约 60% 上下文时主动跑 ****/compact，不要等到 95% 触发自动压缩。加聚焦提示：/compact 只关注 API 变更和未完成的 TODO。每次压缩有信息损失；多次压缩快速退化。
• **高风险下一步不要用 **/compact ——而是让 Claude 把计划和进度转储到 .md，然后 /clear，新 session 读这个 .md（"Document & Clear" 模式）。
• Subagent 做调研 —— "用 subagent 调查我们的 auth 系统如何处理 token 刷新" 让主对话保持干净，因为 subagent 在独立上下文窗口里运行，只汇报摘要。
• 不要在 CLAUDE.md 里 @ 导入大文档——整个文件每次 session 都会加载。用路径引用代替。
• 不要为了"以防万用"安装 skill——每个描述永远消耗 token。
• Shrivu Shankar 的 MCP 规则： "超过 20K token 的 MCP，你就是在打残 Claude。" 把无状态集成迁移到按需调用的 bash CLI。

8. 反模式清单复制标题链接

针对 iOS/FastAPI/Go 个人开发者的分阶段建议复制标题链接

第一阶段 —— 第一天（30 分钟）：

1. 创建最小 AGENTS.md（每个栈的构建/测试/lint 命令，项目结构图，约定）。目标 30–80 行。
2. 创建精简 CLAUDE.md：See @AGENTS.md 加上 3–5 条 Claude 专有注意事项。
3. 加 .claude/settings.json，两个 hook：(a) PostToolUse 对 .py/.go/.swift 写入时格式化，(b) PreToolUse 拦截 rm -rf /、git push --force main、git reset --hard origin。
4. claude --version 确认 v2.1.59+ 以使用自动记忆。

第二阶段 —— 第一周（增量 skill）：

1. 安装 Superpowers：/plugin marketplace add obra/superpowers-marketplace && /plugin install superpowers@superpowers-marketplace。
2. 只为你已经发现 Claude 犯了两次错误的地方写 2–3 个项目专属 skill。好的第一批候选：add-fastapi-endpoint、add-swiftdata-model、add-go-handler。
3. 如需跨 session 记忆，加 claude-mem：npx claude-mem install。

第三阶段 —— 项目认真起来后（完成第一个 feature 后）：

1. npm install -g openspec && openspec init。任何跨越超过一个文件或 session 的 feature 用 /openspec:proposal。
2. 开第二个终端跑 codex，对高风险变更做对抗性方案审查；或安装 /codex Claude 插件通过 ExitPlanMode hook 自动化。
3. 给 git commit 加 PreToolUse hook，跑 openspec validate <active-change> --strict 和 mise run check。

第四阶段 —— 真的在用多工具时（>2 个 CLI）：

1. 安装 cc-switch 跨工具管理 provider 和 skill。
2. 如果不想维护 AGENTS.md，在 Codex 里设 project_doc_fallback_filenames = ["CLAUDE.md"]。

需要调整建议的信号：

• /context 显示第一条消息前 skill/工具已用超 40% → 删 skill，把 MCP 迁移到 CLI
• Claude 反复忽略某条 CLAUDE.md 规则 → 这条规则属于 hook，不属于 markdown
• 一个任务跑了两次以上 /compact → 任务太大；拆成垂直切片
• 一个自定义斜杠命令很少被用 → 删掉；主循环应该是普通语言指令
• 同一段话复制粘贴进 prompt 超过三次 → 做成 skill

注意事项复制标题链接

1. 工具更新很快。 Claude Code v2.1.140（2026 年 5 月）引入了 async hooks、agent hooks、/goal 命令和重要的上下文管理变更。部分特性（如 skillListingBudgetFraction、CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD）可能随版本变化；以 code.claude.com/docs 当前文档为准。
2. "32 个 skill 上限"是默认值，不是硬限制。 它是 skillListingBudgetFraction × 上下文窗口 ÷ 平均描述长度 的函数。调整比例或在 Sonnet 4.6 的 1M 上下文方案上跑，数字会变。
3. Spec 驱动开发有收益递减。 Marmelab 经验和 OpenSpec 文档都承认 SDD 在成熟棕地代码库上效果有限。用在需求不清晰或需要干系人审查意图的地方；快速探索时跳过。
4. 大多数来源反映的是个人工作流，不是基准测试结果。 Shrivu Shankar 的"20K token MCP"、marmelab 的"~400K 相关性上限"都是重度用户的实地报告，不是同行评审研究。定性方向有充分佐证；具体阈值作为起点，在自己的设置里验证。
5. 跨 agent 生态仍在整合。 AGENTS.md 采用已经很广，但工具专有扩展（Codex 的 agents/openai.yaml、Claude 的 context: fork subagent、Cursor 缺乏原生 skill 发现）不互相迁移。坚持使用可移植的 SKILL.md 核心（frontmatter + markdown + 可选脚本），你能在 Claude Code、Codex、OpenCode、Gemini CLI 之间获得约 95% 的可移植性。