diff --git a/docs/task/2-初级维护者文档体系.md b/docs/task/2-初级维护者文档体系.md new file mode 100644 index 0000000..94210b9 --- /dev/null +++ b/docs/task/2-初级维护者文档体系.md @@ -0,0 +1,81 @@ + +generated: true (请先修改 Gitea Wiki,禁止直接编辑本文件) +wiki_page: Task-2-Junior-Maintainer-Docs +wiki_url: http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-2-Junior-Maintainer-Docs.- +wiki_revision: e9128c0d5fdea740b6212083cef0e419e0282837 +synchronized_at: 2026-08-08T01:04:10Z + + +# 2 建立面向初级维护者的轻量项目文档体系 + +- 类型:需求 +- 所属 Epic:无 +- 所属 MVP / 版本:无 +- 状态:待验收 +- 日期:2026-08-08 +- Gitea 工单:[opc/dev_harness#2](http://ilaer.eicp.net:8418/opc/dev_harness/issues/2) +- Wiki 页面:Task-2-Junior-Maintainer-Docs +- Wiki revision:见本地镜像头 + +## 背景与目标 + +DevHarness 已具备工单、Wiki 主源和本地镜像流程,但缺少面向初级维护者的代码入口、业务规则、运行验证、简单修改和故障排查。目标是让初级程序员理解项目文档,并在 Claude/Codex Agent 协助下处理简单 Bug 和需求;大部分代码仍由 Agent 实现。 + +## 最终方案 + +- Home 提供 10~20 分钟阅读路径、五分钟验证命令、修改入口和停止条件。 +- 新增架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、新项目文档初始化六个稳定主题页。 +- 项目档案补充使用者、环境、适用版本、日志、测试数据和阅读入口。 +- 开发工作流和 Agent 规则采用低/中/高风险分级,不以代码行数判断风险。 +- 单元任务模板增加“文档影响”,入口、命令、配置、数据、业务和排错变化必须更新 Wiki。 +- Harness 检查核心页面映射、固定章节及任务模板字段;不把结构检查误认为语义质量判断。 +- 新项目使用明确初始化说明,不增加额外 Wiki 生成框架。 + +## 修改文件 + +- `AGENTS.md`:增加风险边界、核心文档和更新条件。 +- `CLAUDE.md`:增加代码地图、业务规则阅读顺序和文档影响要求。 +- `.gitea/issue_template/task.md`:增加文档影响检查项。 +- `README.md`:链接新项目初始化和新增镜像目录。 +- `wiki-docs.json`:登记六个新增核心页面。 +- `scripts/check_harness.py`:检查核心映射、章节和工单模板。 +- `tests/test_harness_docs.py`:覆盖成功、缺失章节和错误映射。 +- `docs/README.md`、`docs/00-project-profile.md`、`docs/01-workflow.md`:更新后的 Wiki 镜像。 +- `docs/02-architecture-and-code-map.md` 至 `docs/07-new-project-documentation-setup.md`:新增 Wiki 镜像。 + +## 验收结果 + +| 验收标准 | 结果 | +|---|---| +| Home 提供阅读顺序、启动、测试和代码入口 | 通过 | +| 核心页面职责明确且保持轻量结构 | 通过 | +| 简单修改和高风险停止边界清楚 | 通过 | +| 单元任务必须声明文档影响 | 通过 | +| 严格检查能发现页面、映射和章节问题 | 通过 | +| Wiki 与本地镜像一致 | 通过 | +| 自动化测试和严格检查通过 | 通过 | + +## 测试 + +- 执行命令:`python -m unittest discover -s tests -v` +- 结果:16/16 通过。 +- 执行命令:`python scripts/check_harness.py --strict` +- 结果:通过。 +- 执行命令:`python scripts/sync_wiki_docs.py --check` +- 结果:11/11 映射一致。 +- 执行命令:`python -m compileall -q scripts tests` +- 结果:通过。 +- 执行命令:`git diff --check` +- 结果:通过。 +- 人工验证:六个新增 Wiki 页面均可访问,Home 阅读路径、风险分级和初始化顺序完整。 +- **未验证部分**:尚未在全新业务仓库完整执行初始化,也未由真实初级程序员完成可用性测试。 + +## 遗留问题 + +首个采用该模板的业务项目应把“新人能否根据 Home 找到入口、运行测试并理解一次简单修改”纳入实际验收,再根据反馈精简或补充主题页。 + +## 相关提交 + +- `250b055` feat: 建立初级维护者文档体系 (#2) +- `b09658e` docs: 修正文档命令与初始化边界 (#2) +- `c8ccb62` test: 覆盖核心文档映射错误 (#2) diff --git a/wiki-docs.json b/wiki-docs.json index cf0cd5e..470f975 100644 --- a/wiki-docs.json +++ b/wiki-docs.json @@ -47,6 +47,10 @@ { "page": "Task-1-Wiki-文档主源", "path": "docs/task/1-Wiki-文档主源.md" + }, + { + "page": "Task-2-Junior-Maintainer-Docs", + "path": "docs/task/2-初级维护者文档体系.md" } ] }