@tom_doerr：基于多智能体团队和 TDD 的 Claude Code 脚手架 https://github.com/alinaqi/claude-bootstrap…

基于多智能体团队与 TDD 的 Claude Code 脚手架 https://t.co/TtKtX1u3l3 https://t.co/BOlVJM6lhD — # alinaqi/claude-bootstrap 来源：https://github.com/alinaqi/claude-bootstrap # Maggy > 从强约定的 Claude Code 初始配置，进化为自主 AI 工程平台。 Maggy 最初是专为 Claude Code 设计的项目初始化系统 —— 内置技能、TDD 钩子、质量门禁。如今它已演变为完整的自主工程指挥中心：支持交互式聊天与会话接管、容器化多智能体编排、跨机器 P2P 网格网络同步、AI 优先的任务分诊、竞品情报以及流程分析。那些确保 AI 生成代码保持简洁、安全、可验证的安全护栏依然是基石 —— 但现在它们驱动着端到端的自主工程工作流。 v5.0.0 —— 交互式聊天（--resume 会话接管）、Polyphony（容器隔离的多智能体编排）、P2P Mesh（跨机器会话同步）、自动引导、分组仪表板导航。 ## 核心理念 ┌────────────────────────────────────────────────────────────────┐ │ 基于 STOP 钩子的 TDD 循环 │ │ ─────────────────────────────────────────────────────────────│ │ Stop 钩子在 Claude 每次响应后运行测试。 │ │ 失败结果自动反馈。Claude 持续迭代直至测试通过。 │ │ 原生 Claude Code 基础设施 —— 无需插件。 │ ├────────────────────────────────────────────────────────────────┤ │ 始终测试先行 │ │ ─────────────────────────────────────────────────────────────│ │ 新功能：编写测试 → 观察失败 → 实现代码 → 测试通过 │ │ 修 Bug：发现测试盲区 → 编写失败测试 → 修复代码 → 测试通过 │ │ 未经失败测试验证的代码绝不交付。 │ ├────────────────────────────────────────────────────────────────┤ │ 以简洁为目标 │ │ ─────────────────────────────────────────────────────────────│ │ 单函数 ≤20 行 │ 单文件 ≤200 行 │ 最多 3 个参数 │ │ 通过 .claude/rules/ 中的 paths: frontmatter 强制执行。 │ ├────────────────────────────────────────────────────────────────┤ │ 默认安全 │ │ ─────────────────────────────────────────────────────────────│ │ 代码中不含密钥 │ 对 .env 文件设置权限拒绝规则 │ │ 依赖扫描 │ Pre-commit 钩子 │ CI 强制检查 │ ├────────────────────────────────────────────────────────────────┤ │ 默认智能体团队 │ │ ─────────────────────────────────────────────────────────────│ │ 每个项目均作为协调一致的 AI 智能体团队运行。 │ │ 智能体定义使用规范的 frontmatter：tools、model、 │ │ maxTurns、effort、disallowedTools。 │ ├────────────────────────────────────────────────────────────────┤ │ 条件规则 │ │ ─────────────────────────────────────────────────────────────│ │ .claude/rules/ 中的规则根据文件路径激活。 │ │ 仅在编辑 .tsx 文件时加载 React 规则。 │ │ 仅在编辑 .py 文件时加载 Python 规则。 │ │ 节省 Token。减少干扰。提供更精准的指导。 │ └────────────────────────────────────────────────────────────────┘ ## 快速开始 bash # 克隆并安装（可克隆到任意目录） git clone https://github.com/alinaqi/claude-bootstrap.git cd claude-bootstrap && ./install.sh # 在任意项目目录中 claude > /initialize-project Claude 将执行以下操作： 1. 验证工具 - 检查 gh、vercel、supabase CLI 2. 提出问题 - 语言、框架、是否 AI 优先、数据库、图分析级别 3. 设置仓库 - 创建或连接 GitHub 仓库 4. 创建结构 - 技能、规则、设置、安全、CI/CD、规范、待办事项 5. 复制 settings.json - 预配置的权限与 Stop 钩子 6. 生成 CLAUDE.md - 包含用于模块化加载技能的 @include 指令 7. 生成 CLAUDE.local.md - 供开发者私有覆盖的模板 8. 启动智能体团队 - 部署 Team Lead + Quality + Security + Review + Merger + Feature 智能体 ## 跨工具兼容性（Claude + Kimi + Codex） Maggy 兼容 Claude Code、Kimi CLI 和 OpenAI Codex CLI。三者均使用相同的 SKILL.md 格式。 | 特性 | Claude Code | Kimi CLI | Codex CLI | |———|———––|–––––|———–| | 技能 | .claude/skills/ | .kimi/skills/（同时读取 .claude/） | .codex/skills/ | | 项目指令 | CLAUDE.md | （使用技能） | AGENTS.md | | 钩子配置 | settings.json | config.toml | config.toml | install.sh 会自动检测已安装的工具，并将技能安装到所有工具中。 /sync-agents 可按需跨工具同步项目配置。 bash # 安装工具 curl -L code.kimi.com/install.sh | bash # Kimi npm i -g @openai/codex # Codex # 重新安装以识别新工具 cd maggy && ./install.sh # 在任意项目中，同步跨工具配置 claude > /sync-agents ## 跨智能体协同智能 当安装多个 AI CLI 工具时，Maggy 可实现它们之间的智能协作。 ### Codex 自动审查（Stop 钩子） 测试通过后，Codex 会自动审查你的 diff，检查关键 Bug 和安全问题。作为 Stop 钩子在 TDD 和 iCPG 记录之间运行。 Stop 钩子执行顺序： 1. tdd-loop-check.sh → 测试是否通过？ 2. codex-auto-review.sh → Codex 审查 diff（新增） 3. icpg-stop-record.sh → 记录符号 4. mnemos-checkpoint.sh → 保存记忆 - 退出码 0 = 未发现关键问题 - 退出码 2 = 关键/高危问题反馈给 Claude 进行修复 - 若未安装 Codex 则优雅跳过 ### Kimi 任务委派（Token 优化） Claude 会检查 iCPG 影响范围，并自动将小型任务委派给 Kimi —— 用户无需手动执行任何操作： | 影响范围 | Claude 的行为 | |———––|––––––––| | 1-3 个文件 | 通过 mnemos checkpoint 保存上下文，运行 kimi --print -y -p "..." 附带上下文与任务 | | 4-8 个文件 | 询问用户，随后委派或直接处理 | | 9+ 个文件 | 直接处理（需要完整上下文窗口） | 上下文传递使用结构化状态（mnemos 检查点 + iCPG 约束），而非原始对话记录。 ### iCPG + Mnemos（所有智能体默认常驻） 三款工具均运行相同的 iCPG 任务前查询与 Mnemos 记忆生命周期： bash # 在任何代码变更之前（Claude、Kimi 或 Codex）： icpg query prior "" # 检查重复工作 icpg query constraints # 检查不变量 icpg query risk # 检查脆弱性 # 记忆管理： mnemos add goal "" # 任务开始时 mnemos checkpoint # 在子目标边界处 ## TDD 循环工作原理（Stop 钩子） 无插件。无伪命令。 Claude Code 的 Stop 钩子在 Claude 完成响应时运行脚本。退出码 2 会将 stderr 反馈给 Claude 并继续对话。 ┌─────────────────────────────────────────────────────────────┐ │ 1. 你说：“为注册功能添加邮箱验证” │ │ 2. Claude 编写测试 + 实现代码 │ │ 3. Claude 完成响应 │ │ 4. Stop 钩子运行：npm test && npm run lint │ │ 5a. 全部通过（exit 0）→ 完成！ │ │ 5b. 失败（exit 2）→ stderr 反馈给 Claude │ │ 6. Claude 查看失败信息，修复代码，再次完成响应 │ │ 7. Stop 钩子再次运行 → 循环直至全绿 │ └─────────────────────────────────────────────────────────────┘ 配置 位于 .claude/settings.json： json { "hooks": { "Stop": [{ "hooks": [{ "type": "command", "command": "scripts/tdd-loop-check.sh", "timeout": 60, "statusMessage": "Running tests..." }] }] } } tdd-loop-check.sh 脚本运行测试、lint 和类型检查。它会跟踪迭代次数（最多 25 次），并区分代码错误（继续循环）与环境错误（停止循环）。 ## @include 指令 CLAUDE.md 使用 @include 模块化加载技能： markdown # CLAUDE.md @.claude/skills/base/SKILL.md @.claude/skills/iterative-development/SKILL.md @.claude/skills/security/SKILL.md 这些指令由 Claude Code 在加载时解析 —— 内容会被递归内联（最大深度 5，内置循环检测）。这意味着技能会真正成为 Prompt 的一部分，而不仅仅是作为文本列出。 ## 条件规则 .claude/rules/ 中的规则使用带有 paths: 的 YAML frontmatter，仅在编辑相关文件时激活： yaml # .claude/rules/react.md --- paths: ["src/components/**", "**/*.tsx"] --- 优先使用带有 hooks 的函数组件... yaml # .claude/rules/python.md --- paths: ["**/*.py"] --- 使用类型提示、pytest、ruff... 内置规则： | 规则 | 激活条件 | |——|––––––––| | quality-gates.md | 始终（无 paths: 过滤） | | tdd-workflow.md | 始终 | | security.md | 始终 | | react.md | 编辑 .tsx/.jsx 文件时 | | typescript.md | 编辑 .ts/.tsx 文件时 | | python.md | 编辑 .py 文件时 | | nodejs-backend.md | 编辑 api/routes/server 文件时 | ## 更智能的上下文压缩（PreCompact 钩子） Claude Code 内置的压缩机制在上下文达到约 83% 时触发，并使用通用的 9 段模板将所有内容压缩为 20K Token。它并不了解你的项目真正关心什么。 PreCompact 钩子通过向摘要器注入项目特定的保留优先级来解决此问题： ┌─────────────────────────────────────────────────────────────┐ │ 内置压缩： │ │ “总结这段对话” → 生成通用摘要 │ ├─────────────────────────────────────────────────────────────┤ │ 启用 PreCompact 钩子后： │ │ “请总结，但逐字保留所有 schema 决策， │ │ 保留确切错误信息，保留 API 契约细节， │ │ 按名称引用这些关键决策，并附上当前的 git 状态” → 项目感知摘要 │ └─────────────────────────────────────────────────────────────┘ 该钩子自动检测： - 项目类型（TypeScript/Next.js、Python/FastAPI、Flutter 等） - Schema 文件（Drizzle、Prisma、SQLAlchemy）→ 告知摘要器保留 schema 讨论 - API 目录 → 告知摘要器保留端点路径与契约 - CLAUDE.md 中的关键决策 → 告知摘要器按名称引用它们 - Git 状态 → 注入分支、未提交更改、暂存文件 正常使用期间零开销。仅在压缩实际触发时运行。 ## Mnemos —— 任务级记忆生命周期 Claude Code 内置的压缩是有损且不可靠的。它有时不会触发，/compact 和 /clear 可能失败（尤其在多智能体执行中），且崩溃/重启会丢失所有上下文。 Mnemos 提供磁盘持久化的结构化状态，可 survive 所有上述故障模式。 ┌─────────────────────────────────────────────────────────────┐ │ 默认 CLAUDE CODE vs 启用 MNEMOS │ ├─────────────────────────────────────────────────────────────┤ │ 达到 83.5% 前处于盲状态 持续 4 维度监控 │ │ 突然的硬性压缩 渐进式：40→60→75→83% │ │ 统一摘要 类型化：目标永不淘汰 │ │ 无跨会话记忆 自动检查点/恢复 │ │ 崩溃 = 上下文完全丢失 崩溃 = 从磁盘恢复 │ │ 多智能体：无共享状态 每智能体独立结构化状态 │ │ 无行为感知 检测重读、范围分散 │ └─────────────────────────────────────────────────────────────┘ ### 压缩后任务恢复（双层防御机制） 当压缩触发时，内置摘要器通常会丢弃任务特定状态。Mnemos 使用两个独立层来保证恢复： 压缩前 压缩后 PreCompact 钩子触发 首次工具调用 → PreToolUse 触发 ├── 写入紧急检查点 ├── 检测到 ".mnemos/just-compacted" 标记 ├── 从 signals.jsonl 构建任务脉络 ├── 读取 checkpoint-latest.json │ （文件、工具） ├── 将完整检查点输出到上下文中 ├── 向摘要器输出强保留指令 └── 删除标记（一次性） └── 写入 ".mnemos/just-compacted" 标记文件 = 任务完全恢复 第一层（尽力而为）：PreCompact 告知摘要器保留什么，包括带有类型化淘汰优先级的内联检查点内容。 第二层（绝对保证）：压缩后通过 PreToolUse 注入，在压缩后的第一次工具调用时重新注入完整检查点。不依赖摘要器。未发生压缩时快速路径仅 ~5ms。 ### 为什么不直接写入普通文件？ 你可以这么做 —— 但会立刻面临：用什么格式？何时更新？如何区分“关键信息”和“锦上添花”？ MnemoGraph 的类型化节点解决了这个问题： | 节点类型 | 淘汰策略 | 示例 | |———–|––––––––|———| | GoalNode | 永不淘汰 | “实现认证模块” | | ConstraintNode | 永不淘汰 | “API 向后兼容” | | ResultNode | 优先压缩 | “JWT 中间件已测试” → 保留摘要 | | WorkingNode | 优先压缩 | 当前推理 / 进行中的分析 | | ContextNode | 可淘汰 | 文件内容 → 从磁盘重新读取 | 没有类型化优先级，检查点只是一团数据。有了它们，系统知道 目标 > 约束 > 工作记忆 > 上下文，并能在 Token 预算内智能决定恢复什么。 ### 超越常规压缩的韧性 真正的价值不在于顺利路径，而在于出错时： | 故障模式 | CC 内置机制 | Mnemos | |—|—|—| | 会话崩溃/中断 | 上下文丢失 | 磁盘检查点存活 | | /compact 未触发 | 达到上限时截断 | 疲劳钩子已提前写入检查点 | | 多智能体子进程终止 | 无法恢复 | 子进程的 .mnemos/ 保留结构化状态 | | 强制重启 | 通用摘要 | SessionStart 重新加载完整检查点 | | 多智能体中 /clear 失败 | 卡在异常状态 | MnemoGraph 独立于 CC 状态 | ### 疲劳模型 4 个维度通过钩子被动观测 —— 无需智能体配合： | 维度 | 权重 | 信号来源 | 检测内容 | |———–|––––|—————|———| | Token 利用率 | 0.40 | 状态行 JSON | 上下文窗口饱满程度 | | 范围分散度 | 0.25 | PreToolUse 文件路径 | 智能体在目录间频繁跳跃 | | 重读比例 | 0.20 | PreToolUse Read 调用 | 智能体重复读取文件（上下文丢失） | | 错误密度 | 0.15 | PostToolUse 结果 | 智能体受阻（高错误率） | 疲劳状态：FLOW（0-0.4）→ COMPRESS（0.4-0.6）→ PRE-SLEEP（0.6-0.75）→ REM（0.75-0.9）→ EMERGENCY（0.9+）。 疲劳模型确保检查点在出问题之前写入 —— 因此当在 0.85 发生崩溃时，你仍拥有 0.6 时的近期检查点。 ### CLI bash mnemos init # 初始化 .mnemos/ mnemos status # 节点数量 + 疲劳状态 mnemos fatigue # 详细 4 维度分解 mnemos checkpoint --force # 立即写入检查点 mnemos resume # 输出检查点供会话注入 mnemos add goal "Build auth" # 创建 GoalNode mnemos bridge-icpg # 导入 iCPG ReasonNodes 开销： 每次工具调用约 ~5ms（快速路径），磁盘占用 84KB。Token 信号通过状态行自动馈送。 ## iCPG —— 意图增强型代码属性图 iCPG 追踪代码为什么存在，而不仅仅是它做什么。每次代码变更都链接到一个 ReasonNode，捕获意图、后置条件和不变量。 bash icpg create "Implement auth" --scope src/auth/ # 创建意图 icpg record src/auth/middleware.ts # 链接符号 icpg query constraints src/auth/middleware.ts # 获取不变量 icpg drift # 检查偏离 icpg bootstrap # 从 git 历史推断 任务前查询（通过 PreToolUse 钩子自动注入）： - icpg query context — 哪些意图涉及此文件？ - icpg query constraints — 必须满足哪些不变量？ - icpg drift file — 此文件是否偏离了其意图？ 6 维度偏离检测： 规范偏离、决策偏离、归属偏离、测试偏离、使用偏离、依赖偏离。 ## Maggy 仪表板 —— AI 工程指挥中心（可选） Maggy 是一个全功能 AI 工程指挥中心。安装一次，指向你的代码库和问题追踪器，即可获得包含聊天、任务分诊、竞品情报、流程分析和 P2P 会话同步的交互式仪表板。 bash cd maggy/maggy ./install.sh # 编辑 ~/.maggy/config.yaml — 设置你的组织、GitHub 仓库、代码库路径 export GITHUB_TOKEN=ghp_... export ANTHROPIC_API_KEY=sk-ant-... python3 -m maggy.main # 访问 http://localhost:8080 或在任意 Claude Code 会话中： `` /maggy-init # 交互式设置