10 - 实战经验与工程布局

Kaku Terminal 项目经验

春节放假时用 Claude Code 做了一个开源 terminal 项目（Rust + Lua + AI 能力）。混合语言加上自定义配置系统，暴露出不少典型的 agent 协作问题。

doctor 命令

Claude Code 调用的都是真实的 shell、git、package manager 和本地配置。只要有一层不透明，它就只能开始猜，一猜可靠性就掉。

解决方案：在 CLI 里加个 doctor 命令，把环境状态、依赖和配置情况先统一收上来，输出一份结构化的健康报告。Claude Code 开始做事前先跑一次 doctor，省掉很多”环境没搞清楚就开干”的问题。

如果 CLI 本身就有 init、config、reset 这类语义清楚的子命令，Claude Code 用起来会稳不少。先把状态收敛住，再暴露编辑入口，顺序一反过来就很容易乱。

混合语言 Hooks

两套语言、两套检查，适合用 Hooks 按文件类型分别触发：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "pattern": "*.rs",
        "hooks": [{
          "type": "command",
          "command": "cargo check 2>&1 | head -30",
          "statusMessage": "Checking Rust..."
        }]
      },
      {
        "matcher": "Edit",
        "pattern": "*.lua",
        "hooks": [{
          "type": "command",
          "command": "luajit -b $FILE /dev/null 2>&1 | head -10",
          "statusMessage": "Checking Lua syntax..."
        }]
      }
    ]
  }
}

每次编辑完立刻知道有没有编译错误，比”跑了一堆才发现最开始就挂了”舒服得多。

推荐工程布局

想给自己项目配一套比较完整的 Claude Code 工程布局，可以参考这个结构，按需裁剪：

Project/
├── CLAUDE.md
├── .claude/
│   ├── rules/
│   │   ├── core.md
│   │   ├── config.md
│   │   └── release.md
│   ├── skills/
│   │   ├── runtime-diagnosis/   # 统一收集日志、状态和依赖
│   │   ├── config-migration/    # 配置迁移回滚防污
│   │   ├── release-check/       # 发布前校验、smoke test
│   │   └── incident-triage/     # 线上故障分诊
│   ├── agents/
│   │   ├── reviewer.md
│   │   └── explorer.md
│   └── settings.json
└── docs/
    └── ai/
        ├── architecture.md
        └── release-runbook.md

多项目管理：把稳定的个人基线放在 ~/.claude/，各项目的差异放在项目级 .claude/，通过同步脚本分发，不同项目之间不会互相污染。

健康检查 Skill

基于六层框架整理的开源 Skill，可以一键检查你的 Claude Code 配置状态：

npx skills add tw93/claude-health

装好之后跑 /health，自动识别项目复杂度，对 CLAUDE.md、rules、skills、hooks、allowedTools 和实际行为模式各跑一遍检查，输出优先级报告：需要立刻修 / 结构性问题 / 可以慢慢做。

三个阶段

用 Claude Code 大概会经历三个阶段：

1. 当 ChatBot 用 — 问问题、要代码片段
2. 当 Copilot 用 — 让它写代码、改代码、跑测试
3. 当 Agent 用 — 让它在约束下自主完成整个任务

到了第三阶段，关注点会悄悄变掉——从”这个功能怎么用”变成”怎么让 agent 在约束下自己跑起来”。

---

Prev: 09 - CLAUDE.md 写法 | Next: 系列目录