../AGENTS.md：Codex / 通用 AI coding agent 的仓库级入口。
../CLAUDE.md：Claude Code 的薄入口，具体规则以 AGENTS.md 为准。
../tasks.md：当前样本库自身的维护任务列表，不是复制到新项目后的业务任务看板。
../progress.md：可选历史归档 / 项目级大事记；执行记录默认写各任务文件的 ## 执行记录。
AI 开发入口：agent 每次开始工作的入口、阅读顺序和任务领取规则。
项目愿景：为什么做、为谁做、产品原则、非目标。
需求：要什么、用户故事、验收标准，不写技术实现。
技术栈：确定使用哪些框架、库、数据库、部署方式。
架构设计：系统结构、模块职责、数据模型、关键风险和开发顺序。
编码规则：AI 写代码前必须遵守的硬约束。
任务路线图：阶段划分、里程碑和待办池；只读，不跟踪单任务状态。
任务文件（默认）：一任务一文件 docs/tasks/T-<编号>.md，单/多 agent 通用，每个 agent 同时只做一个；启用 Gitea 后由 Issue 承担实时状态。
已有项目接入清单：把本模板补进已有代码库时的迁移步骤和第一轮任务建议。
API 合约：前后端接口形状、错误格式、鉴权约定。
路由与页面结构：页面路由、页面职责、组件归属。
当前实现状态：可覆盖的当前快照，记录仓库现实状态、可运行命令和下一步可做任务。
Agent 上下文清单 / agent-context.json / Schema：按任务类型选择文档、用提交 / 文件 SHA 避免重复读取。
Gitea MCP 接入：可选的共享文档、Issue / PR 协调、安全配置和断连降级规则。
Gitea 多 Agent 协作：可选的任务映射、原子 claim、写路径防撞和 PR 状态协议。
收尾检查清单：会话结束前逐项检查，保证下一轮无需人工修复即可继续。
方法对照表：失败模式 → 首要修复 → 工件；出问题先查这里对症补工件。
评审评分表：单次会话输出的结构化评审（6 维 0-2 分 + 校准说明）。
质量文档：代码库长期健康度追踪，区别于单次输出评审。
../init.sh / ../init.ps1：标准启动与验证入口脚本（根目录），统一安装、验证和启动命令。按操作系统二选一：WSL / Git Bash / macOS / Linux 用 init.sh，Windows 原生 PowerShell 用 init.ps1；换技术栈只改脚本顶部三个命令变量；未替换前脚本会主动失败，避免把示例命令误当真实项目命令。
../scripts/validate_agent_context.py：零第三方依赖校验上下文清单、Schema 和仓库相对路径。
../scripts/setup_gitea_labels.py：默认只读预览远端差异、显式写入的 Gitea 协作标签初始化脚本。
Gitea Issue 模板 / PR 模板：任务映射、写路径和验证证据字段。

任务 / 进度 / 当前状态

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 进入。

README.md Unescape Escape

项目文档导航

一句话定位

文档导航

任务 / 进度 / 当前状态

维护原则

README.md