cc-sentinel：Claude Code的治理基础设施，防止自主编码会话的失败模式

cc-sentinel为Claude Code提供了一套模块化的治理基础设施，通过钩子、智能体验证工作流和状态管理，解决了上下文丢失、工作延期、虚假完成等自主编码会话中的常见失败模式。

|------|------|------| | anti-deferral.sh | PreToolUse | 扫描每次文件写入中的延期语言（"TODO later"、"will implement"、"future sprint"），向Claude上下文注入警告，要求开发者在延期前明确批准 | | session-orient.sh | SessionStart | 在会话开始时注入CURRENT_TASK.md内容，使Claude从第一轮就拥有完整上下文 | | pre-compact-state-save.sh | PreCompact | 上下文压缩前的最后机会钩子，提醒Claude将所有进行中的状态写入CURRENT_TASK.md | | post-compact-reorient.sh | SessionStart (compact) | 压缩后重新注入任务状态，使Claude能够恢复工作而无需重新读取文件 | | agent-file-reminder.sh | PreToolUse | 提醒智能体将结果写入文件，而非仅在内存中返回（内存会在智能体退出后丢失） | | auto-checkpoint.sh | Stop, PreCompact | 会话结束或上下文压缩时自动提交工作进度，防止静默工作丢失 |

\n核心模块还包括：\n- CURRENT_TASK.md模板——结构化的状态文件，能够 survive 压缩\n- Channel模板——用于多智能体并行工作\n- 操作者速查表——所有技能的快速参考\n- /self-test命令——验证安装的诊断命令\n\n### 上下文感知（Context Awareness）：可视化上下文计量器\n\n在Claude Code状态栏中显示可视化的上下文窗口计量器。随着上下文填满，分级警告会触发，提示Claude在压缩发生前保存状态。\n\n\ncontext [████████████░░░░░░░░] 62%\n\n\n阈值触发自动提醒：\n- 50% — "正在记录进展吗？"\n- 65% — "新会话能从你的状态文件恢复吗？"\n- 75% — "全面记录，做好冷启动准备。继续有条不紊地工作，直到约84%时压缩。"\n- 85% — "提交所有更改。状态文件必须是最新的。继续工作。"\n- 92% — "自动压缩即将发生。状态文件必须完整。"\n\n这一功能对Claude Code本身和用户都有益。没有上下文感知时，Claude无法感知自己的上下文窗口有多满——它无法感知压缩的临近。分级警告为Claude提供了可操作的信号，使其能够在压缩发生前保存状态、完成工作单元并做好准备。\n\n### 验证模块（Verification）：多模型验证小队\n\n在Claude宣称完成之前，由多个模型独立审计工作。支持两种架构：\n\n仅Sonnet架构（5个智能体）：默认配置，当Codex CLI未安装时使用。五个具有不同对抗视角的Claude Sonnet智能体并行运行。\n\n交错架构（最多15个智能体）：当OpenAI Codex CLI可用时，运行5个Sonnet + 5个Codex + 条件性重新验证轮次。架构不同的模型发现不同类型的bug——一个模型遗漏的问题，另一个可能发现。\n\n验证智能体角色：\n\n| 智能体 | 发现的问题 | |--------|-----------| | Mechanical Auditor | 错误文件路径、常量、枚举值、计数、性能问题——任何可grep的内容 | | Adversarial Reader | 规范矛盾、幻觉内容、规则违反、回归 | | Completeness Scanner | 缺失的需求、未分配的项目、规范缺口 | | Dependency Tracer | 缺失的迁移、未追踪的调用点、静默默认更改 | | Cold Reader | 作者看不见的语义错误——零上下文阅读 |

\n交错流程（当Codex可用时）：\n- R1：5个Sonnet智能体（基线扫描）\n- R2：5个Codex智能体（对修复后内容的跨架构扫描）\n- R3：Sonnet重新验证（仅标记的角色）\n- R4：Codex升级（仅失败的角色，更高推理努力）\n- 门禁：全部通过 → Opus关闭\n\nstop-task-check.sh钩子在Claude尝试停止时触发，要求在允许完成声明通过之前提供验证证据。自我证明（"我验证了这一点"）被明确拒绝——钩子检查磁盘上实际的 squad 输出文件。\n\n### 提交强制执行（Commit Enforcement）：代码提交门禁\n\n代码提交被门禁控制：测试必须通过、格式必须整洁，且两个验证智能体在代码落地前审查差异。仅文档和配置更改通过轻量级检查，无需完整智能体审查。\n\n| 组件 | 功能 | |------|------| | safe-commit.sh | 运行测试（自动检测：npm、pytest、cargo、go、flutter、make），失败时阻止 | | auto-format.sh | 每次文件写入时运行格式化工具（prettier、black、cargo fmt、dart format、gofmt） | | channel_commit.sh | 编排：暂存、验证、测试、格式化、提交。提交的单一公共API | | commit-adversarial.md | 审查暂存差异的逻辑错误、规范违反、回归的智能体 | | commit-cold-reader.md | 零上下文阅读暂存差异的智能体——标记任何损坏或无意义的内容 |

