66% 的开发者反馈 AI 代码"差不多对但不完全对"，45% 的人说 debug AI 代码比自己写还慢。这些数据在遵循结构化实践的开发者身上显著下降。原因不是 prompt 技巧，而是上下文工程——给 AI 提供正确信息的能力。
核心心智模型：你是上下文工程师
"最好的 prompt 工程师"不是在 prompt 里写得最漂亮的人，而是最善于控制 AI 获得什么信息的人：
- 哪些文件放进上下文
- 哪些文件排除在外
- 什么时候清理上下文
- 何时开新 Session
Stage 1：CLAUDE.md 不是文档，是基础设施
2026 年社区共识：CLAUDE.md 的重要性等同于 .gitignore。
写什么、不写什么：
| ✅ 写进去 | ❌ 不用写 |
|---|---|
| Claude 无法从代码推断的 bash 命令 | Claude 通过读代码就能知道的东西 |
| 与默认不同的代码风格规则 | 语言的标准约定 |
| 测试要求和测试运行器 | 频繁变动的信息 |
| 仓库约定（分支命名、PR 规范） | 详细 API 文档（放链接） |
| 架构决策和环境特殊配置 | 逐文件的代码库说明 |
| 常见坑和非显而易见的行为 | "写干净的代码"这类废话 |
黄金规则：对每一行问自己"删掉这行，Claude 会犯错吗？"不会的话就删。保持 50-100 行，用 @import 引用详细文档。
CLAUDE.md 层级：
~/.claude/CLAUDE.md # 全局，所有项目生效
/project/CLAUDE.md # 项目级，当前项目生效
/project/frontend/CLAUDE.md # 模块级，在 frontend/ 下生效
Claude Code 加载时合并所有层级，子目录规则优先级更高。
Stage 2：.claudeignore 节省 Token
.claudeignore 的作用和 .gitignore 一样——排除不需要放进上下文的文件：
# .claudeignore
node_modules/
dist/
build/
.next/
*.log
coverage/
.nyc_output/
*.min.js
*.min.css
每个 Claude Code 读取的文件都消耗上下文，排除无关文件可以：
- 让 Claude 更聚焦于真正相关的代码
- 减少 token 消耗
- 降低上下文污染（大量无关代码干扰判断）
Claude Code 比 Cursor 少用 5.5x token 的主要原因之一，就是更好的上下文控制。
Stage 3：任务边界控制——防止蝴蝶效应
蝴蝶效应是 Agentic 编程最严重的失败模式：早期的一个误解，被 Agent 叠加五层逻辑后，等你发现问题已经需要推翻重写了。
精确 vs 模糊 Prompt 对比：
| 模糊（引发蝴蝶效应） | 精确（防止蝴蝶效应） |
|---|---|
| "给 foo.py 加测试" | "为 foo.py 写测试，覆盖用户已登出时的边界情况，不用 mock" |
| "加个日历组件" | "参考 HotDogWidget.php 的模式，按同样结构实现日历组件" |
| "修复登录 bug" | "session 超时后登录失败，检查 src/auth/ 的 token refresh 逻辑，先写失败测试再修复" |
采访模式（大功能必用）：
在开始实现之前，先采访我来定义需求。
问我：
1. 这个功能解决什么问题？
2. 关键用户场景有哪些？
3. 有哪些约束（性能/安全/兼容性）？
4. 哪些现有代码最相关？
记录答案，然后给我看功能规格，确认后再开始实现。
确认规格后，开一个新 Session 来实现。新 Session 的上下文干净，完全聚焦执行。
Stage 4：Plan Mode — 先想再做
Plan Mode（Shift+Tab 两次切换）把研究和实现分开：
- Plan Mode 开：Claude 只分析、规划，不写代码
- Plan Mode 关：Claude 开始实现
何时用 Plan Mode：
- 对实现方法不确定时
- 改动横跨多个文件
- 对代码库不熟悉
- 避免"解决了错误问题"的情况
不需要 Plan Mode 的场景：
- 明确的小改动（修 typo、改一个变量名）
- 你已经非常清楚解决方案
Stage 5：Session 卫生——上下文管理
最重要的一条：每个任务开新 Session。
长 Session 质量下降是已知问题——在 r/ChatGPTCoding 被大量讨论。Session 积累的错误尝试和纠正信息会降低后续回答的质量。
上下文管理命令速查：
| 命令 | 时机 | 效果 |
|---|---|---|
/clear | 任务之间 | 清空整个上下文 |
/compact | 上下文用到 70% 时 | 压缩总结，保留关键信息 |
/compact 专注xxx | 特定任务阶段 | 定向压缩，保留指定内容 |
Esc + Esc | 中途恢复 | 回到检查点，可选总结 |
两次纠正原则：如果你已经就同一个问题纠正了两次，上下文已经被失败尝试污染。执行 /clear 用更好的 prompt 重新开始，几乎总是比继续当前 Session 更高效。
批量审查，不要逐条审批：
不要在每次 Agent 改动后都弹出确认。
让 Claude 连续完成相关的一系列改动，
最后用 git diff 我来批量审查。
Stage 6：Subagent 保持主上下文干净
问题：Agent 搜索代码库时会读大量文件，这些全进了主 Session 的上下文。
解决方案：Subagent 在独立的上下文窗口里做研究，只把摘要返回给主 Session。
【搜索任务 - Subagent 模式】
在独立 Session 里搜索整个 src/ 目录：
找出所有使用 createUser() 这个已废弃函数的地方
只返回文件路径和行号，不要把文件内容带回来
这样可以节省 40%+ 的输入 token，主 Session 保持干净。
Stage 7：多 Agent 并行——真正的 10x
Agent 团队让多个 Claude 实例并行工作，但需要明确规则：
按任务分配模型：
| 任务类型 | 推荐模型 | 原因 |
|---|---|---|
| 代码库探索 | claude-haiku | 快、便宜，适合读文件总结 |
| 实现新功能 | claude-sonnet | 推理和代码生成平衡 |
| 复杂重构 | claude-opus | 跨文件改动需要最强推理 |
| 测试生成 | claude-sonnet | 速度和质量的平衡 |
| 安全 Review | claude-opus | 安全审查需要最强理解力 |
通信规则（放进 CLAUDE.md）：
## Agent 团队协作规则
- 每个 Agent 只负责指定的文件范围，不越界
- 改动前先检查其他 Agent 是否在处理同一文件
- 通过共享文件（如 agent-status.md）通报进度
- 有冲突时暂停并报告，不要自行决策Monorepo 的嵌套 CLAUDE.md：
/project/CLAUDE.md # 根级通用规则
/project/frontend/CLAUDE.md # Frontend 专属规则（React 规范等）
/project/backend/CLAUDE.md # Backend 专属规则（API 规范等）
/project/infra/CLAUDE.md # Infra 专属规则（安全限制等）
每个 Agent 进入对应目录时，自动加载对应的规则集。
Stage 8：Hooks——确定性的自动化护栏
Hooks 在特定生命周期自动执行脚本，与 CLAUDE.md 规则不同——Hooks 每次都执行，不依赖模型的判断。
// .claude/settings.json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{
"type": "command",
"command": "npm run lint --fix"
}]
}
],
"PreToolUse": [
{
"matcher": "Write",
"hooks": [{
"type": "command",
"command": "test ! -f '$CLAUDE_TOOL_INPUT_PATH' || grep -q 'production' '$CLAUDE_TOOL_INPUT_PATH' && echo 'ERROR: 不能写入生产配置文件' && exit 1 || exit 0"
}]
}
]
}
}Hooks 的典型用途：
- 每次编辑后自动 lint
- 阻止写入受保护文件（生产配置、密钥文件）
- 发送通知（长任务完成后 Slack 提醒）
- 自动运行测试
验证驱动开发：给 Claude 自我检查的标准
单一最高杠杆实践：给 Claude 验证标准，而不只是任务描述。
实现 validateEmail 函数：
- user@example.com → true
- invalid → false
- user@.com → false
- missing@tld → false
实现后运行测试，确认所有用例通过再汇报完成。
给了验证标准的任务，Claude 完成质量显著高于没有标准的。
委托 vs 监督矩阵
Anthropic 2026 开发者报告数据：开发者 AI 辅助 60% 的工作，但只有 0-20% 完全委托。
| 可以完全委托 | 需要监督 |
|---|---|
| 测试生成、样板代码、脚手架 | 认证流程、支付逻辑、数据变更 |
| 代码迁移、重命名、格式化 | 安全关键重构、API 合约 |
| 文档注释、README | 安全文档、合规文档 |
| Lint 错误、类型错误 | 竞态条件、数据损坏、认证 bug |
| CI 配置、Dockerfile | 生产部署、数据库 Schema 变更 |
AI 生成代码有 1.5-2x 的安全漏洞率，安全关键路径永远要人工审查。
来源：morphllm.com Claude Code 最佳实践指南 | Anthropic 官方最佳实践文档 | 整理：ClaudeEagle