Project stable

project-stable — 项目五文档基建

为项目准备稳定的根级上下文文档，让任意代码助手进入项目即拥有一致的认知基础。适用于全新项目搭建与旧项目接入 Vibe Coding 两种场合。

管辖范围（硬约束）

• 仅管理仓库根目录与 templates/ 同名一一对应的五份文档：AGENTS.md、PRODUCT.md、DESIGN.md、TODO.md、PROMPT.md。
• 其余任何文档（README.md、CLAUDE.md、docs/ 等）不属于本技能：不创建、不修改、不迁移，仅允许作为「解读项目」时的只读信息来源。

文档定位

文档	定位	解读项目时的主要来源
AGENTS.md	默认上下文，最简单清晰的项目指引	package.json、构建/lint 配置、源码目录树、README
PRODUCT.md	产品指示：模块/关联/顺序/引用、增删改查关联、关系图	路由与菜单配置、views/modules 目录、api/types、需求文档
DESIGN.md	产品设计：设计令牌 / UX / UI 基准	设计稿、demo HTML、主题样式与令牌文件
TODO.md	待办：场景→功能→点 目录树 + todo 状态	需求输入、issue、源码 TODO 注释、git log
PROMPT.md	常用提示词：BDD 场景 + 可执行提示词	团队工作流；通用条目开箱即用

模板机制

templates/<名>.md = 公共结构与公共内容（跨项目通用，原样保留） + <!-- 生成提示：... --> 挖空点 + {{占位符}}。

整套机制是完形填空：初始化/更新 = 填空（按项目事实填每个挖空点），同步 = 挖空（把项目文档长出的结构剜去项目特性、还原成挖空点写回模板）。

填空规则：

1. 公共内容原样带入；
2. 逐个挖空点按生成提示解读项目、产出内容，随后删除提示注释与未使用的占位；
3. 解读不到、无法验证的内容写「待补充：<缺什么、去哪找>」，不编造、不推定——尤其「禁止依赖方向」这类规则性结论，无代码依据时一律待补充；
4. 某节确无内容可填时，空表头等悬空结构一并删除，只留一行待补充说明。

操作一：初始化

Scenario: 为项目生成缺失的上下文文档
    Given 仓库根目录缺少一份或多份模板同名文档
    When 执行初始化
    Then 逐模板执行「读取模板 → 解读项目 → 生成项目文档」，在根目录产出缺失文档
    And 已存在的同名文档保持不动，在结果中提示可改走「更新」

对每份待生成文档独立执行：

1. 读取 templates/<名>.md；
2. 按「文档定位」表列出的来源解读项目——全新项目信息不足时，以用户的需求描述为解读对象；
3. 生成 <仓库根>/<名>.md；
4. 汇报：已生成清单、跳过清单、各文档中的「待补充」项。

操作二：更新

Scenario: 让既有文档跟上项目现状
    Given 仓库根目录已存在模板同名文档
    When 执行更新
    Then 逐文档执行「读取模板 → 解读项目 → 更新项目文档」
    And 以最小变更落笔：补缺失章节、修正过期事实；人工补充与项目特性内容一律保留

更新规则：

• 每份文档对照模板逐章节过一遍，每个章节给出四选一处置：补齐（模板有而文档缺 → 按生成提示填空）／修正（与项目现状冲突的事实：命令、目录、依赖、令牌值，核实后改）／保留（文档有而模板没有的章节——它是「同步」的输入）／无变化；
• 保持既有章节顺序与行文风格落笔；
• 完成判据：所处理文档的全部章节处置有交代，缺一份即未完成。

操作三：同步（反哺模板）

Scenario: 把项目文档中长出来的结构反哺回模板
    Given 项目文档演化出了模板中不存在的标题或内容结构
    When 执行同步
    Then 逐文档对比 <仓库根>/<名>.md 与 templates/<名>.md
    And 提取模板缺少的标题+内容结构，去除项目特性后（具体内容改写为生成提示）追加进模板
    And 模板既有内容不被项目特性值污染

同步规则：

• 只反哺「结构」（标题、表头、组织方式）与跨项目通用的规则；具体项目值一律还原成挖空点（改写为 <!-- 生成提示：... -->）；
• 某结构是否具备跨项目通用性拿不准时，列出候选问用户，不默默写入；
• 方向单一：项目文档 → 模板；同步过程永不反向删改项目文档。

执行纪律

• 动手前逐文档重新读取当前内容——项目文档可能已被并行会话或人工修改，会话早期读取的副本一律作废，凭旧副本断言「无变化」即错误；
• 一次调用只做一种操作；用户未点名操作时，按「有缺失文档 → 初始化缺失的，五份齐全 → 更新」判断，并说明所选操作；
• 用户只点名部分文档时，只处理点名的那几份；
• 文档语言跟随项目主语言（默认中文）；
• 收尾时逐文档汇报：做了什么操作、动了哪些章节、遗留哪些待补充项。