CodeT 如何构建文本驱动、插件化的软件工程 Coding Agent？
CodeT 构建文本驱动、插件化的软件工程 Coding Agent，关键是把规则、计划、记忆和协作状态保存为可读文本，再把每项能力拆成 Skill 与薄 Extension，而不是修改底层 Agent 内核。底层 Pi 负责对话、工具调用和上下文编排，CodeT 只定义工程语义与可独立演进的能力。
文本不是导出格式，而是事实源
CodeT 将 Text as Truth 作为核心原则：项目规范写入 AGENTS.md 和 RULES.md，任务计划写入 TODO.md 或 PLAN.md，过程状态通过 Markdown 与 JSONL 保存。代码、规则、记忆和任务产物因此都能被普通编辑器读取，也能纳入 Git 差异审查。
这种结构适合个人维护的 Coding Agent，因为状态不依赖专用数据库才能解释。Agent 进程退出后，下一次会话仍可从项目文本恢复约束；出现错误结论时，开发者也能直接修改文件并通过提交历史追溯变化。
| 信息类型 | 建议载体 | 主要作用 |
|---|---|---|
| 长期项目规则 | AGENTS.md、RULES.md | 约束工具、编码风格和工作边界 |
| 当前任务计划 | PLAN.md、TODO.md | 记录步骤、依赖与完成状态 |
| 执行事件 | JSONL | 追加保存命令、结果与时间顺序 |
| 代码变更 | 源码与 Git | 审查实际修改并支持回退 |
Skill 与 Extension 各自承担什么
Skill 适合保存自然语言可表达的工作方法，例如如何初始化项目、怎样检查计划或如何处理一次失败。Extension 使用 TypeScript 封装需要稳定入口或工具集成的能力。两者组合后，一项能力既有可阅读的工程规则，也有可调用的薄适配层。
Extension 应保持足够薄，只负责注册命令、读取必要参数并把任务交回 Agent。复杂决策、上下文选择和工具调用顺序仍由底层运行时负责。如果把业务编排全部写进 Extension，插件就会逐渐复制一套新的 Agent 循环，后续难以升级内核。
明确 Pi 与 CodeT 的调度边界
底层 Pi 负责命令解析、Skill 与 Extension 路由、工具调用决策、上下文管理和多轮对话。CodeT 负责定义命令含义、提供工程技能、包装工具以及维护项目规则文件。这个边界使 CodeT 可以替换或升级插件，而不必接管模型会话状态。
CodeT 不实现命令之间的隐藏调用链，也不自行编排子 Agent。一个命令需要后续动作时，应把结果写成明确状态，由 Pi 或下一次会话决定如何继续。这样可以避免两个调度器同时控制执行顺序，减少重复调用和难以复现的状态跳转。
上下文加载从目录规则开始
会话启动时可以从当前工作目录向上查找项目级规则，再与用户级规则合并。越靠近当前项目的文件优先级越高，使公共规范可以复用，同时允许具体仓库覆盖。加载结果应显示来源文件和生效顺序，避免同名规则发生冲突时无法解释。
CodeT 的方案不要求数据库缓存解析结果，而是在启动时重新扫描文本。这个选择减少了缓存失效问题，适合规则文件数量有限的项目；大型仓库若后续加入缓存，则必须绑定文件摘要，并在规则修改时立即失效。
通过显式失败保持可控
命令失败时，CodeT 不自动重试、不隐藏错误，也不擅自回滚，而是把错误直接输出到终端或状态文件。修复由开发者或后续 Agent 会话决定。显式失败可以阻止错误前提在自动循环中不断放大，也便于保留第一现场。
这并不意味着完全放弃恢复能力。Extension 仍应返回结构化错误码、失败步骤和已产生的文件；状态文件记录可继续位置。自动重试只适合经过分类的临时故障，并且必须设置次数和退避，不能把所有命令失败都当成网络抖动。
用实际问题推动插件演进
CodeT 采用渐进演进方式：从最小初始化能力开始，在真实项目中发现重复问题，再把稳定做法提炼成规则、Skill 或 Extension。一次偶发问题先记录，不立即扩展内核；只有同类问题反复出现且能定义清楚输入和验收条件时，才固化为插件。
- 在项目中保留失败现象和相关上下文。
- 人工确认问题是否具有可重复模式。
- 先把解决步骤写成可审查的 Skill。
- 只有需要稳定工具入口时再增加薄 Extension。
- 用同一类任务验证规则是否真正减少失败。
建立最小可验收闭环
实现第一版时，可以只提供项目初始化、规则加载、计划记录和一个工具命令。验收时确认规则优先级可解释、所有状态文本能被 Git 跟踪、Extension 不保存隐式会话状态、命令失败会留下完整信息，并且移除某个插件后底层 Agent 仍可运行。
文本驱动的优势是透明和可迁移，限制则是结构约束较弱、文件可能逐渐膨胀。应为 Markdown 规定固定章节，为 JSONL 定义事件 Schema，并定期压缩过期过程信息。只要保持“内核负责调度、插件负责能力、文本负责事实”的边界，CodeT 式架构就能在不堆叠复杂基础设施的前提下持续演进。
