@tea-agent/loop-agent 0.2.1 → 0.4.0

package/docs/development-principles.md

@@ -1,71 +1,73 @@
-# 开发原则
-
-loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
-
-## 操作立场
-
-项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
-
-- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
-- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `docs/`。
-- 工作以小步、可逆、可验证的增量推进。
-- 状态不确定时，先跑基线验证再开新工。
-- 完成由新鲜证据定义，而非意图或信心。
-
-## 原则
-
-1. 一次任务只推进一个有边界的工作块。
-2. 设计新行为前先搜索现有代码、文档、脚本与测试。
-3. Shell 验证是完成权威。
-4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
-5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
-6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
-7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
-8. 不要把隐藏流程状态只留在聊天里。
-9. 不要把占位实现当作已完成交付。
-10. 新增抽象前先沿用现有局部模式。
-
-## 仓库结构
-
-- 源码：`src/`
-- 测试：`test/`
-- Skill 指令：`skills/`
-- 验证与维护脚本：`scripts/`
-- 治理与交接产物：`docs/`
-
-## 变更纪律
-
-行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
-
-当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
-
-- 设计/契约文档 — 变更后的预期
-- 测试或验证脚本 — 变更后的行为
-- progress log 或 report — 非平凡交接证据
-- ADR — 架构或公开契约决策
-- 模板 — 重复流程可复用时
-
-除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
-
-## 搜索与复用
-
-实现前先检视现有系统：
-
-- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
-- 可用时用 `rg` 做文本搜索、`fd` 找文件。
-- 引入新 helper 前先读邻近测试与 helper。
-- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
-
-在搜索证明否则之前，假设系统可能已有部分解法。
-
-## 完成纪律
-
-完成声明必须回答：
-
-- 改了什么
-- 为何选此方案
-- 哪条命令验证、结果如何
-- 是否影响契约、文档、测试或脚本
-- 剩余风险或后续项
-
-验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。
+# 开发原则
+
+loop-agent 是面向 agentic coding 的工作流 runtime。仓库应保持小而显式、可验证。
+
+## 操作立场
+
+项目采用「人类掌舵、智能体执行」的工程模型。Agent 可实现、验证与总结，但持久意图与完成证据必须落在仓库中。
+
+这个模型吸收了 Anthropic 长时运行 agent harness、OpenAI Codex harness engineering、腾讯端到端 Harness Engineering 和社区 agent harness 实践中的共同经验：用短入口文档导航长期知识，用结构化任务状态和 handoff artifact 跨 session 传递事实，用独立验证和评审回路约束 agent 输出，并把人类注意力集中在意图、边界、架构和反馈系统上。面向使用者的背景资料收录在 `website/docs/practices/`。
+
+- 仓库是记录系统。决策、契约、计划、测试、报告与交接属于 tracked files。
+- `AGENTS.md` 是操作地图，不是知识 dump。长期方法论与决策属于 `docs/`。
+- 工作以小步、可逆、可验证的增量推进。
+- 状态不确定时，先跑基线验证再开新工。
+- 完成由新鲜证据定义，而非意图或信心。
+
+## 原则
+
+1. 一次任务只推进一个有边界的工作块。
+2. 设计新行为前先搜索现有代码、文档、脚本与测试。
+3. Shell 验证是完成权威。
+4. Runtime 状态在 `.harness/`；持久决策在 `docs/`。
+5. Pi writer 节点与可选 Cursor 写执行必须由显式 allowed/forbidden paths 约束。
+6. Pi review/planning 路径是 advisory，除非后跟确定性验证。
+7. 反复出现的约束应固化为文档、测试、脚本、检查或模板。
+8. 不要把隐藏流程状态只留在聊天里。
+9. 不要把占位实现当作已完成交付。
+10. 新增抽象前先沿用现有局部模式。
+
+## 仓库结构
+
+- 源码：`src/`
+- 测试：`test/`
+- Skill 指令：`skills/`
+- 验证与维护脚本：`scripts/`
+- 治理与交接产物：`docs/`
+
+## 变更纪律
+
+行为变更要更新测试；工作流或命令变更要更新文档与示例；治理变更要更新 `harness.json` 与相关检查脚本。
+
+当工作影响需求、行为、跨命令契约或 harness 规则时，更新对应持久产物：
+
+- 设计/契约文档 — 变更后的预期
+- 测试或验证脚本 — 变更后的行为
+- progress log 或 report — 非平凡交接证据
+- ADR — 架构或公开契约决策
+- 模板 — 重复流程可复用时
+
+除非 contract 明确说明必须一起移动，否则不要在一个工作块里混合无关重构、新功能与大规模文档迁移。
+
+## 搜索与复用
+
+实现前先检视现有系统：
+
+- 仓库已索引且任务需要理解代码时，优先用 CodeGraph。
+- 可用时用 `rg` 做文本搜索、`fd` 找文件。
+- 引入新 helper 前先读邻近测试与 helper。
+- 优先结构化 parser 与现有本地 API，避免 ad hoc 字符串处理。
+
+在搜索证明否则之前，假设系统可能已有部分解法。
+
+## 完成纪律
+
+完成声明必须回答：
+
+- 改了什么
+- 为何选此方案
+- 哪条命令验证、结果如何
+- 是否影响契约、文档、测试或脚本
+- 剩余风险或后续项
+
+验证失败时，报告失败命令与观察到的状态，而不是软化完成定义。