用AI写代码几个月，最大成本不是烂代码

用 Cursor 和 Claude Code 在真实产品上写了几个月代码之后，作者算了一笔账：最大的成本不是写坏的代码。是反复解释同一套架构，反复抓同一个错误，反复从 diff 里倒推某处为什么改。

他把这件事归结成一个很朴素的事实：每次会话唯一能活下来的上下文，是代码仓库本身。于是他开始把仓库当成 AI 代理的记忆来用，做成了一个开源项目 Agent Runway，把规格、决策、检查点和运行日志都放在代码旁边。项目采用 MIT 许可，免费。

作者在文中披露了自己的身份：他是 Agent Runway 的作者。

写代码不再是难的那部分

难的是在一个真实代码库里维持连续性。只要用编码代理做过活过不止一个周末的项目，大概率撞过下面这堵墙：

• 会话之间上下文丢失
• 架构决策做过了，然后被忘掉
• 同样的错误在不同功能里重复出现
• 自主运行没有可追溯性
• 实现慢慢偏离需求

这些问题的根源不是模型"笨"，而是模型每次都从零开始，而且没有人（人或代理）把重要的东西写下来，放在下一次会话真的会去读的地方。

光有规则文件不够

常见的第一个补丁是 CLAUDE.md、.cursor/rules 目录或者 .github/copilot-instructions.md。这些有用，Agent Runway 也会生成它们。但规则文件只回答一个问题：这里的代码应该长什么样。

它不回答另外几个问题：我们在造什么，"做完"是什么意思（规格）；工作按什么顺序推进，推进前必须通过什么（工作流与关卡）；上次学到了什么、决定了什么（记忆）；我们停在哪、还有什么没关（检查点与运行日志）。

把这些全塞进一个不断膨胀的指令文件，就是文档熵。Agent Runway 的做法是：生成的指令文件（AGENTS.md、CLAUDE.md、Copilot instructions）只当轻量入口，耐久知识放进仓库里一个专门的文件夹。

四层结构

Agent Runway 是产物驱动的，工作经过四层：规格定义意图与行为，工作流用质量关卡编排执行，规则在每一步强制标准，记忆为未来会话捕获决策与教训。全部放在仓库内的 .agent-runway/ 目录里。

一次 Lite 初始化之后，这个目录里会有 config、docs（含 architecture、business、contracts、examples、testing、tickets）、logs、memory、rules、skills、specs、workflows。memory 目录下是 common-failures.md、execution-memory.md、project-decisions.md、reasoning-memory.md、recurring-patterns.md、review-findings.md、testing-notes.md、ticket-quality-notes.md 这些文件。

它们不是被动文档。规格、工单、记忆文件、检查点和运行日志会影响代理跨会话如何推理、规划和执行。因为只是仓库里的文件，这层产物可以在 Cursor、Claude Code 和 VS Code Copilot 之间迁移，也能提交给团队共享。它不替代你的技术栈、架构或流程，只是包在外面。

从 Lite 开始

第一天不需要全套仪式。Vibe/Lite 预设是快速、技能优先的配置，面向原型、单人和低仪式编码，需要 Node.js 22 或更新版本：

npx @adonai-labs/agent-runway init --preset vibe-lite --target all

Lite 装几个技能，加一小套工程原则、安全和测试规则。没有斜杠命令，没有代理，没有重工作流。这些技能之间没有固定顺序，作者自己的用法是：@express 处理改动本身，范围小、仪式少；@checkpoint 在当天收工或交接时用，当前状态写进日志，下一次会话（你的或代理的）从那里恢复而不是靠猜；@learning 在抓到值得记住的东西时用——一个反复出现的错误、一个决策、一个约定，写进 .agent-runway/memory/，未来会话会读到。

他强调这只是习惯，不是必须的顺序。@learning 那一步是他最推荐的：修一次错误很容易，重点在于下一次会话不再重复它。

升级到 Structured

