爻枢 Code

主题

项目文档机制 ​

它有一套「越用越厚」的项目档案：需求、设计、接口、测试——代码改到哪，文档跟到哪。您不用写一个字，但要会用它。

ai-docs/ 是什么 ​

每个编程项目里有一个 ai-docs/ 文件夹——项目的档案柜。打开新项目时自动建好，之后随开发自动长内容：

ai-docs/
├── 项目路径映射.md      ← 项目档案首页：技术栈、目录结构、路径拓扑
├── 需求/               ← 业务需求（做了什么、为什么做）
├── 前端设计/           ← 前端各模块的设计文档
├── 后端设计/           ← 接口契约与后端设计
├── 测试与缺陷/         ← 测试与 Bug 追踪
├── 工单总线/           ← 多角色协作的交接单
└── 临时引用/           ← 外部素材中转（用完即清）

文档谁在写、谁在维护 ​

它写、它维护——这就是「代码改了文档不会烂」的秘密：

时机文档发生什么
新功能开发需求落需求文档、方案落设计文档、接口落契约文档——先有图纸再施工
代码修改对应设计文档同步更新（它交付时会说「已同步文档」）
表结构 / 接口变更DDL 与契约文档跟着改

您不写文档，但您审文档——重要设计它会把方案拿给您拍板（见拍板与确认怎么配合），拍过板的才动工。

为什么您该在乎这套文档 ​

三个真实收益：

  1. 换个会话不断片——新会话不记得昨天聊了什么，但它会先读档案：需求口径、设计决策、踩过的坑都在，接得上（这就是它的「长期记忆」）
  2. 换个人不断层——同事接手时，读档案比读聊天记录快十倍；您离开一个月回来，照样接得上
  3. 改代码有依据——「当初为什么这么设计」有处可查，改起来不心虚

文档的三个日常用法 ​

text
「这个项目的需求文档里，订单模块都定了什么？」   → 查业务口径
「把用户模块的设计文档给我讲一遍」             → 快速了解某模块
「现在的实现和设计文档一致吗？检查一下」        → 对账（它逐项核对）

想看文档

文件树里 ai-docs/ 下点开即看——Markdown 实时预览，表格、图表齐全。

文档质量的兜底 ​

文档不是写了就完——它有一套自查机制（体积防线、断链检查、过时内容清理），文档越用越厚但不会越用越乱。您发现文档不对时直接说「这份文档过时了，对照代码更新」——它修文档而不是辩解。

与 FDE 产出的关系 ​

一个文件夹同时有 FDE 产出与代码是正常的：FDE 的东西（方案、合同）住 ai-fde/，工程的档案住 ai-docs/，互不干扰。签单后 FDE 的需求文档与原型就是工程侧的现成输入——ai-docs/需求/ 里会引用它们开工。

常见卡点 ​

现象怎么办
想找某个决定是当时为什么定的问它「当初××为什么这么设计」——它会引用设计文档的考量段回答
文档和代码对不上说「检查文档与代码一致性」——它对账并修正
文档太多不知从哪看首页（项目路径映射）→ 需求 → 对应模块设计——按这个顺序
不想要某个文档了可删——但设计文档是改代码的依据，删前问一句它是否还有引用
文档会不会泄露出去文档在您项目文件夹里，跟代码同安全级；入库提交时随代码一起管理

延伸阅读 ​