songpl-AI 需求分析、规划与项目管理
核心原则
先规划，再编码。 plan.md 未与用户达成一致之前，禁止编写任何业务代码。
工作流总览
本 Skill 负责项目初始化：从零开始建立需求文档和项目管理体系。
用户提出需求
↓
判断流程级别（完整 / 轻量 / 跳过）
↓
┌─ 完整流程 ──────────────────────────────────────┐
│ ① 需求分析 → plan.md → 摘要+疑问 → 对齐确认 │
│ ② 生成 progress.md │
│ ③（可选）复杂项目 → architecture.md │
│ ④ 生成 FAQ.md │
│ ⑤（可选）不熟悉技术栈 → learning.md │
│ ⑥ 生成 AGENTS.md（持续开发规则，每次对话自动生效） │
│ ⑦ 分阶段编码 → 阶段检查点 → 循环 │
└─────────────────────────────────────────────────┘
初始化完成后，后续的持续开发（文档自动更新、阶段检查等）由项目根目录的 AGENTS.md 负责，它在每次对话中自动加载，无需依赖 Skill 触发。
流程分级
| 级别 | 触发条件 | 执行内容 |
|---|---|---|
| 完整流程 | 新项目搭建、大功能开发（5+文件）、架构重构、涉及技术选型 | 全部阶段 |
| 轻量流程 | 中等功能（3-5文件，目标明确） | 简化 plan.md（要点列表即可）→ 直接编码 |
| 跳过流程 | 单文件小修改、改文案、修样式、明确的 bug 修复 | 直接执行 |
判断不确定时，优先问用户。
阶段一：需求分析（plan.md）
分析步骤
- 澄清目标：用一句话概括核心目标
- 识别约束：技术栈、性能、兼容性、现有代码限制
- 边界确认：明确范围内和范围外的内容
- 歧义处理：发现模糊点优先向用户确认，不自行假设
按任务类型深入分析
| 任务类型 | 分析重点 |
|---|---|
| 新功能开发 | 涉及模块、数据流向、新增 vs 修改、对现有功能的影响 |
| 架构设计 | 职责边界、设计模式、扩展性、技术债务 |
| API 设计 | 接口契约、错误处理、版本兼容、鉴权模型 |
| 代码重构 | 现有问题、重构范围、渐进式路径、测试覆盖 |
| 复杂 Bug | 根因定位、影响范围、修复副作用、回归测试 |
方案设计
- 列出 2-3 个候选方案，标注优劣
- 给出推荐方案及理由
- 标注已知风险、不确定性和外部依赖
- 将方案拆解为分阶段实现步骤
验收标准（Acceptance Criteria）
plan.md 中的每个功能点都应附带验收标准，明确"做到什么程度算完成"：
### 1.1 用户登录
- [ ] 实现邮箱+密码登录
验收标准：
- [ ] 正确凭证 → 登录成功，跳转首页
- [ ] 错误密码 → 提示错误，不跳转
- [ ] 空输入 → 按钮禁用或提示必填
验收标准的粒度根据功能重要性调整：核心功能详细列出，辅助功能简要描述即可。
需求确认交互协议
生成 plan.md 后，必须同时向用户输出：
- 需求理解摘要（3-5 句话概括核心理解）
- 疑问点和假设清单（AI 不确定或做了假设的地方）
- 请求用户确认（明确告知：确认后才开始编码）
示例输出：
## 我的理解
[3-5句话摘要]
## 疑问与假设
- ❓ [需要确认的问题1]
- 💡 [我做的假设1]（如不正确请指出）
已生成 docs/plan.md，请查看确认。确认后我将生成进度追踪文档并开始编码。
用户提出修改 → 更新 plan.md → 再次输出摘要确认 → 双方一致后才进入下一阶段。
plan.md 格式
参见 templates.md 中的 plan.md 模板。
阶段二：进度追踪（progress.md）
基于已确认的 plan.md 自动拆解生成，功能项与 plan.md 一一对应。
状态标记
| 标记 | 含义 |
|---|---|
| ✅ | 已完成 |
| 🚧 | 进行中 |
| ⏳ | 待开发 |
| ❌ | 已取消（备注原因） |
| 🔬 | 调研中 |
测试状态标记
| 标记 | 含义 |
|---|---|
| 🧪 | 待验证 |
| ✅ | 已验证通过 |
progress.md 功能表包含「测试状态」列，区分"代码写完"和"验证通过"：
- 开发完成但未验证 → 开发 ✅ / 测试 🧪
- 验证通过 → 开发 ✅ / 测试 ✅
更新规则
- 开始某功能 → 🚧，更新总体进度完成度
- 功能完成 → ✅，填写完成日期，测试状态标记为 🧪
- 验证通过 → 测试状态改为 ✅
- 确认不做 → ❌，备注原因
- 每完成一个阶段，在更新日志中添加记录
progress.md 格式
参见 templates.md 中的 progress.md 模板。
阶段三：技术架构文档（architecture.md，可选）
触发条件
满足任一即生成：
- 涉及 3 个以上模块交互
- 需要做架构层面的设计决策
- 有复杂的数据流或状态管理
- 用户主动要求
内容要点
- 模块划分与职责边界
- 模块间关系与数据流向
- 关键技术选型及理由
- 核心设计决策与权衡
阶段四：问题记录（FAQ.md）
记录范围
不仅记录"遇到的问题"，还包括：
| 类型 | 示例 |
|---|---|
| 问题与解决方案 | 编译报错、运行时异常、API 行为不符预期 |
| 技术选型决策 | 为什么选 A 而不是 B，对比了哪些方案 |
| 非直觉行为 | 框架/API 的意外表现，容易踩的坑 |
| 特殊用法 | 某技术的非常规但必要的使用方式 |
记录格式
每条记录包含：Q（问题标题）→ 问题描述 → 原因 → 解决方案 → 注意事项
按技术领域分类归档，保持目录索引。
更新时机
编码全程持续更新，不要等到最后才补。
FAQ.md 格式
参见 templates.md 中的 FAQ.md 模板。
阶段五：技术学习路线（learning.md，可选）
触发条件
- 用户提到"不太熟悉"、"第一次用"、"学习"
- AI 判断所用技术较为小众或用户可能不熟悉
内容结构
每项技术包含：
- 是什么：一句话概述
- 为什么选它：选型理由
- 核心概念：3-5 个需要掌握的关键点，附简要解释
- 在本项目中的用法：结合项目代码说明
- 推荐资源：官方文档 + 1-2 个教程
learning.md 格式
参见 templates.md 中的 learning.md 模板。
阶段六：分阶段编码 + 检查点
编码规范（强制）
最佳实践
- 遵循所用技术栈的官方推荐和社区共识
- 代码结构清晰，职责单一
- 适当的错误处理和边界情况覆盖
禁止硬编码
- 所有可配置值（URL、阈值、文案、路径等）提取到独立配置文件或常量定义
- 环境相关配置（开发/生产）应可切换
命名规范
- 遵循所用语言的社区惯例
- 命名自解释，体现用途而非实现
- 布尔变量使用 is/has/should 等前缀
- 项目内风格保持一致
配置管理
- 提供独立、完善的配置模块
- 配置项有合理默认值
- 新增配置不应要求修改业务逻辑代码
测试要求
根据功能重要性分级：
| 重要性 | 测试要求 |
|---|---|
| 核心逻辑（数据处理、鉴权、支付等） | 必须编写自动化测试（单元/集成），覆盖正常路径+边界用例 |
| 一般功能（CRUD、UI 交互） | 关键路径写测试，其余可按验收标准人工验证 |
| 辅助功能（日志、配置读取） | 按需，不强制自动化测试 |
无论是否有自动化测试，验收标准都必须逐项确认通过。
阶段检查点
每完成一个阶段，执行以下检查：
## 阶段 N 回顾
### 完成情况
- [列出本阶段实际完成的功能]
### 偏离与调整
- [是否有偏离 plan.md 的地方？原因是什么？]
### 下一阶段准备
- [下一阶段是否需要调整计划？]
- [是否发现了新的风险或依赖？]
检查点输出后，更新 progress.md 和 FAQ.md（如有新问题）。
阶段七：生成 AGENTS.md
完整流程的最后一步：在项目根目录生成 AGENTS.md。
此文件包含持续开发规则（任务类型判断、编码后自动更新文档、阶段检查点触发、编码规范提醒），在后续每次对话中自动加载，保证持续开发阶段的规则 100% 生效，且跨编辑器通用。
生成规则
- 根据 templates.md 中的 AGENTS.md 模板生成
- 将模板中的
[项目名]替换为实际项目名 - 放在项目根目录（不是
docs/目录）
补充生成
如果项目已有 docs/plan.md 等文档但缺少 AGENTS.md（例如早期项目迁移），可以单独执行此步骤生成 AGENTS.md。
文档存放约定
项目根目录/
├── AGENTS.md # 持续开发规则（每次对话自动加载）
└── docs/
├── plan.md # 开发计划（必须）
├── progress.md # 开发进度（必须）
├── FAQ.md # 问题记录（必须）
├── architecture.md # 技术架构（可选，复杂项目）
└── learning.md # 技术学习路线（可选）
详细模板
所有文档模板参见 templates.md。