dev_harness/README.md

DevHarness

DevHarness 是一个以 Gitea 工单管理任务过程、以 Gitea Wiki 管理长期文档、以 Git 提交记录代码变更、由人负责确认和验收的 AI 辅助开发模板。

它约束的是开发过程，不限制项目使用 Python、Go、JavaScript 或其他技术栈。

工作闭环

讨论需求或缺陷
  -> 阅读代码并提出方案
  -> 人工确认方案
  -> 创建 Epic / MVP / 单元任务工单
  -> Agent 实现并测试
  -> 提交代码并更新工单
  -> 人工验收
  -> 先归档 Wiki，再导出 docs/task 镜像
  -> 关闭工单并更新父工单

快速开始

1. 复制或克隆本仓库，并修改仓库名称。

2. 在 Gitea Wiki 填写项目档案，再运行 python scripts/sync_wiki_docs.py 导出 本地镜像。

3. 把项目不可违反的安全规则写入根目录或子项目的 AGENTS.md。

4. 创建 Gitea 远端仓库并推送当前引导提交。

5. 配置 wiki-docs.json 的页面映射；读取 Wiki 可匿名访问或使用 GITEA_TOKEN，写 Wiki 必须通过环境变量提供令牌。

6. 使用 .gitea/issue_template/ 中的模板创建第一个 Epic、MVP 和单元任务。

7. 开始产品代码前运行：

   python scripts/check_harness.py --strict
   

新仓库在 Gitea 尚未建立前允许一次不关联工单的引导提交。远端和工单系统配置完成后，所有改变程序行为的工作都必须先有单元任务工单。

目录

AGENTS.md                         Agent 的通用工作规则
CLAUDE.md                         Claude Code 的规则入口
.gitea/issue_template/            Epic、MVP、单元任务工单模板
docs/00-project-profile.md        Wiki 项目档案的只读镜像
docs/01-workflow.md               Wiki 开发工作流的只读镜像
docs/templates/task-archive.md    Wiki 任务归档模板的只读镜像
docs/task/                        Wiki 任务归档页的只读镜像
wiki-docs.json                    Wiki 页面到本地镜像的显式映射
scripts/check_harness.py          模板和归档的最小自检
scripts/sync_wiki_docs.py         单向导出或检查 Wiki 镜像
scripts/new_task_archive.py       先创建 Wiki 任务归档，再导出镜像

设计原则

• 人决定目标、范围和验收结果，Agent 负责检查、实现和验证。
• 工单记录实施过程，Wiki 保存长期有效的最终事实，docs/ 只保存可审查的镜像。
• 一个单元工单只解决一个可独立测试和回退的问题。
• 实现提交与归档提交分开，便于审查与追溯。
• 凭据、个人数据和生产数据不得进入代码、工单或归档。