opc/dev_harness
2
0
Fork 0
Code Issues 3 Pull Requests Actions Packages Projects Releases Wiki Activity

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

New Issue
Closed
opened 2026-08-08 08:54:31 +08:00 by ila · 4 comments
ila commented 2026-08-08 08:54:31 +08:00
Owner
Copy Link
Copy Source

基本信息

  • 类型：需求
  • 所属 Epic：无
  • 所属 MVP / 版本：无
  • 阶段：已完成

要解决什么

当前 DevHarness 已建立 Gitea Wiki 主源和本地 docs 镜像，但基础文档主要覆盖项目档案、工作流和任务归档。对于“初级程序员能看懂项目文档，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求”的目标，尚缺代码入口、业务规则、运行验证、常见修改和故障排查等稳定导航，也没有强制 Agent 判断代码变更的文档影响。

目标是建立轻量、任务导向、可检查的项目文档骨架，不把文档扩展成完整教材。

做什么 / 不做什么

  • 做：
    • 优化 Home 的新人阅读路径。
    • 扩展项目档案中的运行环境、日志、测试数据和适用版本信息。
    • 新增“架构与代码地图”“业务规则与术语”“本地开发与验证”“常见修改指南”“故障排查”“新项目文档初始化”六个 Wiki 页面。
    • 在 AGENTS.md 中增加低/中/高风险修改边界和必须更新 Wiki 的触发条件。
    • 在单元任务模板中增加“文档影响”检查。
    • 扩展 Harness 检查，验证核心页面映射、必需章节和镜像元数据。
    • 为新增检查编写自动化测试，并同步本地 docs 镜像。
  • 不做：
    • 不要求逐文件、逐函数编写说明。
    • 不生成完整 API/数据库教材。
    • 不允许初级程序员自行处理权限、安全、并发、迁移、支付或删除数据等高风险修改。
    • 不实现 docs → Wiki 反向同步。
    • 不自动删除或重命名 Wiki 页面。

已确认方案

核心文档保持少而固定：

  1. Home：10～20 分钟新人入口和阅读顺序。
  2. Project-Profile：环境、命令、配置、日志、测试数据和版本。
  3. Architecture-and-Code-Map：功能到目录、入口、核心对象、测试和风险的映射。
  4. Business-Rules-and-Glossary：术语、状态、规则和不可破坏约束。
  5. Local-Development-and-Verification：按“目的、命令、预期、失败检查”描述运行验证。
  6. Common-Changes：简单 Bug/需求的修改步骤和停止条件。
  7. Troubleshooting：按“现象、原因、检查、处理”排错。
  8. Development-Workflow：文档更新触发条件和任务闭环。
  9. New-Project-Documentation-Setup：复制模板后由 Agent 初始化 Wiki 的步骤。
  10. Task-Archive-Template：任务追溯，不作为新人主入口。

风险分级：

  • 低风险：文案、简单校验、查询条件、独立 UI、小范围回归 Bug，可由初级程序员在 Agent 协助下处理。
  • 中风险：API、配置、依赖、跨模块逻辑和数据结构，由 Agent 实现，程序员检查和验证。
  • 高风险：权限、安全、并发、迁移、支付和删除数据，必须先分析并等待人工确认。