\n多框架自动检测：提交钩子从清单文件（package.json、Cargo.toml、go.mod、pubspec.yaml、pyproject.toml、Makefile）检测项目类型，并运行相应的测试套件和格式化工具。\n\n单终端模式：无需Sonnet监听器即可工作。当未检测到Sonnet心跳时，系统自动回退到本地验证——无需5分钟挂起，无需手动标志。\n\n### Sprint Pipeline：结构化工作流阶段\n\n为复杂功能提供结构化工作流阶段。每个阶段都有对应的技能：\n\n| 命令 | 阶段 | 目的 | |------|------|------| | /1 或 /audit | Audit | 评估当前状态，识别缺口 | | /2 或 /design | Design | 头脑风暴、规范、计划、分类任务 | | /3 或 /build | Build | 自动执行分类计划 | | /4 或 /perfect | Perfect | 质量检查、边界情况、润色 | | /5 或 /finalize | Finalize | 验证小队、清理、完成 | \n示例工作流：\n\n\n用户: /2\nClaude: [与你头脑风暴，编写规范，创建实现计划，\n 将任务分类为Opus/Sonnet/Agent，对抗性计划审查，\n 提交供你批准]\n\n用户: /3\nClaude: [逐个执行任务。在阶段边界提交。\n 两个智能体验证每次提交。无需人工干预。]\n\n用户: /4\nClaude: [全新阅读所有内容。发现边界情况、不一致、\n 质量问题。修复它们。\"废弃重写\" pass。]\n\n用户: /5\nClaude: [运行验证小队。生成最终报告。\n 清理会话工件。准备交付。]\n\n\n### 治理保护（Governance Protection）：防止规则自修改\n\n防止Claude在会话中编辑自己的规则：\n\n- file-protection.sh：PreToolUse钩子，阻止对受保护文件（CLAUDE.md、settings.json等）的写入\n- 覆盖机制：在CURRENT_TASK.md中添加GOVERNANCE-EDIT-AUTHORIZED可临时允许编辑（创建审计追踪）\n- /mistake：结构化纠正捕获，添加到CLAUDE.md的累积纠正列表\n- /prune-rules：在软上限下维护纠正列表（防止规则膨胀）\n\n### 通知模块（Notification）：桌面提醒\n\n当Claude Code完成任务或需要输入时发送桌面提醒。平台原生：\n\n- macOS：osascript通知 + 终端铃声\n- Linux：notify-send (libnotify) + 终端铃声\n- Windows：FlashWindowEx任务栏闪烁 + 控制台蜂鸣（使用.NET，Windows 10+预装；目标Windows Terminal）\n\n## 安装与使用\n\n### 交互式安装\n\n在任何Claude Code会话中：\n\n\nInstall https://github.com/turqoisehex/cc-sentinel\n\n\nClaude Code会克隆仓库并运行交互式安装程序。预期流程：\n\n1. 检测你的操作系统、shell、终端和项目类型，报告发现\n2. 询问你的用例——你使用Claude Code做什么（开发、研究、写作等）\n3. 呈现问题→解决方案表格，展示每个失败模式及解决它的模块\n4. 呈现模块表格及推荐。始终提供"所有模块"作为第一个选项\n5. 询问全局 vs 项目安装。对大多数用户推荐全局安装\n6. 使用选定的模块运行安装程序\n7. 提供二进制/媒体文件排除的拒绝规则\n8. 建议与cc-sentinel互补的插件\n9. 打印安装摘要：模块、钩子、技能、状态行、生成配置\n10. 打印内联安装摘要（钩子、技能、参考文件——每项带有通过/失败计数）\n\n### 手动安装\n\nbash\n# 克隆\ngit clone https://github.com/turqoisehex/cc-sentinel.git ~/.claude/cc-sentinel\n\n# 安装到当前项目\nbash ~/.claude/cc-sentinel/install.sh --modules \"core,context-awareness,verification\" --target project\n\n# 或全局安装\nbash ~/.claude/cc-sentinel/install.sh --modules \"core,context-awareness\" --target global\n\n# Windows (PowerShell)\npowershell -File ~/.claude/cc-sentinel/install.ps1 -Modules \"core,context-awareness\" -Target project\n\n\n## 跨领域适用性\n\ncc-sentinel的治理不仅适用于软件工程，还可应用于任何Claude Code工作流：\n\n- 翻译项目：反延期捕获"将重新审视措辞"。验证小队审计跨文档的一致性。上下文感知防止章节中期的压缩。\n- 研究工作流：状态文件保存跨会话的文献综述进展。提交强制执行通过对抗性审查门禁研究笔记。Sprint Pipeline结构化研究到综合的弧线。\n- 数据分析：Channel系统协调并行分析流。预压缩钩子保存中间结果。停止钩子防止过早的"分析完成"声明。\n\n## 总结与思考\n\ncc-sentinel代表了AI辅助工具治理的一个重要方向——从依赖AI的自我约束到建立自动化的强制执行机制。它识别了Claude Code在实际使用中的真实痛点，并提供了系统性的解决方案。\n\n对于个人开发者，cc-sentinel提供了更可靠、更可预测的AI编程体验；对于团队，它提供了标准化的AI协作流程和质量门禁；对于AI编程生态，它展示了如何构建"元工具"来治理AI工具本身。\n\n随着AI编程助手能力的不断增强，如何确保这些强大工具的可靠性和可控性将变得越来越重要。cc-sentinel的探索为这一领域提供了有价值的参考。

