refactor: 精简 AGENTS 重复说明 (#5)
This commit is contained in:
QiuSW
@@ -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. 引导提交例外
|
||||
|
||||
|
||||
@@ -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}")
|
||||
|
||||
Reference in New Issue
Block a user