把 Claude Code 原生的
/loop（循环驱动）和/goal（停止前目标对齐守门）串联成「推进 + 验收」闭环，配合状态文件、质量闸门与「7 + N」多 Agent 协作，将松散的多轮迭代包装成可控、可追踪、高质量的工业级开发流程。
cc-loop 是一个 Claude Code Skill，用于管理长时间、多轮迭代的复杂项目开发。它把两个 Claude Code 原生命令串联为闭环：
/loop（链路前半 · 驱动） — 周期性触发 cc-loop 的循环协议，每轮完成一次「协调 → 变更计划 → 执行 → 闸门校验 → 更新状态」。/goal（链路后半 · 守门） — 「Set a goal Claude checks before stopping」。cc-loop 通过 skill 加载告诉 Claude：停止前先读.cc-loop/goal.md的验收标准逐条比对，达成才停、未达成就续跑——避免过早停止或已达成后空转。
两者之间由本 skill 承接：状态文件驱动、质量闸门强制、多 Agent 角色协作。
- 📋 状态文件驱动 —
.cc-loop/state.md作为单点真相源（Single Source of Truth），每轮由 Coordinator 更新 - 🚦 质量闸门 — 预定义通过标准（lint / type-check / test / coverage），未通过强制进入修复循环；通过
scripts/run-gate.shwrapper 自动采集度量 - 👥 「7 + N」多 Agent 协作 — 7 核心角色（协调者 / 架构师 / 开发者 / 测试者 / 审查者 / 运维 / 产品）+ N 个按需激活的扩展角色（SEC / UX / UI / MOBILE / DATA / BA）
- 🔀 真并行 — 用 Claude Code 的
fan out subagents（独立并行）或ultracode（交叉验证）在单轮内并行调度多个角色 - 🛡️ GoalCheck 守门 —
/goal触发时逐条比对goal.md的AC-XXX验收标准与state.md任务状态、闸门结果 - 🔒 Change Plan 守门 — 默认保守模式，改代码前先出计划、经用户确认；可显式切换「信任模式」
- 🚨 死循环检测 — Coordinator 检测连续 3 轮无推进 → 标注
Dead loop suspected→/goal守门时升级 Architect 复盘
/loop 周期 /goal（用户收尾时或停止前触发，非 /loop 自动调用）
┌───────────────────┐ ┌─────────────────────────┐
│ Coordinator │ │ Claude 受 skill 引导 │
│ Agent → Change │ │ 读 .cc-loop/goal.md │
│ Plan → 闸门 │ │ 逐条比对 → 自行决定 │
│ → 更新 state │ └────┬──────────┬─────┘
└─────────┬─────────┘ 已达成 未达成
▼ │ │
累计 N 轮 Claude 宣布完 Claude 建议继续
▼ │ │
用户/停止时触发 /goal ┈┈┈(非自动)┈┈▶ ──┘ └─→ 继续 /loop
/loop不会自动调用/goal。/goal是原生命令，由用户收尾或停止前场景触发；cc-loop 只负责教 Claude「触发时先读goal.md再决定是否停」。虚线表示「停止前的一次校验」，而非确定性下一步。
| 场景 | 推荐用法 | 链路位置 |
|---|---|---|
| 长时间功能开发、多轮迭代 | /loop [interval] + 单 Agent prompt |
前半：循环驱动 |
| 多 Agent 并行冲刺 | /loop [interval] + fan out subagents: prompt |
前半：循环驱动 |
| 审查/测试深度协作 | /loop [interval] + ultracode: prompt |
前半：循环驱动 |
| 停止前的目标校验 | /goal（读 .cc-loop/goal.md 逐条比对） |
后半：停止前守门 |
| 死循环升级与复盘 | /goal 看到 Dead loop suspected 标注 → 升级 Architect |
后半：守门 + Escalation |
将 cc-loop/ 目录作为 skill 加载：
# 方式 A：项目级 skill
cp -r cc-loop your-project/.claude/skills/cc-loop
# 方式 B：个人 skill
cp -r cc-loop ~/.claude/skills/cc-loop进入你的项目目录，首次使用前必须完成启动检查单。完整命令模板见 SKILL.md#启动检查单。要点：
mkdir -p .cc-loop
# goal.md —— 必须含 - [ ] AC-XXX 验收清单（GoalCheck 逐条比对依据），
# 每条 AC 用 mapped_tasks: 关联到 state.md 的任务
# state.md —— 至少含 ## SUMMARY + ## Tasks + ## History
# gates.yml —— 从 references/gates/ 按项目类型复制（frontend / backend / fullstack）
PROJECT_TYPE=frontend
cp <SKILL_DIR>/references/gates/${PROJECT_TYPE}.yml .cc-loop/gates.yml
# run-gate.sh —— 度量采集 wrapper（零环境变量依赖，统一入口）
mkdir -p .cc-loop/scripts
cp <SKILL_DIR>/references/scripts/run-gate.sh .cc-loop/scripts/run-gate.sh
chmod +x .cc-loop/scripts/run-gate.sh
<SKILL_DIR>替换为本 skill 所在目录（如.claude/skills/cc-loop）。 未完成初始化前不要启动/loop——/goal会因找不到验收标准而无法守门。
/loop 只接受单行 prompt 字符串。单 Agent 主循环：
/loop 5m "Coordinator：读 .cc-loop/state.md 的 ## SUMMARY（如不存在则读全文，并结合 .cc-loop/goal.md 验收标准）。跑一轮 cc-loop 协议——分配 Agent、Change Plan、用户确认、执行、自测、更新 state.md 并运行质量闸门；全部通过则推进，有失败则进入修复循环；发现 3 轮无推进则标注 'Dead loop suspected at Round N'。到达停止边界或用户收尾时，由 Claude 受 skill 引导触发 GoalCheck，读 .cc-loop/goal.md 全部达成后才停止。"
多 Agent 并行（独立并行用 fan out subagents，交叉验证用 ultracode）：
/loop 5m "fan out subagents: Developer, Reviewer, Tester. Coordinator: 读 .cc-loop/state.md ## SUMMARY，并行调度 Developer（实现+单测）、Reviewer（[block]/[major]/[minor] 审查）、Tester（边界+集成）；Developer→Reviewer→Tester 单向流转，[block] 退回 Developer，冲突由 Coordinator 请 Architect 仲裁；结果统一由 Coordinator 写入 state.md。"
详细用法参见 SKILL.md，并行语法见 references/subagent-invocation.md。
cc-loop/
├── SKILL.md # 技能主文件（Claude Code 加载入口）
├── README.md # 本文件
├── LICENSE # MIT 协议
├── EVALUATION.md # 设计评估与修正记录
└── references/ # 详细参考文档
├── project-state-schema.md # state.md 完整格式规范（9 状态机）
├── state-management.md # 三级读取、SUMMARY 协议、归档规则
├── quality-gates.md # 闸门配置、自动修复、升级逻辑
├── agent-roles.md # 「7 + N」角色团队完整定义
├── prompt-templates.md # 核心 + 扩展角色系统提示模板
├── loop-patterns.md # 10 个 /loop 启动模板（A–J）
├── subagent-invocation.md # fan out subagents / ultracode 并行机制
├── troubleshooting.md # 逃生舱、故障恢复、Architect 复盘触发
├── metrics.md # 度量指标定义、采集规范
├── gates/ # 可直接复制的纯 YAML 闸门配置
│ ├── frontend.yml
│ ├── backend.yml
│ └── fullstack.yml
└── scripts/
└── run-gate.sh # 闸门执行 + 度量采集 wrapper
| 概念 | 说明 |
|---|---|
| 状态文件 | .cc-loop/state.md，单点真相源：项目背景、当前阶段、任务列表、闸门结果，每轮更新 |
| 质量闸门 | 预定义通过标准，每轮必须通过才进入下一阶段；通过 run-gate.sh 执行并采集度量 |
| Agent 角色 | 「7 + N」弹性团队，通过系统提示分配；fan out / ultracode 实现真并行 |
| 链路关系 | /loop 周期性驱动；/goal 停止前校验 goal.md。二者形成「推进 + 验收」闭环 |
| Change Plan | Agent 改代码前先出计划，用户确认后执行（默认保守模式） |
| Coordinator | 专责状态维护、摘要更新、轮次管理、死循环检测的协调者 Agent |
| GoalCheck | /goal 触发时逐条比对 AC-XXX ↔ 任务状态 + 闸门结果 |
完整 9 状态流转（与 SKILL.md、agent-roles.md、project-state-schema.md 一致）：
┌──────────────────────────┐
│ blocked │
│ (任何 Agent 标记) │
└──────────────────────────┘
↑ resolved
│
backlog → claimed → in-progress → ready-for-review → reviewing
↓ ↓
ready-for-test [block] 退回 in-progress
↓
testing → done → GoalCheck
↓
[fail] 退回 in-progress（@Developer，附 bug-type）
状态定义见 SKILL.md#状态定义 —— 含 backlog / claimed / in-progress / ready-for-review / reviewing / ready-for-test / testing / done / blocked 共 9 态。
- SKILL.md — 技能主文档（必读，链路式完整叙事）
- references/agent-roles.md — 「7 + N」角色团队定义
- references/loop-patterns.md — 10 个
/loop启动模板 - references/subagent-invocation.md — 并行唤起（
fan out/ultracode） - references/quality-gates.md — 闸门配置与升级逻辑
- references/troubleshooting.md — 故障排除与死循环复盘
欢迎通过 Issue 提交问题或 PR 提交改进。
本项目采用 MIT License 开源。