CodeRail — convergent coding governance for agentic projects

CodeRail — convergent coding governance for agentic projects

为什么值得关注

CodeRail 的核心命题是“Spec 是产出，不是前提”：真实 vibe coding 往往先探索、再理解、再收敛，而不是一开始就拥有完整规格。它把探索过程中形成的范围、证据、进度和交接状态写入 repo-local docs/ / .coderail/ 结构，并通过 start / check / done 三个命令让 coding agent 不能靠口头承诺绕过范围、验证和收口。这对 Harness-Engineering、Spec-driven-development、Loop-Engineering 都有直接价值。

深度判断：值得晋升，因为它不是泛泛的 Claude/Codex prompt 包，而是把“发散探索如何收敛成可验证项目状态”做成了本地生命周期门禁。用户的 Hermes/llm-wiki 工作流同样需要在发现大量候选后收敛：什么入库、什么 raw-only、什么 HOLD、下一轮从哪里继续。

机制 / 一阶原理

CodeRail 的一阶原理是：agent 工作的可靠性来自外部化状态和 fail-closed gate，而不是来自模型记忆。start 记录任务、允许文件和完成标准；check 对照当前 repo truth 判断是否跑偏；done 验证测试或人工检查、确认变更没有越界、同步文档，并只提交安全范围内的任务文件。若 Allowed 与 Forbidden glob 同时命中，它返回 SCOPE_CONTRADICTION，避免“允许规则静默覆盖禁止规则”。

这与 Knowledge-as-Code 的思想一致：事实、范围、进度、验证、交接不应只留在对话里，而应落到可版本化文本账本。对无人 cron 来说，log.md、raw hash、source page、写入记录和 reindex 输出就是类似的 repo truth。

与现有 wiki 概念的关系

• 对 Harness-Engineering：补充 repo-local lifecycle gate 与 fail-closed scope contract。
• 对 Loop-Engineering：每轮任务结束必须留下下一轮可恢复的状态，而不是依赖会话残留。
• 对 Spec-driven-development：规格可以从探索中被追认和固化，适合不确定任务的渐进收敛。
• 对 Agentic-Coding：减少“完成声明早于验证”和“顺手越界修改”的典型失败。

对 Hermes / llm-wiki 的可执行启发

1. 给 radar 候选池增加收敛状态：候选不只是“发现/未发现”，应有 promoted、raw-only、duplicate、HOLD、blocked-by-access 等状态。
2. 把 deep ingest 做成三命令心智模型：start=声明今日主题/晋升标准；check=查重和读已有概念；done=文件存在、index/log、写入记录、reindex 证据。
3. 无人 cron 默认 fail-closed：来源无法访问、概念重复、证据不足时不晋升正式页。
4. 交接优先于叙事：日报应说明下一轮应继续追踪什么，而不是只总结今天做了什么。

失败模式 / 边界条件

• CodeRail 需要项目愿意接受 .coderail/ 和 docs 账本；对轻量脚本或临时探索可能显得重。
• 本地 gate 只能管 repo 范围内事实，不能替代外部服务、部署、浏览器或 MCP action boundary 的审计。
• 如果 agent/人类长期忽略 check/done 输出，文本账本也会腐化。
• 今天只做方法论入库，未在用户项目中安装或运行 CodeRail；安装会改变 repo 工作流，需用户确认。

写入记录

• 2026-07-29 09:00 CST：基于 README 深度入库，提炼其对 Hermes / llm-wiki / agentic workflow 的机制启发、边界条件和未安装原因。