DevHarness 文档中心

DevHarness 是一个以 Gitea 工单管理开发任务、以 Wiki 管理长期开发文档、以 Git 记录代码变更的 AI 辅助开发模板。目标是让初级程序员能够理解项目、运行验证，并在 Claude/Codex Agent 协助下处理简单 Bug 和需求。

第一次阅读

建议按以下顺序，用 10～20 分钟建立整体认识：

项目档案：项目目标、环境、命令和目录边界。
产品需求总览：长期需求、状态、原型和验收入口。
架构与代码地图：功能从哪里开始读、测试在哪里。
业务规则与术语：重要名词、状态和不能破坏的规则。
本地开发与验证：怎样运行、测试和排错。
常见修改指南：简单修改的步骤和停止条件。
故障排查：遇到错误时按什么顺序检查。
开发工作流：完整建单、实施、验收和可选快照流程。

从模板创建新项目时先阅读新项目文档初始化；向已有项目增量接入本流程时阅读已有项目接入 DevHarness 指南。需要为客户或其他岗位准备说明时，阅读交付文档指南，再按需使用岗位文档模板。

五分钟开始

在仓库根目录执行：

git status --short --branch
python dev_scripts/harness.py check --strict
python -m unittest discover -s tests -v
python dev_scripts/harness.py sync --check

预期结果：

工作区没有不属于当前任务的修改；
Harness 输出“DevHarness 检查通过”；
所有单元测试通过；
所有 Wiki 映射显示“一致”。

如果失败，先看故障排查，不要直接重置工作区或覆盖本地文档。

简单修改从哪里开始

想做什么	先读哪里	主要验证
修改文档	对应 Wiki 页面、Common-Changes	Wiki 同步检查
查看或更新产品需求	Product-Requirements-Overview、对应主题 Wiki 和工单	状态、链接和事实来源核对
接入已有项目	Existing-Project-Adoption-Guide	只读盘点、差异确认和分阶段验证
准备交付文档	Delivery-Documentation-Guide、Audience-Document-Template	目标岗位验证和 Wiki 同步检查
调整工单字段	`.gitea/issue_template/`、Development-Workflow	Harness 严格检查
修改同步行为	`dev_scripts/wiki_docs.py`、Architecture-and-Code-Map	单元测试和真实 Wiki 检查
增加结构检查	`dev_scripts/harness.py`	成功与失败测试
排查运行错误	Troubleshooting、项目档案	最小复现命令

权限、安全、并发、迁移、支付、删除数据或不可逆操作不属于简单修改，必须停止并交给 Agent 分析、等待人工确认。

事实来源

信息	事实来源
任务状态、讨论、阻塞、验收过程	Gitea 工单
长期产品需求的统一导航和状态	Gitea Wiki 的 Product-Requirements-Overview
架构、业务规则、开发规范、操作手册和交付文档	Gitea Wiki
源码和与特定代码版本强绑定的文档	Git 仓库
核心长期文档的离线浏览副本	Git 仓库中的 `docs/` Wiki 镜像
单次任务需求、实现、测试和验收	Gitea 工单；专项 Wiki 快照仅在人工明确要求时创建

本地 docs/ 不是编辑入口。长期文档必须先修改 Wiki，读取确认后再导出镜像。

项目入口

同步原则

修改 Wiki → 读取确认 → 导出 docs → 校验差异 → 提交镜像

核心页面和本地路径通过仓库中的 wiki-docs.json 显式映射；普通同步不处理任务归档。
默认不创建任务归档；只有用户明确要求专项快照或项目专用规则要求时，才创建 Wiki 归档并按需导出到 docs/task/。
镜像头记录来源页面、Wiki revision 和同步时间。
已映射镜像存在未提交修改时同步必须停止。
页面删除、重命名和映射变更必须人工确认。
长期事实发生变化而核心 Wiki 或必要同步失败时，相关任务不能标记为完成；没有长期文档变化时不运行 Wiki 同步，未请求可选归档不阻止任务完成。
凭据、个人数据和生产数据不得进入 Wiki 或镜像。