Claude Code 工程化实践：从 CLAUDE.md 到 Subagent 的完整方法论

ccAiHub
5 阅读8分钟

Claude Code 工程化实践：从 CLAUDE.md 到 Subagent 的完整方法论

本文适合已经上手 Claude Code 但感觉"没发挥出全部实力"的用户。从 CLAUDE.md 契约设计、上下文管理、Prompt 缓存原理到 Subagent 隔离，这些是我实际踩坑后沉淀的工程级经验。

写在前面

AI 编程助手已经泛滥，但真正能在生产环境跑起来的少之又少。Claude Code 是我用过上下文管理最扎实、工程化程度最高的工具之一。但光会用不够，它的天花板取决于你怎么配置、怎么引导它。

这篇文章把我踩过的坑和积累的方法都写出来了，建议收藏慢慢读。

💡 如果你想直接用上 Claude API / Claude Code 的能力，推荐访问 ccAiHub.com ——提供稳定的 Claude API 接入、多模型聚合，支持国内直连，适合个人开发者和团队快速接入。

1. CLAUDE.md：你和 Claude 的协作契约

CLAUDE.md 不是团队文档，也不是知识库，它是每次会话都必须成立的约定。

一开始甚至可以什么都不写。先用起来，等你发现自己老是在重复同一件事，再补进去。

应该放什么

  • 怎么 build、怎么 test、怎么跑（最核心）
  • 关键目录结构与模块边界
  • 代码风格和命名约束
  • 那些不明显的环境坑
  • 绝对不能干的事（NEVER 列表）
  • 压缩时必须保留的信息（Compact Instructions）

不该放什么

  • 大段背景介绍
  • 完整 API 文档
  • 空泛原则，如"写高质量代码"
  • Claude 通过读仓库即可推断的显然信息
  • 大量背景资料和低频任务知识（这些放 Skills）

快速追加方式：输入 # 可以把当前对话里的内容直接追加进 CLAUDE.md，或直接告诉 Claude「把这条加到项目的 CLAUDE.md 里」。

2. Skills：封装可复用的工作流，不是 Prompt 模板

Skills 是 CLAUDE.md 的延伸，用来封装那些「在特定场景下固定的执行路径」。

三种 Skill 类型

类型一：流程执行型（封装固定步骤）

---
name: migrate-config
description: Migrate config schema. Run only when explicitly requested.
disable-model-invocation: true
---

## Steps
1. Backup: `cp ~/.config/kaku/config.toml ~/.config/kaku/config.toml.bak`
2. Dry run: `kaku config migrate --dry-run`
3. Apply: remove `--dry-run` after confirming output
4. Verify: `kaku doctor` all pass

类型二：领域专家型（封装决策框架）

---
name: runtime-diagnosis
description: Use when kaku crashes, hangs, or behaves unexpectedly at runtime.
---

## Decision Matrix
| Symptom | First Check |
|---|---|
| Crash on startup | doctor output → Lua syntax error |
| Rendering glitch | GPU backend / terminal capability |

描述符要写短

每个启用的 Skill 描述符常驻上下文，差距很大：

# 低效（~45 tokens）
description: |
  This skill helps you review code changes in Rust projects.
  It checks for common issues like unsafe code, error handling...

# 高效（~9 tokens）
description: Use for PR reviews with focus on correctness.

使用频率策略：

  • 高频（>1次/会话）→ 保持 auto-invoke，优化描述符
  • 低频（<1次/会话）→ disable-auto-invoke，手动触发
  • 极低频（<1次/月）→ 移除 Skill，改为 AGENTS.md 中的文档

3. 工具设计：让 Claude 少选错的关键

给 agent 用的工具和给人写的 API 不是一回事。重点不是功能堆得多完整，而是让它更容易用对。

维度好工具坏工具
名称jira_issue_get, sentry_errors_searchquery, fetch, do_action
参数issue_key, project_id, response_formatid, name, target
返回与下一步决策直接相关的信息一堆 UUID、内部字段、原始噪声
错误信息包含修正建议仅返回 opaque error code

实用设计原则：

  • 名称前缀按系统分层：github_pr_*、jira_issue_*
  • 对大响应支持 response_format: concise / detailed
  • 错误响应要教模型如何修正
  • 避免 list_all_* 让模型自行筛选

Claude Code 内部工具演进的教训

AskUserQuestion 工具的演进是个经典案例：

  • 第一版：给已有工具加 question 参数 → Claude 大多数时候直接忽略继续跑
  • 第二版：要求 Claude 输出特定 markdown 格式 → 经常"忘了"按格式写
  • 第三版：独立的 AskUserQuestion 工具 → 调用即暂停，没有歧义，最稳定

结论：既然要 Claude 停下来问一句，就直接给它一个专门的工具。

4. Hooks：把关键逻辑收回到确定性流程

Hooks 的价值不是"自动运行脚本"，而是把不能交给 Claude 临场发挥的事，重新收回到确定性流程。

格式化要不要跑、保护文件能不能改、任务完成后要不要通知——这些事不要指望 Claude 每次都自己记得。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "pattern": "*.rs",
        "hooks": [
          {
            "type": "command",
            "command": "cargo check 2>&1 | head -30",
            "statusMessage": "Running cargo check..."
          }
        ]
      }
    ],
    "Notification": [
      {
        "type": "command",
        "command": "osascript -e 'display notification \"Task completed\" with title \"Claude Code\"'"
      }
    ]
  }
}

