5.2 Claude Code 实践指南
引言：Harness 的六个入口
Claude Code 不只是"一个 AI 编程助手"——它是一个完整的 Harness 工程平台，提供了六个入口让你注入约束和控制。
六个 Harness 入口
| 入口 | 作用 | 典型场景 |
|---|---|---|
| CLAUDE.md | 项目级指令文件，Agent 启动时自动加载 | 编码规范、架构约定、禁止操作 |
| Commands | 自定义斜杠命令，复用工作流 | /review、/deploy、/test |
| Hooks | 事件触发的自动化脚本 | Pre-commit 检查、Post-edit 验证 |
| Skills | 可分享的能力模块 | 代码审查、安全扫描、文档生成 |
| MCP Servers | 外部工具和数据源的标准化接入 | 数据库查询、API 调用、CI/CD |
| Permissions | 操作权限控制 | 文件访问、命令执行、网络请求 |
起手三板斧
第一斧：写好 CLAUDE.md
CLAUDE.md 是最重要的 Harness 入口。每个项目都应该有一个。
markdown
# 项目约定
- 使用 TypeScript，禁止 any
- 测试框架：Vitest
- 提交信息格式：conventional commits
- 禁止修改 .env 文件
- 所有 API 调用必须经过 src/api/ 层好的 CLAUDE.md 的特征：具体、可执行、不含歧义。不是"注意代码质量"，而是"函数不超过 50 行"。
第二斧：配置 Hooks
Hooks 让你在关键节点自动执行检查，而不是依赖 Agent 自律。
常用 Hooks：
PreToolUse：Agent 调用工具前拦截（如禁止删除文件）PostToolUse：Agent 调用工具后验证（如检查输出格式）Notification：关键操作的通知（如生产环境变更告警）
第三斧：分层权限
不要全开也不要全锁——按风险等级分层授权。
- 允许：读取源码、运行测试、查看日志
- 确认：修改文件、安装依赖、创建分支
- 禁止：删除生产数据、修改 CI 配置、推送 main 分支
诊断指南：问题出在哪一层？
当 Agent 出问题时，首先判断是上下文问题还是 Harness 层问题：
| 症状 | 可能原因 | 排查方向 |
|---|---|---|
| Agent 反复犯同类错误 | CLAUDE.md 指令不够具体 | 优化 CLAUDE.md |
| Agent 修改了不该改的文件 | 权限控制缺失 | 添加 Permission 规则 |
| Agent 输出格式不对 | 工具返回结构未约束 | 添加输出校验 Hook |
| Agent 调用错误的工具 | 工具描述不够清晰 | 优化工具/MCP Server 描述 |
| Agent 上下文丢失 | 长任务中信息衰减 | 检查上下文管理策略 |
反馈速度层级
越早发现问题，修复成本越低。 这是软件工程的铁律，对 Agent 同样适用。
| 层级 | 延迟 | 典型机制 | 发现的问题 |
|---|---|---|---|
| Hook | 毫秒级 | PreToolUse 拦截 | 越权操作、非法参数 |
| Pre-commit | 秒级 | Git hook 自动检查 | 格式错误、类型错误 |
| CI | 分钟级 | 自动化流水线 | 测试失败、构建错误 |
| Review | 小时级 | 人工或 Agent 审查 | 逻辑错误、架构偏离 |
最佳实践
尽量把检查往左移。能在 Hook 拦截的，不要留到 Pre-commit；能在 Pre-commit 发现的，不要留到 CI。
每一个左移的检查点，都在为 Agent 缩小自由度——这正是 Harness 的本质。
本节小结
📌 本节核心要点
- Claude Code 提供六个 Harness 入口：CLAUDE.md、Commands、Hooks、Skills、MCP Servers、Permissions
- 起手三板斧：写好 CLAUDE.md → 配置 Hooks → 分层权限
- 诊断问题时先区分上下文问题 vs Harness 层问题
- 反馈越早越好：Hook(ms) → Pre-commit(s) → CI(min) → Review(hours)
思考题
- 你的 CLAUDE.md 目前写了什么？有没有"注意代码质量"这类无法执行的指令？
- 如果要给当前项目添加三个 Hook，你会选哪些事件？每个 Hook 做什么检查？
- 你的团队中，Agent 的反馈信号目前主要在哪一层？怎么向左移一层？
下一节预告
单个 Agent 的 Harness 建好了，多个 Agent 怎么协作？下一节谈多 Agent 协作模式。