From c9f1bc883211aa8bb2d8b7c8f7a78a5a2e7b7a3e Mon Sep 17 00:00:00 2001 From: QiuSW <105186638@qq.com> Date: Sat, 8 Aug 2026 10:03:38 +0800 Subject: [PATCH] =?UTF-8?q?refactor:=20=E7=B2=BE=E7=AE=80=20AGENTS=20?= =?UTF-8?q?=E9=87=8D=E5=A4=8D=E8=AF=B4=E6=98=8E=20(#5)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 47 ++++++++++++------------------------ dev_scripts/check_harness.py | 5 ++++ 2 files changed, 21 insertions(+), 31 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index e40217c..4e6f7c8 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -74,19 +74,10 @@ Gitea 不可用时，输出完整工单草稿并说明阻塞。未经用户明 ## 4. 工单层级 -```text -Epic：完整产品目标和长期路线 -└── MVP：第一个可交付版本 - └── 单元任务：唯一的实施单位 -``` - -- Epic 维护总体目标、范围、路线、风险和所有任务索引。 -- MVP 维护首个可交付范围、阶段、集成风险和任务清单。 -- 单元任务记录具体方案、修改范围、验收标准、过程和测试结果。 -- 父工单只维护 `- [ ] #编号` 或 `- [x] #编号` 的索引和汇总，不复制子工单全文。 +- 单元任务是唯一正式实施单位，记录方案、范围、验收标准、过程和测试结果。 +- Epic 和 MVP 只维护目标、风险、汇总及 `- [ ] #编号` / `- [x] #编号` 子工单索引，不复制单元任务全文。 - 新任务先建单元工单，再把编号同步到所属 MVP 和 Epic。 - -工单模板位于 `.gitea/issue_template/`。 +- 详细层级、状态和模板入口见 [开发工作流](docs/01-workflow.md) 与 [业务规则和术语](docs/03-business-rules-and-glossary.md)。 ## 5. 实施中的变化 @@ -107,17 +98,16 @@ Epic：完整产品目标和长期路线 ## 7. 完成、验收和归档 -1. 实现完成后逐项检查验收标准，并提交代码。 -2. 更新单元工单：最终方案、方案差异、测试结果、提交哈希和遗留问题。 -3. 工单保持“待验收”，用户没有明确验收通过前不得关闭。 -4. 运行 `python dev_scripts/new_task_archive.py <编号> "<短标题>"`，先在 Wiki 创建任务归档，再登记映射并导出 `docs/task/<编号>-<短标题>.md` 镜像。 -5. 读取确认 Wiki 页面，运行 `python dev_scripts/sync_wiki_docs.py --check` 校验镜像。 -6. 归档镜像单独提交，例如：`docs: 归档任务 #123`。 -7. 把 Wiki 页面、revision、镜像路径和提交哈希回写工单。 -8. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。 +1. 逐项完成验收、测试和实现提交，并把最终方案、差异、结果、提交及遗留问题写回工单。 +2. 工单保持“待验收”，用户没有明确验收通过前不得关闭。 +3. 运行 `python dev_scripts/new_task_archive.py <编号> "<短标题>"`，先创建 Wiki 归档，再登记并导出本地镜像。 +4. 读取确认 Wiki，运行 `python dev_scripts/sync_wiki_docs.py --check`；归档镜像单独提交，并把页面、revision、路径和提交哈希写回工单。 +5. 用户验收通过后关闭单元工单，并同步更新 MVP 和 Epic。 MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才能关闭 MVP。Epic 的全部范围完成后才能关闭 Epic。 +详细归档顺序和字段见 [开发工作流](docs/01-workflow.md)。 + ## 8. 可维护性 - 优先使用直白、常见的实现；不要为了少写几行引入晦涩技巧。 @@ -127,23 +117,18 @@ MVP 内所有单元任务通过后才能做 MVP 集成验收；MVP 通过后才 - Wiki 文档先写结论和用途，再写步骤；示例命令应可直接复制，本地 `docs/` 由同步工具生成。 - 面向初级维护者说明从哪里开始读、怎样运行和怎样验证。 -### 初级维护者的修改边界 +### 修改风险 -| 风险 | 示例 | 处理方式 | -|---|---|---| -| 低 | 文案、简单校验、查询条件、独立 UI、小范围回归 Bug | 初级程序员可在 Agent 协助下理解、修改和验证 | -| 中 | API、配置、依赖、跨模块逻辑、数据结构 | 由 Agent 实现，程序员检查差异并执行验证 | -| 高 | 权限、安全、并发、迁移、支付、删除数据、不可逆操作 | 停止修改，由 Agent 分析并等待人工确认 | +- 低风险修改可由初级程序员在 Agent 协助下处理；接口、配置、依赖、跨模块逻辑和数据结构由 Agent 实现并验证。 +- 权限、安全、并发、迁移、支付、删除数据和不可逆操作属于高风险；高风险修改必须停止，由 Agent 分析并等待人工确认。 +- 风险按影响范围判断，不按代码行数判断；示例见 [常见修改指南](docs/05-common-changes.md)。 -风险按影响范围判断，不按代码行数判断。 +### 文档影响 -### 核心文档与更新条件 - -- 新项目至少维护：新人入口、项目档案、架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、开发工作流和任务归档模板。 - 每个单元任务必须在工单中选择“无长期文档影响并说明原因”或列出需要更新的 Wiki 页面。 - 启动、测试、部署、排错命令，模块入口、目录职责、主要调用路径，配置、API、数据结构、状态、业务规则、安全边界、日志位置发生变化时，必须更新对应 Wiki。 - 普通内部重构只有在入口、行为、配置和验证方式均未改变时，才可以记录为不影响长期文档。 -- 稳定主题页描述项目现在怎样工作；工单和任务归档只解释某次为什么修改以及如何验证。新人不应依赖按时间阅读任务归档来理解当前系统。 +- 必需核心页面及结构以 `python dev_scripts/check_harness.py --strict` 和 [新项目文档初始化](docs/07-new-project-documentation-setup.md) 为准；稳定文档与任务归档的分工见 [开发工作流](docs/01-workflow.md)。 ## 9. 引导提交例外 diff --git a/dev_scripts/check_harness.py b/dev_scripts/check_harness.py index 5fe3f9d..56191f9 100644 --- a/dev_scripts/check_harness.py +++ b/dev_scripts/check_harness.py @@ -181,6 +181,11 @@ def check_agent_efficiency_rules(errors: list[str], root: Path = ROOT) -> None: "#### 渐进执行和修复", "#### 复用已验证事实", "#### 明确停止条件", + "单元任务是唯一正式实施单位", + "高风险修改必须停止", + "用户没有明确验收通过前不得关闭", + "长期文档必须先修改 Wiki", + "提交只包含当前工单相关文件", ) for section in missing_sections(content, required): errors.append(f"AGENTS.md 缺少：{section}")