docs/ 用于存放项目文档。目标只有三个：容易找到、容易理解、内容可信。
统一按“业务域 + 文档类型”组织：
docs/<domain>/<type>/
| 目录 | 前缀 | 内容 |
|---|---|---|
specs |
S |
需求、技术方案、协议和测试计划 |
apis |
A |
接口说明和联调指南 |
reports |
R |
评审、分析、复盘和测试报告 |
designs |
D |
流程图、模型图和设计源文件 |
logs |
L |
脱敏后的问题日志和原始数据 |
示例：
docs/vcc/specs/
docs/referral/apis/
docs/platform/reports/
除 docs/README.md 外，不在 docs/ 根目录直接堆放文档。
统一格式：
<prefix><YYYYMMDD>_<domain>_<topic>[_rNN].<ext>
YYYYMMDD使用文档首次创建日期。domain必须与所属业务域目录一致。topic使用小写英文和下划线。rNN是可选修订号，仅在需要保留多个正式版本时使用。- 本地草稿在文件名前加
_。
示例：
S20260717_vcc_card_creation.md
A20260717_referral_dashboard.md
R20260717_platform_design_review_r02.md
_S20260717_vcc_card_creation.md
Markdown 文档在一级标题后统一写：
> 状态：草稿 | 待确认 | 待实现 | 实现中 | 已完成 | 已废弃
> 最后更新：YYYY-MM-DD
> 适用范围：版本、模块或环境
> 关联文档：相对链接；没有则写“无”文件名日期不随修改变化；最后更新 必须随内容更新。
废弃文档不要直接删除，应标记为 已废弃 并链接到替代文档。
- 结论前置：开头直接说明目标、核心方案或最终结论。
- 范围明确：写清本次做什么、不做什么。
- 说明原因：关键决策不仅写“怎么做”，还要写“为什么这样做”。
- 区分现状与目标：尚未实现的接口、命令和行为必须明确标注为目标设计。
- 覆盖异常路径：除了正常流程，还要说明失败、重试、幂等和边界情况。
- 结论可验证：附测试命令、请求样例、验收步骤或其他验证依据。
- 风险不藏着：已知限制、待确认项和后续工作集中列出。
背景与目标
→ 范围
→ 核心方案与关键决策
→ 流程、模型或接口
→ 验证方式
→ 风险与后续
不适用的章节可以省略，不要为了套模板硬凑内容。
| 类型 | 必须说清的内容 |
|---|---|
| 需求/技术方案 | 背景、目标、范围、关键决策、业务流程、数据或接口、验证、风险 |
| 接口文档 | 接口用途、认证方式、调用顺序、请求响应样例、业务规则、错误处理 |
| 实施计划 | 关联方案、任务顺序、涉及文件、输入输出、验证命令和完成标准 |
| 评审/执行报告 | 结论、范围、发现或完成项、验证证据、未完成项、风险和下一步 |
| 设计图 | 图例、起点、终点、关键分支和异常路径；优先保留可编辑源文件 |
| 日志 | 时间、环境、触发步骤、最小必要日志和关联问题；必须脱敏 |
- 一篇文档只使用一个一级标题，主要章节使用二级标题。
- 同一篇文档的编号风格保持一致。
- 对照和字段映射使用表格；流程和状态变化使用 Mermaid；操作步骤使用编号列表。
- 代码块标明语言，例如
json、http、bash、kotlin、mermaid。 - 路径、命令、类名、接口和字段名使用反引号。
- 同一个概念只使用一种叫法，缩写首次出现时解释。
- 示例保持最小但完整，不粘贴与主题无关的大段代码或响应。
- 内部文档使用相对链接；外部资料优先引用官方来源并注明核对日期。
- 禁止写入密钥、Token、Cookie、个人信息和未脱敏生产数据。
Agent 本地草稿建议加入 .gitignore：
docs/**/specs/_S*
docs/**/apis/_A*
docs/**/reports/_R*外部工具生成的文件保留原目录和原文件名，不手动移动。在业务域目录创建相对软链接，软链接名称遵守本规范。
- 目录、类型前缀和文件名一致。
- 文档头完整，状态和更新时间准确。
- 开头已经说清目标、方案或结论。
- 范围、关键决策、异常路径、验证方式和风险清楚。
- 相对链接、文件路径、示例和命令有效。
- 没有敏感信息和未脱敏数据。