⚠️ 注意：限制输出长度（| head -30），避免 Hook 输出污染上下文。

三层叠加最稳定

层级职责
CLAUDE.md声明"提交前必须通过测试和 lint"
Skill告诉 Claude 顺序、如何看失败、如何修复
Hook对关键路径执行硬性校验，必要时阻断

三样少任何一层都会有漏洞。只写 CLAUDE.md 规则，Claude 经常当没看见；只靠 Hooks，细节判断又做不了。

5. Subagents：隔离才是核心价值，不是并行

Subagent 最大的价值不是"并行"，而是隔离——扫代码库、跑测试、做审查这类会产生大量输出的事，塞进主线程很快就把有效上下文挤没了。

配置要点：

  • tools / disallowedTools：限定能用什么工具
  • model：探索任务用 Haiku 省成本，重要审查用 Opus
  • maxTurns：防止跑飞
  • isolation: worktree：需要动文件时隔离文件系统

常见反模式：

  • 子代理权限和主线程一样宽，隔离没有意义
  • 输出格式不固定，主线程拿到没法用
  • 子任务之间强依赖，频繁共享中间状态

6. Prompt Caching：Claude Code 架构的核心

这块很多教程没展开讲，但它直接影响成本结构和设计取舍。

"Cache Rules Everything Around Me"——Claude Code 的整个架构都是围绕 Prompt 缓存构建的。

为缓存设计的 Prompt 顺序

1. System Prompt    → 静态，锁定
2. Tool Definitions → 静态，锁定
3. Chat History     → 动态，在后面
4. 当前用户输入     → 最后

破坏缓存的常见陷阱

  • 在静态系统 Prompt 中放入带时间戳的内容
  • 非确定性地打乱工具定义顺序
  • 会话中途增删工具

动态信息怎么传？ 别动系统 Prompt，放到下一条消息里传进去。Claude Code 自己用 <system-reminder> 标签，系统 Prompt 不动，缓存不会被打坏。

会话中途不要切换模型

Prompt 缓存是模型唯一的。已经和 Opus 对话了 100K tokens，切换到 Haiku 实际上比继续用 Opus 更贵，因为要为 Haiku 重建整个缓存。

7. 验证闭环：没有 Verifier 就没有工程上的 Agent

「Claude 说完成了」没有任何工程价值。你得能知道它做没做对、出了问题能退回来、过程还能查。

Verifier 的层级

层级工具
最低层命令退出码、lint、typecheck、unit test
中间层集成测试、截图对比、contract test、smoke test
更高层生产日志验证、监控指标、人工审查清单

我自己的判断标准：如果一个任务你都说不清楚「Claude 怎么才算做对了」，那它大概率不适合直接丢给 Claude 自动完成。

8. 高频命令速查

# 上下文管理
/context   # 查看 token 占用结构
/clear     # 清空会话（同一问题被纠偏两次以上就重来）
/compact   # 压缩但保留重点
/memory    # 确认哪些 CLAUDE.md 真的被加载了

# 会话连续性
claude --continue               # 恢复当前目录最近会话
claude --resume                 # 打开选择器恢复历史会话
claude --continue --fork        # 从已有会话分叉，同一起点不同方案
claude -p "prompt"              # 非交互模式，接入 CI/脚本
claude -p --output-format json  # 结构化输出，便于脚本消费

几个不常见但很好用的命令：

  • /simplify：对刚改完的代码做三维检查（复用、质量、效率），发现问题直接修掉
  • /rewind：回到某个会话 checkpoint 重新总结，适合 Claude 已沿错误路径探索太久
  • /btw：不打断主任务的侧问题，适合单轮旁路问答
  • /insight：让 Claude 分析当前会话，提炼哪些内容值得沉淀到 CLAUDE.md
  • 双击 ESC：回溯到上一条输入重新编辑，不用重新开会话

对话历史本地存储： 所有会话记录存放在 ~/.claude/projects/ 下，每个会话是一个 .jsonl 文件。

grep -rl "关键词" ~/.claude/projects/

总结：Claude Code 工程化的核心思路

  1. CLAUDE.md 是协作契约，只放每次都成立的事
  2. Skills 封装固定执行路径，描述符要短
  3. 工具设计 重点是让模型容易用对，而不是功能齐全
  4. Hooks 把不能临场发挥的事收回到确定性流程
  5. Subagents 核心价值是隔离，不是并行
  6. Prompt 缓存 是成本控制的关键，别随意破坏前缀
  7. 验证闭环 没有 Verifier 就没有工程上的 Agent

关于 Claude API 接入

如果你读到这里，说明你对 Claude Code 的工程化用法有真实需求。

不管是个人开发者想集成 Claude API，还是团队需要稳定的多模型聚合接入，推荐试试 ccAiHub.com：

  • ✅ 支持 Claude 全系列模型（Opus / Sonnet / Haiku）
  • ✅ 国内直连，无需代理
  • ✅ 标准 OpenAI 兼容接口，无缝切换
  • ✅ 按量计费，适合个人和小团队
  • ✅ 支持多模型聚合，一个 Key 调用多种模型

访问 ccAiHub.com 注册即可开始使用。

如果这篇文章对你有帮助，欢迎点赞收藏，也欢迎在评论区分享你的 Claude Code 使用心得。

avatar
文章
阅读
粉丝