工作超出 Lite 之后，原地升级：

npx agent-runway upgrade --to structured

记忆、日志、检查点和文档都会保留，同时加上完整的 Structured 工作流集。也可以直接从这里起步，比如用 node-typescript 预设初始化。

Structured 增加斜杠命令、代理、规格、工单、lead/自主工作流、架构/逆向关卡、完整规则和可选的治理检查。核心路径是：/spec-creator 在实现前定义意图与行为，/ticket-creator 把它变成可开工的工单，/lead 是带质量关卡的完整实现工作流，/review 做结构化评审（工程、安全、性能）。需要时还有更多入口：/architect 处理设计决策、权衡与 ADR，/contrarian 对选定方案做对抗性评审，/validate 和 /po-eval 检查工单与产品就绪度，/refactor 做保持行为的改动，/iac 处理基础设施即代码。

贯穿这些工作流的有两个理念。一是测试驱动交付：行为变更先理解问题、定义预期行为、选定能证明改动的证据，再动手实现；严格的测试先行不现实时，记录原因并用最小的可信替代方案。二是叙事交付：工单、提交、PR 描述、检查点和记忆条目讲一个简短的技术故事——工作为什么存在、改了什么、什么证据说明它安全、还有什么没关。不是更长的文档，而是不用逆向 diff 就能恢复的意图。

技术栈单独添加，没有自己的斜杠命令，安装的是规则、代码评审集成和栈技能，覆盖 .NET、TypeScript、Node.js、React、Python、Go、Rust。

自主但受治理

无人值守或低监督运行时用 /autonomous-lead。它保持和 /lead 一样的质量标准，另加三件作者不愿省掉的事：强制运行日志、ADR 关卡、破坏性操作前的人工批准。目标不是"放代理出去跑"，而是事后回来能看清它做了什么、为什么。作者也明确：Agent Runway 不是完全自主的 AI 工程师，也不消除工程判断的必要性。

PR 评审的两种模式

@code-review 和 /review 产出一份合并的 PR 式报告：结论、去重后的严重度计数、带影响的发现、可直接粘贴的 PR 评论、优点、技术债备注和建议的合并关卡。模式由你显式选择。

compact 是普通 PR 的默认模式，只评审一次 diff，按来源标注发现：CR 是标准评审，SEC 是安全，SNR 是资深架构/运维。

isolated 用于高风险 PR：认证、PII、合规、公开契约、数据迁移、IaC、并发、大型跨层改动。它对同一份 diff 分别跑独立的 CR、SEC、SNR 评审，再合并去重。高影响改动还有可选的逆向视角 CTR，它不是默认关卡。

两种模式都只评审引入的改动，并把广泛的技术债和行级发现分开。想要数字的话，agent-runway metrics 从关卡结论和运行日志给出交付记分卡；agent-runway ci-check（预览、需主动开启）在 CI 里校验治理产物，默认建议模式，团队准备好后可用 --profile strict。

局限与路线图

作者列了几条诚实的提醒：它不是应用框架、不是 SDK 抽象层，也不替代架构和文档实践；@council 和 ci-check 是预览，能用，但行为和 ci-check 的 JSON 输出可能还会变；结构是有成本的，这也是 Lite 存在的原因，路线图里也明确写了不是每个小任务都该用重治理。

v1.7 的计划是：CLI 内部模块化、更多产物级和安装/更新回归测试、更好的本地测试与发布文档、用真实例子稳定 @council。更往后他想试验一种"共享工作区"模型（意图、假设、上下文、约束、置信度、计划）来改善交接与恢复质量，但前提是在真实的多会话任务上测过。完整清单在 ROADMAP.md 里。

怎么试

npx @adonai-labs/agent-runway init --preset vibe-lite --target all

从小处开始，留下有用的，工作需要的时再升级。作者也留了反馈渠道：哪个技能仪式感太重，或者哪块上下文代理在会话之间还是会忘，都欢迎提 issue 和批评。