为什么是 CodeStable
August 3, 2026 · View on GitHub
English · 中文
起点
CodeStable 来自一个很具体的问题：AI 能快速写出大量代码，但一个持续演进的项目会不断丢失边界、决策和上下文。
同一个错误反复出现，往往不是模型不会写，而是项目没有把已经知道的事实组织好。
仅把更多提示塞进会话并不能解决这个问题。上下文会过期，聊天会结束，隐含共识也会漂移。
严肃工程需要让当前代码、产品契约、历史决策和验证证据在下一次工作时仍然可被找到。
与 Agent 编排解决不同问题
Agent 编排关注谁来做、如何组队、如何传递任务。CodeStable 关注软件本身由哪些长期要素构成，以及这些要素如何被确认、验证、保存和再次使用。
| Agent 编排 | CodeStable | |
|---|---|---|
| 核心实体 | Agent、角色、团队 | Feature、Issue、Epic、Decision、Evidence |
| 主线问题 | Agent 如何协作和接力 | 软件边界、决策和知识如何持续成立 |
| 状态归宿 | 会话、队列、消息总线 | 代码、项目文档与最小项目记忆 |
| 人的角色 | 决定自动化程度 | 掌握产品边界与最终接受 |
两种方向可以共存。宿主可以自由组织一个或多个 Agent，CodeStable 只约束软件任务的责任、边界、证据与知识归宿。
thin harness, thick context
模型越强，越应该给它责任，而不是逐步脚本。
CodeStable 的 skill 很薄：说明要达成什么、不能越过什么、怎样证明完成。它不要求所有任务经过同一套阶段，也不让常驻状态机替模型做局部工程判断。
任务类型只决定工程方法，实际风险决定保障强度：
执行流程 = 最小闭环 + 每个未排除风险所要求的最少保障
独立 review 不是默认步骤。一个风险只增加与它直接对应的保障，不自动打开整套流程。
上下文则要厚，但只在需要时加载。项目事实、相邻实现、历史经验和工程参考由当前任务按关键词与场景检索，避免把一整套手册预载进每次会话。
人在环不是每步审批
人在环的价值不是让用户反复点击“继续”。明确行动应该直接执行，普通步骤应该连续推进。
真正需要 owner 的地方是会改变产品契约、承担重大风险、选择不可轻易回退的方案，或接受整体交付。验证、独立 review 和 owner gate 都应与风险相称。
这种分工让 AI 成为高效执行者，同时保留程序员对软件整体的可观测、可控制和可演进责任。
项目知识是一项工程资产
领域术语、需求、架构决定、失败经验和验收证据不应该只存在于聊天记录中。但把它们全部复制进一个新档案馆，同样会制造漂移。
CodeStable 坚持一个事实只有一个 canonical owner：稳定产品事实回到项目文档，结构性取舍进入 ADR， 尚未被更强 owner 承接的经验暂存于 lessons。
共享语言同样遵守这个原则。它只在术语歧义会改变行为或路线时触发：Feature 收敛局部语义，Epic 收敛概念关系；已有项目领域文档继续拥有稳定定义，不为每个任务复制词典。
会话必读事实进入 attention，长期 Epic 契约进入永久 Epic 文档。
路线尚不清晰的大需求不能直接伪装成完整计划。永久 Epic 文档本身就是路线地图：决策依赖派生 frontier，agent 解决事实，只有产品判断与真实取舍进入 HITL；只有路线清晰、可审查、可执行后才交给 执行 agent。探索与最终路线共用同一个事实 owner，不落独立 issue 地图。
只有活动中的跨会话状态使用临时 work 游标。普通任务以 diff、测试输出和交付说明作为证据，不额外生产阶段文档。
经验通过验证演化
经验不是活动日志。CodeStable 在任务中静默识别真正改变方案、根因或验证，或明确排除一个具体且合理的错误路径 的晶化时刻，只把有证据、适用于本次精确 diff 之外且尚无更强 owner 的结论作为候选。没有强信号时不增加收尾仪式。
lesson 是 staging，不是永久档案。它先被观察，再由独立后续任务验证；事实变化时会退役，能机械化 时则进入测试或 checker。这样项目积累的是降低失败率的方法，而不是不断增长的文字规则。
有意不做的事
- 不提供 Agent 团队、角色队列或自动接力系统。
- 不替项目新建一套 requirements、domain model 或 ADR 真相。
- 不用大量阶段、模板和 runtime gate 防御强模型。
- 不追求完全无人干预；关键产品决定仍由 owner 承担。
- 不承诺未收敛讨论跨会话恢复。
演进方向
CodeStable 的目标不是让流程越来越多。某项约束一旦被模型能力、宿主能力或更简单的证据稳定替代，就应该被删掉。