harness_coding_docs/docs/README.md

# 项目文档导航

> 复制到新项目后，先替换本文中的项目名称和一句话定位，再逐个补齐后续文档。

## 一句话定位

【项目名】是一个【目标用户】使用的【产品类型 / 系统类型】，用于解决【核心问题】，第一版先完成【MVP 闭环】。

示例：

> 这是一个面向小团队的工单协作系统，第一版先跑通「提交工单 -> 分派 -> 处理 -> 关闭」闭环。

## 文档导航

- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的薄入口，具体规则以 `AGENTS.md` 为准。
- [`../tasks.md`](../tasks.md)：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。
- [`../progress.md`](../progress.md)：可选历史归档 / 项目级大事记；执行记录默认写各任务文件的 `## 执行记录`。
- [仓库导览](../graph/repo-tour.md)：给新接手者的结构、工作流和任务生命周期流程图；描述样本库自身，复制模板到新项目时可不带。
- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
- [需求](02-requirements.md)：要什么、功能范围、优先级、验收标准，不写技术实现。
- [用户故事清单](07-user-stories.md)：用户目标、业务价值、验收场景与 US / IX 关联。
- [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
- [任务路线图](06-tasks.md)：阶段划分、里程碑和待办池；只读，不跟踪单任务状态。
- [任务文件（默认）](tasks/README.md)：一任务一文件 `docs/tasks/T-<编号>.md`，单/多 agent 通用，每个 agent 同时只做一个；启用 Gitea 后由 Issue 承担实时状态。
- [已有项目接入清单](adoption-checklist.md)：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
- [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
- [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
- [交互清单](08-interaction-checklist.md)：页面 / 组件交互、状态反馈、无障碍与验收证据。
- [设计原型输入约定](design/README.md)：单文件 HTML 低保真原型的形态、权威性边界和工作流，用于生成交互清单。
- [当前实现状态](current-state.md)：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
- [Agent 上下文清单](agent-context.md) / [`agent-context.json`](agent-context.json) / [`Schema`](agent-context.schema.json)：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
- [Gitea MCP 接入](gitea-mcp.md)：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。
- [Gitea 多 Agent 协作](gitea-collaboration.md)：可选的任务映射、串行分配、防重复 claim 和 PR 状态协议。
- [收尾检查清单](clean-state-checklist.md)：会话结束前逐项检查，保证下一轮无需人工修复即可继续。
- [方法对照表](method-map.md)：失败模式 → 首要修复 → 工件；出问题先查这里对症补工件。
- [评审评分表](evaluator-rubric.md)：单次会话输出的结构化评审（6 维 0-2 分 + 校准说明）。
- [质量文档](quality-document.md)：代码库长期健康度追踪，区别于单次输出评审。
- [`../init.sh`](../init.sh) / [`../init.ps1`](../init.ps1)：标准启动与验证入口脚本（根目录），统一安装、验证和启动命令。按操作系统二选一：WSL / Git Bash / macOS / Linux 用 `init.sh`，Windows 原生 PowerShell 用 `init.ps1`；换技术栈只改脚本顶部三个命令变量；未替换前脚本会主动失败，避免把示例命令误当真实项目命令。
- [`../scripts/validate_agent_context.py`](../scripts/validate_agent_context.py)：零第三方依赖校验上下文清单、Schema 和仓库相对路径。
- [`../scripts/setup_gitea_labels.py`](../scripts/setup_gitea_labels.py)：默认只读预览远端差异、显式写入的 Gitea 协作标签初始化脚本。
- [`../scripts/validate_harness_governance.py`](../scripts/validate_harness_governance.py)：离线检查导航、链接、任务、模板、工作流和敏感信息。
- [`../scripts/audit_gitea_coordination.py`](../scripts/audit_gitea_coordination.py)：只读审计远端任务映射、状态、分支、PR、写路径和过期 claim。
- [`../scripts/test_gitea_claim_race.py`](../scripts/test_gitea_claim_race.py)：显式写入并安全清理的 claim 分支并发兼容性 smoke。
- [`../tests/test_governance.py`](../tests/test_governance.py)：标准库治理回归测试。
- [Gitea Issue 模板](../.gitea/ISSUE_TEMPLATE/task.md) / [PR 模板](../.gitea/PULL_REQUEST_TEMPLATE.md)：任务映射、写路径和验证证据字段。
- [Gitea Actions 工作流](../.gitea/workflows/harness-governance.yml)：push / PR 离线治理模板；实际执行依赖仓库 Actions 和 runner。

## 任务 / 进度 / 当前状态

- `tasks/`（`docs/tasks/T-<编号>.md`）维护任务：规格、依赖、状态（frontmatter）和执行记录，一任务一文件。
- `06-tasks.md` 维护路线图：阶段划分、里程碑和待办池，不跟踪单任务状态。
- `current-state.md` 维护当前快照：当前目录、当前可运行命令、任务摘要和下一个可领取任务。
- `../progress.md` 可选：历史归档或项目级大事记，不逐任务追加。

已有项目接入时，先读 `adoption-checklist.md`，不要直接领取新功能。

## 维护原则

- 需求变化先改文档，再改代码。
- 代码现实变化后同步 `current-state.md`；任务长期状态和执行证据写进对应任务文件，启用 Gitea 时实时状态同步到 Issue。
- API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。