预计修改文件：

  • Gitea Wiki 相关页面
  • wiki-docs.json 与 docs/** 镜像
  • AGENTS.md
  • .gitea/issue_template/task.md
  • README.md、CLAUDE.md
  • scripts/check_harness.py
  • tests/**

文档影响

  • 更新项目档案、开发工作流和新人入口。
  • 新增架构、业务、开发验证、常见修改、排错和初始化主题页。
  • 更新任务模板和文档检查规则。

验收标准

  • 初级程序员可从 Home 找到建议阅读顺序、启动、测试和代码入口。
  • 核心 Wiki 页面职责明确、内容简洁，并包含可复制或待项目填写的固定结构。
  • 简单修改与必须停止的风险边界清楚。
  • Agent 在任务工单中必须声明文档影响。
  • Harness 严格检查能发现核心页面缺失、映射缺失和必需章节缺失。
  • Wiki 与本地 docs 镜像 revision、正文一致。
  • 自动化测试和严格检查通过。

验证方式

python -m unittest discover -s tests -v
python scripts/check_harness.py --strict
python scripts/sync_wiki_docs.py --check
python -m py_compile scripts/check_harness.py tests/test_harness_docs.py
git diff --check

人工检查 Home 阅读路径、风险分级、常见修改示例和新项目初始化步骤。

风险和回退

风险：文档页面过多导致维护成本增加；通用模板被误认为真实项目事实；核心页面与任务归档混淆。

控制：只增加六个固定主题页；所有模板段落明确要求用真实项目事实替换；任务归档不放入新人阅读主线；自动检查只校验结构和映射，不声称能判断语义质量。

回退：通过 Wiki revision 恢复页面，通过 Git 提交恢复规则、映射和镜像。

## 基本信息 - 类型：需求 - 所属 Epic：无 - 所属 MVP / 版本：无 - 阶段：已完成 ## 要解决什么 当前 DevHarness 已建立 Gitea Wiki 主源和本地 docs 镜像，但基础文档主要覆盖项目档案、工作流和任务归档。对于“初级程序员能看懂项目文档，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求”的目标，尚缺代码入口、业务规则、运行验证、常见修改和故障排查等稳定导航，也没有强制 Agent 判断代码变更的文档影响。 目标是建立轻量、任务导向、可检查的项目文档骨架，不把文档扩展成完整教材。 ## 做什么 / 不做什么 - 做： - 优化 Home 的新人阅读路径。 - 扩展项目档案中的运行环境、日志、测试数据和适用版本信息。 - 新增“架构与代码地图”“业务规则与术语”“本地开发与验证”“常见修改指南”“故障排查”“新项目文档初始化”六个 Wiki 页面。 - 在 AGENTS.md 中增加低/中/高风险修改边界和必须更新 Wiki 的触发条件。 - 在单元任务模板中增加“文档影响”检查。 - 扩展 Harness 检查，验证核心页面映射、必需章节和镜像元数据。 - 为新增检查编写自动化测试，并同步本地 docs 镜像。 - 不做： - 不要求逐文件、逐函数编写说明。 - 不生成完整 API/数据库教材。 - 不允许初级程序员自行处理权限、安全、并发、迁移、支付或删除数据等高风险修改。 - 不实现 docs → Wiki 反向同步。 - 不自动删除或重命名 Wiki 页面。 ## 已确认方案 核心文档保持少而固定： 1. Home：10～20 分钟新人入口和阅读顺序。 2. Project-Profile：环境、命令、配置、日志、测试数据和版本。 3. Architecture-and-Code-Map：功能到目录、入口、核心对象、测试和风险的映射。 4. Business-Rules-and-Glossary：术语、状态、规则和不可破坏约束。 5. Local-Development-and-Verification：按“目的、命令、预期、失败检查”描述运行验证。 6. Common-Changes：简单 Bug/需求的修改步骤和停止条件。 7. Troubleshooting：按“现象、原因、检查、处理”排错。 8. Development-Workflow：文档更新触发条件和任务闭环。 9. New-Project-Documentation-Setup：复制模板后由 Agent 初始化 Wiki 的步骤。 10. Task-Archive-Template：任务追溯，不作为新人主入口。 风险分级： - 低风险：文案、简单校验、查询条件、独立 UI、小范围回归 Bug，可由初级程序员在 Agent 协助下处理。 - 中风险：API、配置、依赖、跨模块逻辑和数据结构，由 Agent 实现，程序员检查和验证。 - 高风险：权限、安全、并发、迁移、支付和删除数据，必须先分析并等待人工确认。 预计修改文件： - Gitea Wiki 相关页面 - `wiki-docs.json` 与 `docs/**` 镜像 - `AGENTS.md` - `.gitea/issue_template/task.md` - `README.md`、`CLAUDE.md` - `scripts/check_harness.py` - `tests/**` ## 文档影响 - [x] 更新项目档案、开发工作流和新人入口。 - [x] 新增架构、业务、开发验证、常见修改、排错和初始化主题页。 - [x] 更新任务模板和文档检查规则。 ## 验收标准 - [x] 初级程序员可从 Home 找到建议阅读顺序、启动、测试和代码入口。 - [x] 核心 Wiki 页面职责明确、内容简洁，并包含可复制或待项目填写的固定结构。 - [x] 简单修改与必须停止的风险边界清楚。 - [x] Agent 在任务工单中必须声明文档影响。 - [x] Harness 严格检查能发现核心页面缺失、映射缺失和必需章节缺失。 - [x] Wiki 与本地 docs 镜像 revision、正文一致。 - [x] 自动化测试和严格检查通过。 ## 验证方式 ```powershell python -m unittest discover -s tests -v python scripts/check_harness.py --strict python scripts/sync_wiki_docs.py --check python -m py_compile scripts/check_harness.py tests/test_harness_docs.py git diff --check ``` 人工检查 Home 阅读路径、风险分级、常见修改示例和新项目初始化步骤。 ## 风险和回退 风险：文档页面过多导致维护成本增加；通用模板被误认为真实项目事实；核心页面与任务归档混淆。 控制：只增加六个固定主题页；所有模板段落明确要求用真实项目事实替换；任务归档不放入新人阅读主线；自动检查只校验结构和映射，不声称能判断语义质量。 回退：通过 Wiki revision 恢复页面，通过 Git 提交恢复规则、映射和镜像。
ila commented 2026-08-08 08:54:51 +08:00
Author
Owner
Copy Link
Copy Source

用户已确认方案，开始实施。工作区干净；先创建和更新线上 Wiki，再登记映射、导出 docs 镜像，最后修改并验证 Harness 规则。

用户已确认方案，开始实施。工作区干净；先创建和更新线上 Wiki，再登记映射、导出 docs 镜像，最后修改并验证 Harness 规则。
ila commented 2026-08-08 09:03:10 +08:00
Author
Owner
Copy Link
Copy Source

实现完成，进入待验收

最终方案

  • 新增架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、新项目文档初始化六个 Wiki 主题页。
  • Home 改为 10～20 分钟新人入口，给出阅读顺序、五分钟命令、常见修改入口和高风险停止条件。
  • 项目档案增加使用者、适用版本、环境、阅读入口、日志和测试数据说明。
  • 开发工作流增加低/中/高风险边界、每任务文档影响和稳定主题页与任务归档的分工。
  • AGENTS.md、CLAUDE.md 和单元任务模板同步强制上述规则。
  • check_harness.py 固定检查 10 个核心 Wiki 页面映射、9 份新人核心文档章节以及任务模板的文档影响字段。
  • 新增结构与失败路径测试；检查只验证结构事实，不声称自动判断文档语义质量。
  • 新项目采用初始化说明而非额外生成框架，保持维护成本低。

方案差异与修正

  • 选择“初始化说明”而不是新建 Wiki 初始化脚本，避免引入额外写入工具和凭据处理。
  • 审查时发现 Windows 下 python -m py_compile scripts/*.py 不可靠，已改为实测通过的 python -m compileall -q scripts tests。
  • 新项目清理 DevHarness 历史归档增加了明确前置确认和禁止在原仓库执行的边界。

验证结果

  • 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 页面 HTTP 检查：全部返回 200。
  • 人工检查：Home 阅读路径、风险分级、常见修改步骤、故障表和初始化顺序完整。
  • 未验证部分：尚未在一个全新的业务仓库执行完整初始化，也未安排真实初级程序员做可用性测试；这些属于后续实际项目验收。

实现提交

  • 250b055 feat: 建立初级维护者文档体系 (#2)
  • b09658e docs: 修正文档命令与初始化边界 (#2)
  • c8ccb62 test: 覆盖核心文档映射错误 (#2)

状态保持待验收，用户确认前不关闭。

## 实现完成，进入待验收 ### 最终方案 - 新增架构与代码地图、业务规则与术语、本地开发与验证、常见修改、故障排查、新项目文档初始化六个 Wiki 主题页。 - Home 改为 10～20 分钟新人入口，给出阅读顺序、五分钟命令、常见修改入口和高风险停止条件。 - 项目档案增加使用者、适用版本、环境、阅读入口、日志和测试数据说明。 - 开发工作流增加低/中/高风险边界、每任务文档影响和稳定主题页与任务归档的分工。 - `AGENTS.md`、`CLAUDE.md` 和单元任务模板同步强制上述规则。 - `check_harness.py` 固定检查 10 个核心 Wiki 页面映射、9 份新人核心文档章节以及任务模板的文档影响字段。 - 新增结构与失败路径测试；检查只验证结构事实，不声称自动判断文档语义质量。 - 新项目采用初始化说明而非额外生成框架，保持维护成本低。 ### 方案差异与修正 - 选择“初始化说明”而不是新建 Wiki 初始化脚本，避免引入额外写入工具和凭据处理。 - 审查时发现 Windows 下 `python -m py_compile scripts/*.py` 不可靠，已改为实测通过的 `python -m compileall -q scripts tests`。 - 新项目清理 DevHarness 历史归档增加了明确前置确认和禁止在原仓库执行的边界。 ### 验证结果 - `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 页面 HTTP 检查：全部返回 200。 - 人工检查：Home 阅读路径、风险分级、常见修改步骤、故障表和初始化顺序完整。 - 未验证部分：尚未在一个全新的业务仓库执行完整初始化，也未安排真实初级程序员做可用性测试；这些属于后续实际项目验收。 ### 实现提交 - `250b055` feat: 建立初级维护者文档体系 (#2) - `b09658e` docs: 修正文档命令与初始化边界 (#2) - `c8ccb62` test: 覆盖核心文档映射错误 (#2) 状态保持待验收，用户确认前不关闭。
ila referenced this issue from a commit 2026-08-08 09:05:20 +08:00
docs: 归档任务 #2
ila commented 2026-08-08 09:05:29 +08:00
Author
Owner
Copy Link
Copy Source

归档与推送完成

  • Wiki 归档：Task-2-Junior-Maintainer-Docs
  • Wiki revision：e9128c0d5fdea740b6212083cef0e419e0282837
  • 本地镜像：docs/task/2-初级维护者文档体系.md
  • 实现提交：
    • 250b055 feat: 建立初级维护者文档体系 (#2)
    • b09658e docs: 修正文档命令与初始化边界 (#2)
    • c8ccb62 test: 覆盖核心文档映射错误 (#2)
  • 归档提交：5c432da docs: 归档任务 #2
  • 4 个任务提交已推送到 origin/main，远端当前为 5c432da。
  • 最终验证：16/16 单元测试通过、Harness 严格检查通过、12/12 Wiki 映射一致、Python compileall 与 diff 检查通过、工作区干净。
  • 验收标准已逐项勾选；工单保持“待验收”，用户确认前不关闭。

遗留验证仍为：首个实际业务项目应安排一次真实初级维护者试用，根据反馈调整文档密度。

## 归档与推送完成 - Wiki 归档：[Task-2-Junior-Maintainer-Docs](http://ilaer.eicp.net:8418/opc/dev_harness/wiki/Task-2-Junior-Maintainer-Docs.-) - Wiki revision：`e9128c0d5fdea740b6212083cef0e419e0282837` - 本地镜像：`docs/task/2-初级维护者文档体系.md` - 实现提交： - `250b055` feat: 建立初级维护者文档体系 (#2) - `b09658e` docs: 修正文档命令与初始化边界 (#2) - `c8ccb62` test: 覆盖核心文档映射错误 (#2) - 归档提交：`5c432da` docs: 归档任务 #2 - 4 个任务提交已推送到 `origin/main`，远端当前为 `5c432da`。 - 最终验证：16/16 单元测试通过、Harness 严格检查通过、12/12 Wiki 映射一致、Python compileall 与 diff 检查通过、工作区干净。 - 验收标准已逐项勾选；工单保持“待验收”，用户确认前不关闭。 遗留验证仍为：首个实际业务项目应安排一次真实初级维护者试用，根据反馈调整文档密度。
ila commented 2026-08-08 09:12:12 +08:00
Author
Owner
Copy Link
Copy Source

用户已于 2026-08-08 明确验收通过。Wiki 归档状态已更新为“已完成”，revision：9bf07c395c959501d995cfe7250623438c53dba7；本地镜像已通过提交 c69c0fd 推送到 main。本工单无父级 MVP/Epic，现按流程关闭。

用户已于 2026-08-08 明确验收通过。Wiki 归档状态已更新为“已完成”，revision：`9bf07c395c959501d995cfe7250623438c53dba7`；本地镜像已通过提交 `c69c0fd` 推送到 `main`。本工单无父级 MVP/Epic，现按流程关闭。
ila closed this issue 2026-08-08 09:12:16 +08:00
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
No items
No labels
Milestone
No items
No Milestone
Projects
Clear projects
No projects
Assignees
Clear assignees
admin ila
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: opc/dev_harness#2