From 066f3c75e9255809f3bfeea655e0ffab78f2e83d Mon Sep 17 00:00:00 2001
From: QiuSW <ila2002@qq.com>
Date: Mon, 22 Jun 2026 21:44:11 +0800
Subject: [PATCH] Initialize harness coding docs

---
 AGENTS.md                |  47 +++++++++++++++
 CLAUDE.md                |  44 ++++++++++++++
 README.md                |  34 +++++++++++
 docs/00-ai-start-here.md | 119 +++++++++++++++++++++++++++++++++++++
 docs/01-vision.md        |  41 +++++++++++++
 docs/02-requirements.md  |  66 +++++++++++++++++++++
 docs/03-tech-stack.md    |  47 +++++++++++++++
 docs/04-architecture.md  | 124 +++++++++++++++++++++++++++++++++++++++
 docs/05-coding-rules.md  |  79 +++++++++++++++++++++++++
 docs/06-tasks.md         |  68 +++++++++++++++++++++
 docs/README.md           |  33 +++++++++++
 docs/api.md              |  87 +++++++++++++++++++++++++++
 docs/current-state.md    |  63 ++++++++++++++++++++
 docs/routes.md           |  48 +++++++++++++++
 14 files changed, 900 insertions(+)
 create mode 100644 AGENTS.md
 create mode 100644 CLAUDE.md
 create mode 100644 README.md
 create mode 100644 docs/00-ai-start-here.md
 create mode 100644 docs/01-vision.md
 create mode 100644 docs/02-requirements.md
 create mode 100644 docs/03-tech-stack.md
 create mode 100644 docs/04-architecture.md
 create mode 100644 docs/05-coding-rules.md
 create mode 100644 docs/06-tasks.md
 create mode 100644 docs/README.md
 create mode 100644 docs/api.md
 create mode 100644 docs/current-state.md
 create mode 100644 docs/routes.md

diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..1ebf2fc
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,47 @@
+# AGENTS.md
+
+> Codex / AI coding agent 的仓库级入口。进入本仓库后，先读本文，再进入 `docs/00-ai-start-here.md`。
+
+## 项目定位
+
+本仓库是 harness coding 文档样本库，用来沉淀一个新项目交给 AI coding agent 开发前应准备的文档集合。
+
+当前不是业务应用代码仓库，而是文档模板仓库。默认任务是维护、改进、补充这些模板，让它们更适合复制到新项目中使用。
+
+## 必读顺序
+
+每次开始工作前，按顺序读取：
+
+1. `README.md`：了解本仓库用途和文档集合。
+2. `docs/README.md`：了解文档导航。
+3. `docs/00-ai-start-here.md`：理解新项目中 agent 的入口流程。
+4. `docs/05-coding-rules.md`：理解模板中的编码纪律。
+5. 与当前任务相关的具体文档。
+
+如果用户要求修改某类模板，优先阅读对应文件，不要只凭文件名猜内容。
+
+## 工作规则
+
+- 保持这些文件是“可复制到新项目”的模板，不要写入只适用于当前机器的业务事实。
+- 可以引用 `D:\opc_project\lingo\docs` 作为参考来源，但不要把 lingo 的具体业务内容照搬进通用模板。
+- 文档中使用 `【占位符】` 表示新项目需要替换的内容。
+- 修改导航时，必须同步检查 `README.md` 和 `docs/README.md` 的链接。
+- 新增文档时，必须在根目录 `README.md` 和 `docs/README.md` 中登记。
+- 不要删除已有模板，除非用户明确要求。
+
+## 风格
+
+- 文档默认使用中文。
+- 标题、表格、任务状态、文件名保持简洁稳定。
+- 内容要面向 agent 执行，而不是泛泛讲原则。
+- 每条规则最好能落到“读取什么、修改什么、验证什么”。
+
+## 验证
+
+本仓库目前是纯文档仓库。修改后至少检查：
+
+```powershell
+Get-ChildItem -Recurse -File
+```
+
+如修改链接或文件名，使用 `rg` 搜索旧名称和新名称，确认引用一致。
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..1a6218a
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,44 @@
+# CLAUDE.md
+
+> Claude Code 的仓库级上下文。进入本仓库后，先读本文，再读 `AGENTS.md` 和 `docs/00-ai-start-here.md`。
+
+## 仓库用途
+
+这是 harness coding 文档样本库，目标是提供一套新项目启动前可复制的 AI coding 文档模板。
+
+这套模板参考了 `D:\opc_project\lingo\docs` 的真实项目文档结构，但本仓库产物应保持通用，不绑定 lingo 的业务、数据、技术栈或任务状态。
+
+## 关键事实
+
+- 根目录 `README.md` 是样本库总入口。
+- `docs/README.md` 是模板文档导航。
+- `docs/00-ai-start-here.md` 是新项目中 AI agent 的工作入口模板。
+- `docs/05-coding-rules.md` 是新项目中 AI agent 的硬约束模板。
+- `docs/06-tasks.md` 是任务看板模板，强调每轮只做一个任务。
+- `docs/current-state.md` 用来记录代码现实，防止文档计划和实际状态脱节。
+
+## Claude 工作方式
+
+处理本仓库任务时：
+
+1. 先确认用户是在要求修改模板本身，还是要求基于模板生成某个具体项目的文档。
+2. 如果是修改模板，保持通用占位符和可复制性。
+3. 如果是生成具体项目文档，允许替换占位符为该项目事实，但不要污染通用样本，除非用户明确要求覆盖模板。
+4. 修改文件前先读相关模板，保持同一套命名和结构。
+5. 修改后检查文档导航是否仍完整。
+
+## 不要做
+
+- 不要把真实密钥、token、账号、私有 URL 写入模板。
+- 不要把旧项目的具体事实写成新项目通用规则。
+- 不要把模板改成只适合某一种技术栈，除非用户明确要求。
+- 不要在没有用户要求时创建应用代码、依赖配置或构建脚本。
+
+## 常用检查命令
+
+```powershell
+Get-ChildItem -Recurse -File
+rg -n "AGENTS.md|CLAUDE.md|00-ai-start-here|05-coding-rules|06-tasks" .
+```
+
+如果 `rg` 不可用，使用 PowerShell `Select-String`。
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..455b171
--- /dev/null
+++ b/README.md
@@ -0,0 +1,34 @@
+# Harness Coding 文档样本库
+
+本仓库用于沉淀一个新项目交给 AI coding agent 开发前，建议准备的文档集合。
+
+这些文档参考了 `D:\opc_project\lingo\docs` 的实际项目文档结构，抽象为可复用模板：从项目入口、愿景、需求、技术栈、架构、编码规则，到任务看板、API、路由和当前状态。
+
+## 推荐文档集合
+
+| 文档 | 作用 |
+| --- | --- |
+| [`AGENTS.md`](AGENTS.md) | Codex / 通用 AI coding agent 的仓库级入口 |
+| [`CLAUDE.md`](CLAUDE.md) | Claude Code 的仓库级上下文入口 |
+| [`docs/README.md`](docs/README.md) | 文档导航，总览所有项目文档 |
+| [`docs/00-ai-start-here.md`](docs/00-ai-start-here.md) | AI coding agent 的入口、阅读顺序、任务领取规则 |
+| [`docs/01-vision.md`](docs/01-vision.md) | 项目为什么做、为谁做、什么不做 |
+| [`docs/02-requirements.md`](docs/02-requirements.md) | 产品需求、用户故事、验收标准 |
+| [`docs/03-tech-stack.md`](docs/03-tech-stack.md) | 技术选型和运行命令 |
+| [`docs/04-architecture.md`](docs/04-architecture.md) | 系统结构、职责边界、数据模型、开发顺序 |
+| [`docs/05-coding-rules.md`](docs/05-coding-rules.md) | AI 写代码前必须遵守的硬规则 |
+| [`docs/06-tasks.md`](docs/06-tasks.md) | 可逐步交付的任务看板 |
+| [`docs/api.md`](docs/api.md) | API 合约模板 |
+| [`docs/routes.md`](docs/routes.md) | 页面路由、组件归属、导航规则 |
+| [`docs/current-state.md`](docs/current-state.md) | 当前实现状态，防止计划和代码现实脱节 |
+
+## 使用方式
+
+1. 复制 `docs/` 到新项目。
+2. 从 `01-vision.md` 和 `02-requirements.md` 开始替换业务内容。
+3. 在 `03-tech-stack.md` 固定技术选型，不确定的选项标为待定。
+4. 在 `04-architecture.md` 写清事实来源、数据模型、系统边界。
+5. 在 `06-tasks.md` 拆出小任务，要求 AI 每轮只领取一个任务。
+6. 开始编码前，让 agent 先读 `00-ai-start-here.md`。
+
+核心原则：文档不是给人看的装饰，而是给 agent 执行时用的约束、事实来源和验收标准。
diff --git a/docs/00-ai-start-here.md b/docs/00-ai-start-here.md
new file mode 100644
index 0000000..c3d5c18
--- /dev/null
+++ b/docs/00-ai-start-here.md
@@ -0,0 +1,119 @@
+# AI 开发入口
+
+> 给 AI coding agent 的项目入口。这里负责导航和流程，硬性编码规则见 [`05-coding-rules.md`](05-coding-rules.md)。
+
+## 一句话定位
+
+【项目名】是【一句话说明项目目标、用户和 MVP 范围】。
+
+第一版 MVP 只做：【列出最小闭环功能】。
+
+## 必读顺序
+
+每次开始写代码前，按这个顺序建立上下文：
+
+1. [`01-vision.md`](01-vision.md)：为什么做、为谁做、什么不做。
+2. [`02-requirements.md`](02-requirements.md)：MVP 要什么、怎么算达成。
+3. [`03-tech-stack.md`](03-tech-stack.md)：既定技术选型。
+4. [`04-architecture.md`](04-architecture.md)：系统结构、职责划分、数据模型和关键难点。
+5. [`05-coding-rules.md`](05-coding-rules.md)：写代码前必须遵守的规则。
+6. [`06-tasks.md`](06-tasks.md)：领取本轮唯一任务。
+7. [`current-state.md`](current-state.md)：当前代码现实、可运行命令、下一步任务。
+
+如果仓库根目录有 `AGENTS.md`、`CLAUDE.md` 或其他 agent 规则文件，也必须先读。仓库级规则优先于项目局部建议。
+
+## 当前阶段
+
+当前项目处于：【例如：MVP 起步 / 原型验证 / 功能开发 / 上线前收尾】。
+
+优先路径：
+
+1. Phase 0：最小可运行地基。
+2. Phase 1：最高风险功能原型。
+3. Phase 2：核心用户流程。
+4. Phase 3：账号 / 数据持久化 / 同步。
+5. Phase 4：部署、离线、监控或上线准备。
+
+## 领取任务规则
+
+从 [`06-tasks.md`](06-tasks.md) 领取任务时：
+
+- 只领取第一个状态为 `TODO` 且依赖均为 `DONE` 的任务。
+- 开始前把该任务状态改为 `DOING`。
+- 本轮只完成这一个任务。
+- 验收通过后把状态改为 `DONE`。
+- 做完即停，汇报验证结果，等待下一步指令。
+
+如果代码实际状态和任务看板冲突，先说明冲突，不要擅自跳步或重排。
+
+## MVP 边界
+
+MVP 只做：
+
+- 【P0 功能 1】
+- 【P0 功能 2】
+- 【P0 功能 3】
+
+MVP 不做：
+
+- 【明确非目标 1】
+- 【明确非目标 2】
+- 【后续版本功能】
+
+## 事实来源
+
+项目事实只信：
+
+- 【业务数据源 / schema / seed 数据路径】
+- 【产品需求文档】
+- 【接口合约】
+- 【现有代码中的权威模块】
+
+不要把以下内容当事实来源：
+
+- 历史备份文件。
+- 旧导出文档。
+- 临时实验目录。
+- 未被任务或需求引用的草稿。
+
+## 常见任务该看哪里
+
+做页面 / UI：
+
+- 先看 `02-requirements.md` 的对应验收标准。
+- 再看 `routes.md` 的页面职责。
+- 最后看 `04-architecture.md` 的组件边界。
+
+做后端 API：
+
+- 先看 `api.md` 的接口合约。
+- 再看 `04-architecture.md` 的数据模型和鉴权边界。
+
+做数据模型：
+
+- 先看 `04-architecture.md` 的数据模型。
+- 如果 schema 变化，必须同步更新 `api.md`、`current-state.md` 和相关任务验收。
+
+做部署 / 运行：
+
+- 先看 `03-tech-stack.md` 的运行命令。
+- 再看 `current-state.md` 的当前真实命令。
+
+## 验证命令
+
+把本项目真实命令填在这里：
+
+```bash
+# 示例
+npm test
+npm run build
+go test ./...
+pytest
+```
+
+说明：
+
+- 改前端后跑：【命令】。
+- 改后端后跑：【命令】。
+- 改数据结构后跑：【命令】。
+- 如果命令当前不可运行，必须在回复里如实说明原因。
diff --git a/docs/01-vision.md b/docs/01-vision.md
new file mode 100644
index 0000000..8554f73
--- /dev/null
+++ b/docs/01-vision.md
@@ -0,0 +1,41 @@
+# 项目愿景
+
+## 一、核心目标
+
+【项目名】要解决：【一句话说明用户的真实问题】。
+
+> 让【目标用户】能够【完成核心任务】，并获得【明确价值】。
+
+它不是【容易混淆的产品类型】，而是一个为【核心场景】服务的工具。
+
+## 二、目标用户
+
+- 【用户类型 1】：【典型需求】
+- 【用户类型 2】：【典型需求】
+- 【用户类型 3】：【典型需求】
+
+## 三、产品原则
+
+遇到取舍时，以这些原则为准：
+
+- **核心流程优先**：先把用户最常做、最关键的流程做顺。
+- **真实数据优先**：不造假数据、不虚构字段、不用演示逻辑冒充产品逻辑。
+- **小步交付**：每一步都能运行、能验证、能回退。
+- **少即是稳**：MVP 不追求完整，只追求最小闭环可靠。
+- **可维护**：架构、命名、边界要让后续 agent 能继续接手。
+
+## 四、核心价值主张
+
+| 价值点 | 说明 |
+| --- | --- |
+| 【价值 1】 | 【用户得到什么】 |
+| 【价值 2】 | 【用户得到什么】 |
+| 【价值 3】 | 【用户得到什么】 |
+
+## 五、不做什么（非目标）
+
+- 不做【非目标 1】。
+- 不做【非目标 2】。
+- 不做【容易膨胀但不属于 MVP 的功能】。
+
+> MVP 的具体功能范围与验收标准，见 [需求](02-requirements.md)。
diff --git a/docs/02-requirements.md b/docs/02-requirements.md
new file mode 100644
index 0000000..18de423
--- /dev/null
+++ b/docs/02-requirements.md
@@ -0,0 +1,66 @@
+# 需求
+
+> 本文只描述**要什么**与**怎么算达成**，用产品 / 用户语言表达，**不涉及技术实现**。
+> 技术方案、数据结构、字段定义见 [架构设计](04-architecture.md)。
+
+## 一、业务现状
+
+| 项 | 状态 |
+| --- | --- |
+| 用户 | 【目标用户和当前痛点】 |
+| 数据 | 【已有 / 缺失 / 待清洗的数据】 |
+| 现有系统 | 【如有，说明当前状态】 |
+| 约束 | 【版权、合规、性能、设备、网络等限制】 |
+
+## 二、用户角色
+
+- **【角色 1】**：【能做什么】
+- **【角色 2】**：【能做什么】
+- **游客 / 未登录用户**：【是否允许访问，待定也要写明】
+
+## 三、功能清单
+
+### 第一版 MVP（最小闭环）
+
+| 功能 | 用户能做什么 | 优先级 |
+| --- | --- | --- |
+| 【功能 1】 | 【用户动作和结果】 | P0 |
+| 【功能 2】 | 【用户动作和结果】 | P0 |
+| 【功能 3】 | 【用户动作和结果】 | P0 |
+
+### 后续迭代
+
+| 功能 | 描述 | 阶段 |
+| --- | --- | --- |
+| 【功能】 | 【说明】 | V2 |
+| 【功能】 | 【说明】 | V3 |
+
+## 四、核心用户故事（MVP）
+
+1. 作为【角色】，我打开系统后能【第一步】。
+2. 我可以【关键动作】，并看到【结果】。
+3. 我可以【继续动作】，系统会【保存 / 同步 / 展示】。
+4. 当【异常场景】发生时，系统会【降级 / 提示 / 阻止错误】。
+
+## 五、验收标准（MVP）
+
+每条 P0 功能对应可验证的判据：
+
+- **【功能 1】**：【打开 / 点击 / 输入 / 保存 后，应看到什么结果】。
+- **【功能 2】**：【明确时间、状态、数据持久化或错误处理要求】。
+- **【功能 3】**：【跨刷新、跨设备、权限、边界情况等要求】。
+
+## 六、范围边界与决策
+
+| 问题 | 决策 |
+| --- | --- |
+| 第一版平台 | 【Web / 移动端 / 桌面 / CLI】 |
+| 是否需要账号 | 【是 / 否 / 待定】 |
+| 第一版范围 | 【最小闭环】 |
+| 暂不支持 | 【明确排除项】 |
+
+## 七、待确认 / 风险点
+
+- 【风险 1】：【为什么有风险，建议先如何验证】。
+- 【风险 2】：【数据、性能、授权、依赖、体验等风险】。
+- 【待确认问题】：【谁来决策，什么时候需要决策】。
diff --git a/docs/03-tech-stack.md b/docs/03-tech-stack.md
new file mode 100644
index 0000000..b07e5e7
--- /dev/null
+++ b/docs/03-tech-stack.md
@@ -0,0 +1,47 @@
+# 技术栈（Tech Stack）
+
+> “用什么”的统一速查表。选型与理由在此集中维护；“怎么把它们搭起来”见 [架构设计](04-architecture.md)。
+> 未定项必须标为待定，不要让 agent 在代码里自行决定。
+
+## 一、技术栈一览
+
+| 维度 | 选型 | 状态 | 理由 / 说明 |
+| --- | --- | --- | --- |
+| 前端框架 | 【例如 React / Vue / go-app / 原生】 | 【已定 / 待定】 | 【理由】 |
+| UI 样式方案 | 【例如 CSS / Tailwind / 组件库】 | 【已定 / 待定】 | 【理由】 |
+| 状态管理 | 【例如框架内置 / Zustand / Redux】 | 【已定 / 待定】 | 【理由】 |
+| 后端 | 【例如 Go net/http / FastAPI / NestJS】 | 【已定 / 待定】 | 【理由】 |
+| 数据库 | 【例如 SQLite / Postgres / MySQL】 | 【已定 / 待定】 | 【理由】 |
+| 鉴权方式 | 【例如 Session Cookie / JWT / 无账号】 | 【已定 / 待定】 | 【理由】 |
+| 部署方式 | 【例如单二进制 / Docker / Vercel】 | 【已定 / 待定】 | 【理由】 |
+| 测试 | 【例如 go test / pytest / vitest】 | 【已定 / 待定】 | 【理由】 |
+
+## 二、决策记录与演进
+
+- 【选型 1】：现在选择【方案】，因为【理由】。未来在【条件】出现时再评估【替代方案】。
+- 【选型 2】：当前不引入【工具 / 框架】，避免【复杂度】。
+
+## 三、构建与运行命令
+
+| 用途 | 命令 |
+| --- | --- |
+| 安装依赖 | `【命令】` |
+| 本地开发 | `【命令】` |
+| 构建 | `【命令】` |
+| 测试 | `【命令】` |
+| 格式化 / 静态检查 | `【命令】` |
+
+Windows PowerShell 如有差异，单独列出：
+
+```powershell
+# 示例
+npm install
+npm run dev
+npm test
+```
+
+## 四、依赖纪律
+
+- 新增第三方依赖前，先说明用途、替代方案和维护成本。
+- 不确定的技术选型先更新本文，再进入代码。
+- 不允许同一职责并存两套框架或两套状态管理方案。
diff --git a/docs/04-architecture.md b/docs/04-architecture.md
new file mode 100644
index 0000000..2be227f
--- /dev/null
+++ b/docs/04-architecture.md
@@ -0,0 +1,124 @@
+# 架构设计
+
+> 本文讲“怎么把技术栈搭起来”：系统结构、职责划分、数据模型、技术难点、开发顺序。
+> 具体用了哪些框架 / 库 / 数据库 / 部署方式，见 [技术栈](03-tech-stack.md)。
+
+## 一、系统结构
+
+```text
+用户
+  |
+  v
+前端 / 客户端
+  |
+  v
+后端 API
+  |
+  v
+数据库 / 文件 / 第三方服务
+```
+
+把真实组件替换到上图中，例如：
+
+- 前端：【框架、入口目录】
+- 后端：【框架、入口文件】
+- 数据库：【类型、迁移方式】
+- 外部服务：【支付、邮件、对象存储、AI 服务等】
+
+## 二、职责划分
+
+**前端 / 客户端**
+
+- 【页面与交互职责】
+- 【客户端状态】
+- 【本地缓存 / 离线 / 上传等职责】
+
+**后端**
+
+- 【鉴权】
+- 【业务 API】
+- 【数据校验】
+- 【异步任务 / 文件处理】
+
+**数据库 / 存储**
+
+- 【持久化哪些数据】
+- 【不持久化哪些数据】
+- 【哪些数据只读，哪些数据可变】
+
+## 三、数据模型
+
+### 3.1 静态 / 只读数据
+
+| 数据 | 来源 | 说明 |
+| --- | --- | --- |
+| 【数据名】 | 【路径 / 服务】 | 【字段和约束】 |
+
+关键事实：
+
+- 【字段事实 1】
+- 【字段事实 2】
+- 【路径映射 / schema 约束】
+
+### 3.2 用户 / 业务动态数据
+
+示例表结构：
+
+```sql
+CREATE TABLE users (
+  id INTEGER PRIMARY KEY,
+  email TEXT UNIQUE NOT NULL,
+  created_at TEXT NOT NULL
+);
+```
+
+需要说明：
+
+- 主键和唯一约束。
+- 重要索引。
+- 是否软删除。
+- 哪些字段由服务端生成。
+- 哪些字段是前向兼容预留，MVP 是否启用逻辑。
+
+## 四、关键技术难点
+
+| 难点 | 说明 | 应对 |
+| --- | --- | --- |
+| 【难点 1】 | 【为什么难】 | 【先做 spike / 原型 / 测试】 |
+| 【难点 2】 | 【为什么难】 | 【降级方案】 |
+
+高风险功能应先做最小原型，不要等整个系统搭完才验证。
+
+## 五、推荐开发顺序
+
+1. 最小可运行地基。
+2. 最高风险功能原型。
+3. 核心用户流程。
+4. 数据持久化和账号体系。
+5. 完整验收、部署和边界处理。
+
+## 六、项目结构建议
+
+```text
+project/
+├── docs/
+├── src/ 或 app/
+├── server/ 或 api/
+├── tests/
+├── scripts/
+└── README.md
+```
+
+按实际技术栈替换：
+
+- `src/`：【前端 / 客户端代码】
+- `server/`：【后端代码】
+- `scripts/`：【数据校验、迁移、构建辅助脚本】
+- `tests/`：【测试目录】
+
+## 七、架构纪律
+
+- 业务事实和 schema 变化必须同步更新本文。
+- 不在代码里发明文档没有的接口、字段和状态。
+- 不把静态内容、用户数据、缓存数据混在一个模型里。
+- 高风险模块先单独验证，再接入完整页面或流程。
diff --git a/docs/05-coding-rules.md b/docs/05-coding-rules.md
new file mode 100644
index 0000000..7f4fc56
--- /dev/null
+++ b/docs/05-coding-rules.md
@@ -0,0 +1,79 @@
+# 编码规则（Coding Rules）
+
+> 每次写代码前先读完本文件。这是让 AI 不跑偏、代码质量稳定的硬约束。
+> 与技术细节冲突时，以 [技术栈](03-tech-stack.md) / [架构设计](04-architecture.md) 的事实为准；与“该不该做”冲突时，以 [需求](02-requirements.md) 为准。
+
+## 0. 黄金法则
+
+1. **不臆造**：数据字段、文件、接口、依赖，不确定就查证或询问。
+2. **守范围**：只做当前任务要求的事，不顺手加后续功能。
+3. **照架构**：使用既定技术栈和模块边界，不擅自引入新框架。
+4. **小步改**：一次只解决一个问题，不夹带无关重构。
+5. **可验证**：改完必须能构建、能测试、对得上验收标准。
+
+## 1. 动手前
+
+- 按链路确认：`vision` -> `requirements` -> `tech-stack` -> `architecture` -> `tasks`。
+- 找到本任务对应的验收标准，写之前就知道“怎么算做对”。
+- 先找现有函数、组件、工具和测试，复用优先。
+- 如果需求含糊，或改动会偏离原则 / 架构，先问。
+
+## 2. 事实来源纪律
+
+- 只相信文档指定的权威数据源、schema、API 合约和当前代码。
+- 不从备份、草稿、旧导出文件里推断当前事实。
+- 不虚构字段、接口、状态码、配置项。
+- 数据结构变化必须同步更新 `04-architecture.md`、`api.md` 和相关任务。
+
+## 3. 范围纪律
+
+- MVP 只做 `02-requirements.md` 中列为 P0 的功能。
+- V2 / V3 功能只记录，不实现。
+- 需求明确排除的非目标不得实现。
+- 不为“将来可能用到”提前抽象。
+
+## 4. 架构纪律
+
+- 技术栈以 `03-tech-stack.md` 为准。
+- 新增依赖前先说明理由；未经确认不要引入重量级依赖。
+- 模块职责以 `04-architecture.md` 为准，不跨层偷写逻辑。
+- API 形状以 `api.md` 为准，页面路由以 `routes.md` 为准。
+
+## 5. 代码规范
+
+- 标识符使用英文。
+- UI 文案、注释、文档语言按项目现状保持一致。
+- 错误必须处理，不吞错。
+- 注释解释“为什么”，不复述“做了什么”。
+- 遵守项目已有格式化工具，不手工制造风格分裂。
+
+## 6. 测试与验证
+
+完成前至少检查：
+
+- [ ] 构建通过。
+- [ ] 相关测试通过。
+- [ ] 对得上需求验收标准。
+- [ ] 没有夹带无关改动。
+- [ ] 涉及文档事实变化时，文档已同步。
+- [ ] 回复里如实说明跑了什么命令、结果如何。
+
+把真实命令填在这里：
+
+```bash
+# 示例
+npm test
+npm run build
+go test ./...
+```
+
+## 7. 绝不
+
+- 绝不把密钥、token、密码写进代码或文档样例的真实值里。
+- 绝不为了让测试通过而删除断言、降低验收标准。
+- 绝不擅自删除用户已有文件或重置工作区。
+- 绝不在没说明的情况下改公共接口、迁移数据结构或升级依赖。
+
+## 8. 拿不准就问
+
+问题要具体，说明你卡在哪里、有哪些选项、倾向哪个选项以及原因。
diff --git a/docs/06-tasks.md b/docs/06-tasks.md
new file mode 100644
index 0000000..978d9dd
--- /dev/null
+++ b/docs/06-tasks.md
@@ -0,0 +1,68 @@
+# 任务看板（Tasks）
+
+> 把 MVP 拆成小步、可独立交付的任务，让 AI 一步一步开发，避免一次生成整个项目。
+
+## 使用规则
+
+1. **一次只做一个任务**：每轮只领取一个状态为 `TODO`、且依赖均已 `DONE` 的任务，取最靠前的那个。
+2. **做完即停**：完成该任务、自测通过、把状态改成 `DONE` 后，停下来汇报。
+3. **不跳步**：依赖未完成的任务不能开工。
+4. **完成定义**：以 [编码规则](05-coding-rules.md) 的验证清单为准。
+5. **动手前**先读 `00-ai-start-here.md`、`05-coding-rules.md` 和 `current-state.md`。
+
+## 状态图例
+
+`TODO` 待开始 · `DOING` 进行中（同一时间最多 1 个）· `DONE` 已完成并验收 · `BLOCKED` 受阻（注明原因）
+
+---
+
+## Phase 0 · 地基
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-001 | 初始化项目骨架 | - | 依赖安装成功；本地能启动；首页 / 入口可访问 | TODO |
+| T-002 | 建立基础目录和配置 | T-001 | 目录结构符合 `04-architecture.md`；配置不含密钥 | TODO |
+| T-003 | 加入最小测试 / 构建检查 | T-001 | 测试命令和构建命令可运行 | TODO |
+
+## Phase 1 · 最高风险验证
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-101 | 验证最高风险功能原型 | T-001 | 用最小输入跑通核心难点，结论写入文档 | TODO |
+| T-102 | 把原型接入正式结构 | T-101 | 代码进入约定模块，测试覆盖关键路径 | TODO |
+
+## Phase 2 · 核心用户流程
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-201 | 实现核心页面 / 入口 | T-102 | 用户能进入主流程第一步 | TODO |
+| T-202 | 实现核心动作 | T-201 | 用户能完成 MVP 最关键动作 | TODO |
+| T-203 | 实现结果展示 / 状态反馈 | T-202 | 用户能看到保存、提交或处理结果 | TODO |
+
+## Phase 3 · 数据与账号
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-301 | 建立数据模型 / 迁移 | T-202 | 表结构符合 `04-architecture.md` | TODO |
+| T-302 | 实现鉴权 / 权限边界 | T-301 | 未授权访问被拒绝；授权后可访问 | TODO |
+| T-303 | 实现数据持久化 | T-302 | 刷新 / 重进后数据仍在 | TODO |
+
+## Phase 4 · 收尾与发布
+
+| ID | 任务 | 依赖 | 验收要点 | 状态 |
+| --- | --- | --- | --- | --- |
+| T-401 | 完整验收 MVP | T-303 | `02-requirements.md` 的 P0 验收全部通过 | TODO |
+| T-402 | 部署 / 打包 / 运行文档 | T-401 | 新环境可按文档运行 | TODO |
+
+## 里程碑
+
+- M1：最小可运行地基完成。
+- M2：最高风险功能已验证。
+- M3：MVP 核心闭环完成。
+- M4：可交付 / 可部署。
+
+## 待办池（Backlog）
+
+- 【V2 功能 1】
+- 【V2 功能 2】
+- 【优化项】
diff --git a/docs/README.md b/docs/README.md
new file mode 100644
index 0000000..5c039d6
--- /dev/null
+++ b/docs/README.md
@@ -0,0 +1,33 @@
+# 项目文档导航
+
+> 复制到新项目后，先替换本文中的项目名称和一句话定位，再逐个补齐后续文档。
+
+## 一句话定位
+
+【项目名】是一个【目标用户】使用的【产品类型 / 系统类型】，用于解决【核心问题】，第一版先完成【MVP 闭环】。
+
+示例：
+
+> 这是一个面向小团队的工单协作系统，第一版先跑通「提交工单 -> 分派 -> 处理 -> 关闭」闭环。
+
+## 文档导航
+
+- [`../AGENTS.md`](../AGENTS.md)：Codex / 通用 AI coding agent 的仓库级入口。
+- [`../CLAUDE.md`](../CLAUDE.md)：Claude Code 的仓库级上下文入口。
+- [AI 开发入口](00-ai-start-here.md)：agent 每次开始工作的入口、阅读顺序和任务领取规则。
+- [项目愿景](01-vision.md)：为什么做、为谁做、产品原则、非目标。
+- [需求](02-requirements.md)：要什么、用户故事、验收标准，不写技术实现。
+- [技术栈](03-tech-stack.md)：确定使用哪些框架、库、数据库、部署方式。
+- [架构设计](04-architecture.md)：系统结构、模块职责、数据模型、关键风险和开发顺序。
+- [编码规则](05-coding-rules.md)：AI 写代码前必须遵守的硬约束。
+- [任务看板](06-tasks.md)：按依赖拆分的小任务，agent 每轮只做一个。
+- [API 合约](api.md)：前后端接口形状、错误格式、鉴权约定。
+- [路由与页面结构](routes.md)：页面路由、页面职责、组件归属。
+- [当前实现状态](current-state.md)：仓库现实状态、已完成任务、下一步可做任务。
+
+## 维护原则
+
+- 需求变化先改文档，再改代码。
+- 代码现实变化后同步 `current-state.md` 和 `06-tasks.md`。
+- API、数据模型、路由、技术栈一旦在文档中定稿，代码不得另起一套。
+- agent 开始新任务前，必须从 `00-ai-start-here.md` 进入。
diff --git a/docs/api.md b/docs/api.md
new file mode 100644
index 0000000..7a8467d
--- /dev/null
+++ b/docs/api.md
@@ -0,0 +1,87 @@
+# API 合约
+
+> 本文定义后端 API 的目标形状。实现前可细化，但不要在代码里另起一套不兼容接口。
+
+如果项目没有后端 API，可改成本地模块接口、CLI 参数或事件合约。
+
+## 通用约定
+
+- 传输：【JSON over HTTPS / GraphQL / gRPC / 本地函数调用】。
+- 鉴权：【Session Cookie / Bearer Token / 无】。
+- 请求体和响应体编码：【UTF-8 JSON】。
+- 时间格式：【ISO 8601 / Unix timestamp】。
+- 未登录访问需要权限的接口时返回：【401 / 403】。
+
+通用错误响应：
+
+```json
+{
+  "error": {
+    "code": "bad_request",
+    "message": "请求参数不正确"
+  }
+}
+```
+
+## 账号
+
+### `POST /api/auth/login`
+
+请求：
+
+```json
+{
+  "email": "user@example.com",
+  "password": "password"
+}
+```
+
+成功响应：
+
+```json
+{
+  "user": {
+    "id": 1,
+    "email": "user@example.com"
+  }
+}
+```
+
+## 核心资源
+
+把项目的核心资源按 REST 或其他风格写清楚。
+
+### `GET /api/items`
+
+成功响应：
+
+```json
+{
+  "items": [
+    {
+      "id": 1,
+      "name": "示例"
+    }
+  ]
+}
+```
+
+### `POST /api/items`
+
+请求：
+
+```json
+{
+  "name": "示例"
+}
+```
+
+成功响应返回新增资源。
+
+## 待实现时确认
+
+- 参数校验规则。
+- 分页、排序、筛选方式。
+- 重复提交是否幂等。
+- 错误码枚举。
+- 鉴权过期时间和刷新策略。
diff --git a/docs/current-state.md b/docs/current-state.md
new file mode 100644
index 0000000..85d8afa
--- /dev/null
+++ b/docs/current-state.md
@@ -0,0 +1,63 @@
+# 当前实现状态
+
+> 本文记录代码与任务看板的现实状态，帮助 AI coding agent 避免只看计划而忽略仓库现状。
+
+## 当前快照
+
+- 日期：【YYYY-MM-DD】
+- 阶段：【MVP 起步 / 原型验证 / 功能开发 / 上线前】
+- 技术栈：【简述当前已落地的技术栈】
+- 生产代码：【入口文件和关键目录】
+- 测试：【已有测试与命令】
+- 数据：【已有数据源或 seed 文件】
+
+## 当前目录要点
+
+| 路径 | 状态 | 说明 |
+| --- | --- | --- |
+| `docs/` | 已有 | 项目规范化文档 |
+| `src/` | 【已有 / 待建】 | 前端或核心代码 |
+| `server/` | 【已有 / 待建】 | 后端代码 |
+| `tests/` | 【已有 / 待建】 | 测试 |
+| `scripts/` | 【已有 / 待建】 | 辅助脚本 |
+
+## 任务看板状态
+
+以 [`06-tasks.md`](06-tasks.md) 为准。
+
+- 已完成：【列出 DONE 任务】。
+- 正在进行：【如有，列出 DOING 任务】。
+- 下一个可领取任务：【第一个 TODO 且依赖均 DONE 的任务】。
+
+## 当前可运行内容
+
+```bash
+# 本地开发
+【命令】
+
+# 测试
+【命令】
+
+# 构建
+【命令】
+```
+
+## 开始编码前检查
+
+开始任意任务前：
+
+1. 读仓库级 agent 规则文件（如有）。
+2. 读 `docs/00-ai-start-here.md`。
+3. 读 `docs/05-coding-rules.md`。
+4. 在 `docs/06-tasks.md` 取第一个 `TODO` 且依赖均 `DONE` 的任务。
+5. 将该任务状态改为 `DOING`。
+
+## 维护规则
+
+当实际代码状态发生变化时，同步更新本文件：
+
+- 新增或移动入口文件。
+- 初始化框架或模块。
+- 任务从 `TODO` 进入 `DOING` 或 `DONE`。
+- 新增可运行命令。
+- 发现文档和代码现实不一致。
diff --git a/docs/routes.md b/docs/routes.md
new file mode 100644
index 0000000..f5fd65b
--- /dev/null
+++ b/docs/routes.md
@@ -0,0 +1,48 @@
+# 路由与页面结构
+
+> 本文约定前端页面路由、页面职责和组件归属。没有前端页面的项目，可改成 CLI 命令、后台任务或模块入口说明。
+
+## 页面路由
+
+| 路由 | 页面 | MVP 说明 |
+| --- | --- | --- |
+| `/` | 首页 / 列表页 | 展示主入口 |
+| `/items/{id}` | 详情页 | 展示单个资源详情 |
+| `/login` | 登录页 | 登录入口 |
+| `/settings` | 设置页 | 用户或系统配置 |
+
+## 页面职责
+
+### 首页 / 列表页
+
+- 展示【核心资源列表】。
+- 支持【筛选 / 搜索 / 新建】。
+- 展示【状态 / 进度 / 空状态】。
+
+### 详情页
+
+- 根据 URL 参数定位资源。
+- 展示核心信息。
+- 支持 MVP 范围内的关键操作。
+- 异常时展示明确错误或降级状态。
+
+### 登录页
+
+- 通过账号 API 建立会话。
+- 登录成功后返回原目标页或首页。
+
+## 组件建议
+
+| 组件 | 归属 | 说明 |
+| --- | --- | --- |
+| `AppShell` | 全局 | 页面框架、导航、登录态入口 |
+| `ItemList` | 首页 | 渲染资源列表 |
+| `ItemDetail` | 详情页 | 渲染资源详情 |
+| `AuthForm` | 登录页 | 登录 / 注册表单 |
+
+## 导航规则
+
+- 首页进入详情页：点击资源项。
+- 详情页返回首页：保留返回入口。
+- 未登录访问需要账号的页面时，引导登录。
+- 权限不足时显示明确错误，不静默失败。