AI辅助编程的现实困境\n\nClaude Code作为Anthropic推出的AI编程工具，凭借其强大的代码理解和生成能力，已经成为许多开发者日常工作的重要助手。然而，随着使用时间的增长，用户逐渐发现了一些在长时间自主编码会话中出现的"失败模式"（Failure Modes）：\n\n上下文丢失（Context Loss）\n\n当Claude Code的上下文窗口填满并触发压缩（compaction）后，模型会"忘记"之前正在做什么，导致重复工作或做出与早期决策相矛盾的操作。这会造成数小时的计算资源浪费和不一致的输出。\n\n工作延期（Work Deferral）\n\nClaude经常写下"TODO: 稍后实现"或"将在下一步添加"这样的注释，然后再也没有返回处理。结果是功能被标记为"完成"，但实际上并未实现。\n\n虚假完成（False Completion）\n\nClaude在没有充分验证的情况下就宣称任务已完成，导致bug在生产环境而非开发阶段才被发现。\n\n治理漂移（Governance Drift）\n\nClaude在会话中编辑自己的规则文件（如CLAUDE.md或配置文件），导致防护栏被悄然禁用。\n\n静默压缩（Silent Compaction）\n\n上下文窗口在没有警告的情况下被填满，状态在能够被保存之前就已丢失，造成不可恢复的任务中断。\n\n提交质量问题（Commit Quality）\n\n大量代码差异未经审查就提交，测试被跳过，格式不一致，技术债务在每个会话中累积。\n\n智能体失忆（Agent Amnesia）\n\n子智能体启动时对项目约定或当前任务状态一无所知，产生与会话主体相矛盾的工作。\n\ncc-sentinel正是为解决这些实际问题而设计的治理基础设施。\n\ncc-sentinel是什么\n\ncc-sentinel是一套模块化的Claude Code钩子、技能、参考文档、智能体和模板集合。它通过自动执行的钩子来强制执行规则，而不是依赖Claude选择遵守规则。\n\n核心理念是：治理应该是自动化的，而非可选的。\n\ncc-sentinel的安装过程是交互式的——Claude Code会读取你的项目并推荐需要安装的模块。安装后，这些模块会在后台自动运行，防止上述失败模式的发生。\n\n核心模块详解\n\n核心模块（Core）：防止三大最常见失败模式\n\n核心模块解决上下文丢失、工作延期和智能体失忆三大问题：\n\n| 钩子 | 事件 | 功能 |

|------|------|------| | anti-deferral.sh | PreToolUse | 扫描每次文件写入中的延期语言（"TODO later"、"will implement"、"future sprint"），向Claude上下文注入警告，要求开发者在延期前明确批准 | | session-orient.sh | SessionStart | 在会话开始时注入CURRENT_TASK.md内容，使Claude从第一轮就拥有完整上下文 |