harness_coding_docs/README.md

Harness Coding 文档样本库

本仓库用于沉淀一个新项目交给 AI coding agent 开发前，建议准备的文档集合。

这些文档参考了 D:\opc_project\lingo\docs 的实际项目文档结构，抽象为可复用模板：从项目入口、愿景、需求、技术栈、架构、编码规则，到任务路线图、任务文件、API、路由和当前状态。

推荐文档集合

文档	作用
AGENTS.md	Codex / 通用 AI coding agent 的仓库级入口
CLAUDE.md	Claude Code 的仓库级薄入口
tasks.md	本样本库自身的维护任务列表
init.sh	标准启动与验证入口脚本（Unix shell / WSL / Git Bash），统一安装 + 验证 + 打印启动命令
init.ps1	标准启动与验证入口脚本（Windows 原生 PowerShell），与 init.sh 等价，按操作系统二选一
gitea.env.example	Gitea MCP 本机私有配置示例；复制后替换，真实文件不得入库
progress.md	可选：历史归档 / 项目级大事记；执行记录默认写各任务文件
docs/README.md	文档导航，总览所有项目文档
docs/00-ai-start-here.md	AI coding agent 的入口、阅读顺序、任务领取规则
docs/01-vision.md	项目为什么做、为谁做、什么不做
docs/02-requirements.md	产品需求、功能范围、优先级与验收标准
docs/07-user-stories.md	用户目标、业务价值、验收场景与 US / IX 追踪
docs/03-tech-stack.md	技术选型和运行命令
docs/04-architecture.md	系统结构、职责边界、数据模型、开发顺序
docs/05-coding-rules.md	AI 写代码前必须遵守的硬规则
docs/06-tasks.md	任务路线图：阶段划分、里程碑、待办池（只读，不跟踪单任务状态）
docs/tasks/README.md	默认任务管理：一任务一文件 docs/tasks/T-<编号>.md，单/多 agent 通用
docs/adoption-checklist.md	已有项目接入 harness 文档的迁移清单
docs/api.md	API 合约模板
docs/routes.md	页面路由、组件归属、导航规则
docs/08-interaction-checklist.md	UI 交互、状态反馈、无障碍与验收证据
docs/design/	页面原型输入约定：单文件 HTML 低保真原型，用于枚举交互
docs/clean-state-checklist.md	会话收尾检查清单，保证下一轮无需人工修复即可开工
docs/current-state.md	当前实现状态快照，防止计划和代码现实脱节
docs/agent-context.json	机器可读上下文路由：最小必读、任务类型和 SHA 刷新规则
docs/agent-context.schema.json	上下文清单结构契约
docs/agent-context.md	上下文清单的读取、缓存、权威来源和断连降级说明
docs/gitea-mcp.md	可选：Gitea MCP 共享文档与任务协调接入、安全和降级规则
docs/gitea-collaboration.md	可选：Issue / 任务文件 / PR 映射、串行分配和写路径防撞协议
scripts/validate_agent_context.py	零第三方依赖校验上下文清单、Schema 和仓库相对路径
scripts/setup_gitea_labels.py	默认只读预览远端差异、显式 --apply 的 Gitea 协作标签初始化脚本
scripts/validate_harness_governance.py	离线检查导航、链接、任务、模板、工作流和敏感信息
scripts/audit_gitea_coordination.py	只读审计远端任务映射、状态、分支、PR、写路径和过期 claim
scripts/test_gitea_claim_race.py	显式 --apply 的目标实例 claim 分支并发兼容性 smoke
tests/test_governance.py	标准库治理回归测试
.gitea/ISSUE_TEMPLATE/task.md / .gitea/PULL_REQUEST_TEMPLATE.md	Gitea 任务 Issue 与 PR 模板
.gitea/workflows/harness-governance.yml	push / PR 离线治理检查模板；需仓库 Actions 和 runner 已启用
docs/method-map.md	失败模式 → 首要修复 → 工件的诊断 / 导航对照表
docs/evaluator-rubric.md	单次会话输出的结构化评审评分表
docs/quality-document.md	代码库长期健康度追踪（产品域 × 架构层评级）

使用方式

最小必选集

只想先让 agent 稳定工作时，先复制这些文件：

• AGENTS.md
• CLAUDE.md
• docs/00-ai-start-here.md
• docs/agent-context.json、docs/agent-context.schema.json、docs/agent-context.md
• docs/05-coding-rules.md
• docs/06-tasks.md
• docs/tasks/（README.md + _template.md）
• docs/current-state.md
• scripts/validate_agent_context.py
• init.sh 或 init.ps1

完整推荐集

新项目从零开始时，建议复制根目录入口文件和 docs/ 目录（含 docs/tasks/），并按操作系统选择 init.sh 或 init.ps1。复制后按顺序处理：

1. 从 docs/01-vision.md 和 docs/02-requirements.md 开始替换业务内容；有 UI / UX 时，同时完成 docs/07-user-stories.md 和 docs/08-interaction-checklist.md。
2. 在 docs/03-tech-stack.md 固定技术选型，不确定的选项标为待定。
3. 在 docs/04-architecture.md 写清事实来源、数据模型、系统边界。
4. 在 docs/06-tasks.md 拆出阶段路线图和建议任务；开工时按 docs/tasks/README.md 把任务落成 docs/tasks/T-<编号>.md，要求 AI 每轮只领取一个任务。
5. 替换 init.sh 或 init.ps1 顶部三个命令，并把真实命令同步到 docs/03-tech-stack.md、docs/00-ai-start-here.md 和 docs/current-state.md。
6. 执行记录写进各任务文件的 ## 执行记录，用 docs/current-state.md 覆盖更新当前快照；progress.md 可选，用作历史归档或项目级大事记。
7. 开始编码前，让 agent 先读 docs/00-ai-start-here.md。

已有项目接入

已有代码仓库不要急着让 agent 做新功能。先按 docs/adoption-checklist.md 建立当前状态、启动路径、验证路径和任务文件；第一轮任务优先修复基线，而不是扩大功能范围。

可选增强集

项目进入多轮长期开发后，再按需启用：

• docs/gitea-mcp.md：需要跨 agent 读取 Gitea 文档、Issue 和 PR 时启用。
• docs/gitea-collaboration.md：需要 dispatcher 串行分配、独立分支 / worktree 和写路径防撞时启用。
• scripts/validate_harness_governance.py：在本地和 CI 使用同一套离线一致性检查。
• docs/clean-state-checklist.md：每轮结束前检查仓库是否可恢复。
• docs/method-map.md：遇到失败模式时定位该补哪个工件。
• docs/evaluator-rubric.md：评审单次 agent 输出质量。
• docs/quality-document.md：追踪代码库长期健康度。

tasks.md 是本样本库自身的维护任务；复制到新项目后，项目任务默认以一任务一文件写在 docs/tasks/，阶段路线图维护在 docs/06-tasks.md。

核心原则：文档不是给人看的装饰，而是给 agent 执行时用的约束、事实来源和验收标准。