dev_harness/docs/task/2-初级维护者文档体系.md

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: 9bf07c395c959501d995cfe7250623438c53dba7 synchronized_at: 2026-08-08T01:11:23Z

2 建立面向初级维护者的轻量项目文档体系

• 类型：需求
• 所属 Epic：无
• 所属 MVP / 版本：无
• 状态：已完成
• 日期：2026-08-08
• Gitea 工单：opc/dev_harness#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)