name: doc-driven-ai-workflow description: 用"文档驱动"方法论管理所有 AI 辅助开发项目（新项目搭建、功能迭代、存量改造/重构/迁移等），通过 AGENTS.md 规则约束、工作分析文档、分期实施计划、Memory.md 外置记忆四层文档解决 AI 编程的上下文丢失、改动失控、人机修改冲突三大痛点。所有 AI 编程项目都应调用本 skill 初始化文档体系，或当用户提到"文档驱动"、"实施计划"、"修改记录"、"Memory.md"、"AI 工作流"、"AGENTS.md"、"项目初始化"时使用。

文档驱动 AI 编程工作流

适用于所有 AI 辅助开发项目——无论是从零搭建新项目、功能迭代，还是存量项目的渐进式改造（UI 改版、样式升级、渐进重构、框架迁移等）。用四层文档让跨会话的 AI 工作可控、可追溯、可回退。

触发条件

本 skill 应在以下场景自动激活——不仅是用户显式提到关键词，还包括 AI 判断当前任务满足触发条件时主动调用：

关键词触发（用户明确提及）

• 文档体系相关：文档驱动、AGENTS.md、Memory.md、四层文档、铁律
• 工作计划相关：实施计划、工作分析、分期、修改记录、改造策略
• 工作流相关：AI 工作流、AI 编程规范、跨会话、项目初始化

场景触发（AI 应主动判断并调用）

触发后行为

1. 检查文档体系是否存在：扫描项目根目录的 AGENTS.md、Memory.md、*工作分析.md、*实施计划.md
2. 缺失则初始化：按阶段一创建缺失的文档
3. 已有则按流程执行：按阶段二的单次修改循环进行

核心思想

AI 会话没有长期记忆、改动容易扩散、会覆盖人工微调。对策：

AGENTS.md（约束） + 分析文档（上下文） + 实施计划（分期任务）
        ↓ 每次 AI 会话
   小范围修改 → 人工验收/手动微调 → Memory.md 追加记录
        ↓ 下次会话
   AI 读 Memory.md 恢复上下文，且不覆盖人工修改

工作流

阶段一：初始化（项目首次接入 AI 编程时，新项目/存量项目均适用）

初始化清单：
- [ ] 创建 AGENTS.md：写 3~5 条铁律，不要多
- [ ] 创建工作分析文档：明确前提约束、逐区域新旧对比、改动程度评级
- [ ] 创建实施计划文档：分期拆解，每期独立可运行/可验收/可回退
- [ ] 创建 Memory.md：开头放项目目录结构说明，正文留空待追加

各文档模板见 templates.md。

AGENTS.md 铁律的三个必备方向（按需增删措辞）：

1. 人机冲突规则 — AI 修改后若用户手动改过，下次修改必须保留用户的改动
2. 改动范围规则 — 明确本次任务只允许动什么（如"只改 template 和样式，不动业务逻辑"）
3. 留痕规则 — 每次修改完必须在 Memory.md 追加记录

实施计划的关键要求：

• 分期粒度以"单次会话能完成 + 出错可单文件 git 回退"为准
• 每期必须写明：目标文件（越少越好，第一期最好只动 1 个文件）、改动点、验收标准
• 显式写"不在本次范围内"清单，防止 AI 顺手扩散改动
• 预定义共享常量（如 CSS 变量表），保证多次会话产出风格一致

阶段二：单次修改循环（每次会话执行）

会话循环：
- [ ] 1. 读 AGENTS.md、Memory.md（最近几条记录 + 目录结构）恢复上下文
- [ ] 2. 对照实施计划，确认本次只做当前期内的一个小改动
- [ ] 3. 修改前检查目标代码是否与 Memory.md 记录不一致 → 不一致说明用户手改过，保留用户版本
- [ ] 4. 执行修改，严格遵守 AGENTS.md 改动范围规则
- [ ] 5. 在 Memory.md 顶部追加记录（格式见 templates.md）
- [ ] 6. 提示用户验收；验收通过才进入计划的下一步

Memory.md 记录必须包含：日期 + 主题、修改文件列表、修改内容逐条列出；如果是修 bug，还要写问题原因（这是下次会话避免重蹈覆辙的关键）。

阶段三：维护

• 出现"改坏→修复→回退"的反复时，每一步都记录到 Memory.md，不要合并成一条——失败路径本身就是有价值的记忆
• 项目结构变化时同步更新 Memory.md 开头的目录结构说明
• 一期全部完成后，在实施计划中标记该期状态，再开启下一期

反模式

• ❌ AGENTS.md 写成长篇规范 —— 铁律超过 5 条就会被稀释，细节放分析/计划文档
• ❌ 一次会话跨多期、动多个不相关文件 —— 破坏"单文件可回退"原则
• ❌ Memory.md 只写"优化了样式" —— 无法恢复上下文，必须写到文件级和改动点级
• ❌ 跳过分析和计划直接让 AI 动手 —— 多轮任务没有共享上下文，风格和方案必然漂移
• ❌ AI 发现代码与自己上次的产出不一致就"修正"回去 —— 那是用户的手动修改，必须保留

附加资源

• 四份文档的完整模板：templates.md

这是一套解决 AI 编程协作问题的实用方法论，通过四层文档让 AI 工作更可控。文档体系设计完善，触发条件明确，模板可直接使用。优点是思路清晰、步骤明确；不足是纯文字说明缺少案例演示，对新手来说可能需要一定时间消化理解。整体质量良好，适合有一定 AI 编程经验的用户使用。