# demo-app Agent Rules

## Goal

先把当前交付目标、长期稳定真相、验证方式和变更工作区写清楚，再开始编码，减少返工和误解。

## Working Order

1. `docs/workflow/00-intake/README.md`
2. `docs/workflow/01-requirements/README.md`
3. `docs/workflow/02-design/README.md`
4. `docs/knowledge/context/README.md`
5. `docs/knowledge/structure/README.md`
6. `docs/knowledge/behavior/README.md`
7. `docs/knowledge/reference/README.md`
8. `docs/workflow/03-implementation/README.md`
9. `docs/workflow/04-verification/README.md`
10. `docs/workflow/05-tasks/README.md`
11. `docs/issues/README.md`
12. `docs/changes/active/<change-key>/`
13. `docs/releases/README.md`
14. `docs/archive/README.md`
15. `docs/adr/README.md`
16. `docs/rules/README.md`
17. 实现代码
18. 回写文档、测试、变更记录和 README

## Workflow Phases

本项目的文档流程借鉴 Spec Kit 的阶段化节奏，但长期文档源仍是 `docs/`：

| Phase | 本项目落点 | 完成标准 |
|---|---|---|
| specify | `00-intake`, `01-requirements` | 目标、边界、FR/NFR/AC 清楚 |
| clarify | 待确认区、必要时 `docs/issues/` | 关键分歧已问用户或明确阻塞 |
| plan | `02-design`, `03-implementation`, `04-verification`, `docs/knowledge/` | 方案、顺序、验证、长期真相一致 |
| tasks | `05-tasks`, `docs/changes/active/<change-key>/tasks.md` | 任务可执行、可验证、可追踪 |
| analyze | tasks 之后、实现之前 | 没有孤立 ID、冲突文档或阻塞性 `[待确认]` |
| implement | 代码、测试、脚本、迁移 | 只执行能回链到 `FR -> DES -> TEST -> T` 的工作 |
| converge | 实现之后 | workflow、knowledge、changes、records、README、AGENTS 已回写 |

## Document Boundaries

| File | Focus | Do not put here |
|---|---|---|
| `docs/workflow/00-intake/README.md` | 背景、用户、目标、非目标、约束 | 具体技术方案 |
| `docs/workflow/01-requirements/README.md` | what / why / success | 框架、库、表名、接口实现 |
| `docs/workflow/02-design/README.md` | how / architecture / current-stage decisions | 执行顺序和碎任务 |
| `docs/knowledge/context/README.md` | 术语、角色、核心实体、长期业务边界 | 本轮临时任务 |
| `docs/knowledge/structure/README.md` | 模块边界、系统结构、集成关系 | 具体交付排期 |
| `docs/knowledge/behavior/README.md` | 关键流程、状态流转、业务规则 | 低层实现细节 |
| `docs/knowledge/reference/README.md` | 样例、协议、schema、素材和固定参考 | 临时讨论记录 |
| `docs/workflow/03-implementation/README.md` | 里程碑、依赖、交付顺序 | 细碎的底层实现细节 |
| `docs/workflow/04-verification/README.md` | 如何验证需求落地 | 只有“后面补测试”这种空话 |
| `docs/workflow/05-tasks/README.md` | 可执行动作 | 抽象愿景和泛泛而谈 |
| `docs/changes/active/<change-key>/` | 单次变更的工作区和影响分析 | 项目长期稳定真相 |
| `docs/rules/` | 项目级规范与完成定义 | 具体业务需求细节 |

## Delivery Rules

- 存在阻塞性的 `[待确认]` 时，不要开始大规模实现。
- 对需求边界、架构方向、技术栈、数据模型或覆盖策略存在关键疑点时，必须先向用户确认，不能自行定案。
- 新功能必须同步更新 workflow、knowledge、verification 和 tasks 中受影响的部分。
- 新接口、数据结构、配置项变化，必须同时更新设计文档、知识层文档和测试。
- 修 bug 必须补回归测试，并记录进当前变更工作区。
- 新需求、bugfix、重构或流程变化，应同步更新 `docs/changes/active/` 或其归档位置。
- 每次提交必须遵循 `docs/rules/commit-rules.md`，使用 `<type>: <简短标题>` 标题，并在正文写清摘要、关联、修改范围、影响范围、测试状态和详细变更。
- 每次提交只能关联一个主要改动点；提交前必须确认对应 Issue、change workspace、需求 / 设计 / 验证文档已经存在或已同步。
- 记录型文档必须遵循 `docs/rules/document-archive-rules.md`，使用 `TYPE-YYYYMMDD-NNN` 编号，并按年份和月份归档。
- 代码注释必须说明关键逻辑是什么、为什么存在，以及它如何连接业务流程；不要写只重复代码语法的空注释。
- 版本发布或对外交付变化，应同步更新 `docs/releases/`。
- 未解决问题、风险和技术债，应同步更新 `docs/issues/`。
- 被替代或废弃的文档，应同步归档到 `docs/archive/`。
- 目录结构变化必须更新 `README.md`、`spec-init.topology.yml` 和 `docs/rules/document-routing-rules.md`。
- 关键技术权衡写入 `docs/adr/`。
- 每个任务都应该关联 `FR-*`、`DES-*`、`TEST-*` ID。
- 不确定的信息要显式标成 `[待确认]`，不要编造。
- 开始编码前，至少保证一条完整追踪链已经存在：`FR -> DES -> TEST -> T`
- 开始实现前必须完成 analyze 检查：需求、设计、验证、任务、change workspace 不得互相冲突。
- 完成实现后必须完成 converge 检查：代码真实行为、测试结果、当前文档和历史记录重新一致。
- `docs/changes/active/<change-key>/` 不能存放已完成变更；完成后必须移动到 `docs/changes/completed/`（如启用年月归档，则为 `docs/changes/completed/YYYY/MM/<change-key>/`）。
- 如果暂时不能移动到 `completed/`，不得把状态写成“已完成”，必须保持“待收敛”或“阻塞”并写清剩余条件。
- 具体编码、测试和文档同步规范，优先遵循 `docs/rules/` 下的规则文件。

## Project Commands

根据实际技术栈补充：

- Install: `[命令]`
- Dev: `[命令]`
- Test: `[命令]`
- Build: `[命令]`
- Lint: `[命令]`

## Definition of Done

- 需求、设计、验证、任务之间存在可追踪关系。
- 长期稳定事实已沉淀到 `docs/knowledge/`。
- 当前 change 已记录在 `docs/changes/active/`、`completed/` 或 `legacy/` 中的正确位置。
- 已完成 change 不再停留在 `docs/changes/active/`。
- 代码与文档保持一致。
- 高优先级需求有自动化验证。
- 实现前的一致性分析没有阻塞项。
- 实现后的收敛回写已完成。
- README 能帮助新成员快速理解项目结构。
- 已知风险和取舍已记录到文档或 ADR。
- `docs/rules/definition-of-done.md` 中的检查项通过。