runesleo/claude-code-workflow

QuietHarness – AI 编码代理的轻量级可靠性层

是什么

• 一组小型、可移植的配置文件和脚本，为 Claude Code、Codex 或 Cursor 等 AI 编码助手添加安全检查。
• 核心部分（1 604 字节）定义了“工作边界”：检测无关变更、运行测试、在执行不可逆操作（如凭证更改、部署）前要求确认，并保留可验证的审计日志。
• 与三种支持的代理中的任意一种兼容；你只需安装与你使用的客户端匹配的部分。

为何需要它

• 防止代理覆盖其未检查的文件。
• 阻止代理在未实际运行项目测试套件的情况下声称任务已完成。
• 确保在任何实际更改写入文件系统前都有一个预览（dry-run）。
• 提供代理配置文件的自动备份/回滚，可安全恢复到之前的状态。

组织结构

文件夹	用途
templates/	三个最小配置包（共享核心、Claude 适配器、Cursor 规则、Codex 适配器）。
scripts/	辅助脚本：清单、安装（预览与应用）、验证、迁移。
examples/first-success/	分步隔离演示，展示代理成功“首次运行”的过程。
examples/leo-system/	作者真实任务系统的净化快照（JSON 示例、文档）。
docs/	架构、任务连续性、会话结束处理、日报处理等。
tests/	在临时 HOME 目录中运行安装器的烟雾测试。
media/	图表和发布图形。

典型工作流程

1. 克隆 仓库并运行 ./scripts/inventory.sh 查看将被修改的内容。
2. 创建一个隔离的演示目录（mktemp …）。
3. 以 预览模式 运行你客户端的安装器，例如：

   ./scripts/install.sh --dry-run --claude-project "$demo_dir"
   

4. 审查预览后，使用 --apply 应用。
5. 在 $demo_dir 中打开所选代理，并给出简单指令，如 Read TASK.md and complete the task.。
6. 代理应执行所需更改、运行现有测试，并返回成功的确凿证据，无需额外提示。
7. 若一切正常，重复安装步骤但不带 --project 标志，以全局安装核心（写入 ~/AGENTS.md、~/.claude/CLAUDE.md 等）。备份会自动创建（.bak-ai-workflow-*）。

关键安全机制

• 预览模式 – 除非显式传递 --apply，否则不会写入任何文件。
• 备份与回滚 – 原始配置文件会按时间戳保存；安装器可自动恢复它们。
• 风险门控操作 – 任何潜在破坏性操作（凭证更改、生产部署、发布）都需要代理的显式确认步骤。
• 隔离 – 演示完全在临时目录内运行；安装器从不连接互联网或修改你的账户设置。

适合人群

• 已依赖 Claude Code、Codex 或 Cursor 进行代码生成，希望设置防护机制以避免意外覆盖或未经测试的提交的开发者。
• 在这些代理之间切换的团队，需要一种可在不同工具间迁移的一致安全策略，无需重写规则。
• 寻找可复现的“首次成功”入门测试，以验证其 AI 助手在自身代码库中行为可靠的任何人。

局限性

• 它 不提供 任务数据库、调度器或团队级编排平台——这些需单独构建。
• 仅支持类 Unix shell；目前尚无 Windows 的 PowerShell 安装器。
• 核心规则是静态文本文件；扩展需手动编辑或构建自己的模板。
• 系统假设你已在本地安装并配置了相应的 AI 代理客户端。

安装与验证

# 克隆并检查
git clone https://github.com/runesleo/claude-code-workflow.git
cd claude-code-workflow
./scripts/verify.sh   # 运行烟雾测试，检查备份、模板大小等

验证后，遵循上述演示步骤，或运行全局安装：

# Claude Code（用户级）
./scripts/install.sh --dry-run --claude
./scripts/install.sh --apply --claude

Codex（--codex）和 Cursor（--cursor）也有类似命令。

许可证

• MIT 许可证（参见 LICENSE）。

---

QuietHarness 本质上是一个 配置即代码 的包，使 AI 编码助手的行为更加可预测和安全，无需任何网络调用或专有 API。它是 LLM 基础代码助手开发者真正可复用的工具。