# ProjectPlanner

> 编写代码前的系统性需求分析、规划和项目文档管理。覆盖完整开发生命周期：需求对齐（plan.md）、进度追踪（progress.md）、问题记录（FAQ.md）、技术架构（architecture.md）、技术学习路线（learning.md），并强制遵循编码最佳实践。当用户描述一个需要实现的功能或任务时自动应用，先完成分析和规划再开始编码。适用于新功能开发、架构设计、API设计、代码重构、复杂Bug修复等场景。

- Skill: `songpl-ai/projectplanner` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add songpl-ai/projectplanner`
- Raw SKILL.md: https://api.skillmd.com/api/skills/songpl-ai/projectplanner/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: songpl-AI (https://skillmd.com/u/songpl-ai)
- Updated: 2026-09-22
- Page: https://skillmd.com/skills/songpl-ai/projectplanner

---


# 需求分析、规划与项目管理

## 核心原则

**先规划，再编码。** 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）

### 分析步骤

1. **澄清目标**：用一句话概括核心目标
2. **识别约束**：技术栈、性能、兼容性、现有代码限制
3. **边界确认**：明确范围内和范围外的内容
4. **歧义处理**：发现模糊点**优先向用户确认**，不自行假设

### 按任务类型深入分析

| 任务类型 | 分析重点 |
|---------|---------|
| 新功能开发 | 涉及模块、数据流向、新增 vs 修改、对现有功能的影响 |
| 架构设计 | 职责边界、设计模式、扩展性、技术债务 |
| API 设计 | 接口契约、错误处理、版本兼容、鉴权模型 |
| 代码重构 | 现有问题、重构范围、渐进式路径、测试覆盖 |
| 复杂 Bug | 根因定位、影响范围、修复副作用、回归测试 |

### 方案设计

1. 列出 2-3 个候选方案，标注优劣
2. 给出推荐方案及理由
3. 标注**已知风险**、不确定性和外部依赖
4. 将方案拆解为分阶段实现步骤

### 验收标准（Acceptance Criteria）

plan.md 中的**每个功能点**都应附带验收标准，明确"做到什么程度算完成"：

```
### 1.1 用户登录
- [ ] 实现邮箱+密码登录

验收标准：
- [ ] 正确凭证 → 登录成功，跳转首页
- [ ] 错误密码 → 提示错误，不跳转
- [ ] 空输入 → 按钮禁用或提示必填
```

验收标准的粒度根据功能重要性调整：核心功能详细列出，辅助功能简要描述即可。

### 需求确认交互协议

生成 plan.md 后，**必须同时**向用户输出：

1. **需求理解摘要**（3-5 句话概括核心理解）
2. **疑问点和假设清单**（AI 不确定或做了假设的地方）
3. **请求用户确认**（明确告知：确认后才开始编码）

```
示例输出：

## 我的理解
[3-5句话摘要]

## 疑问与假设
- ❓ [需要确认的问题1]
- 💡 [我做的假设1]（如不正确请指出）

已生成 docs/plan.md，请查看确认。确认后我将生成进度追踪文档并开始编码。
```

用户提出修改 → 更新 plan.md → 再次输出摘要确认 → **双方一致后才进入下一阶段**。

### plan.md 格式

参见 [templates.md](references/templates.md) 中的 plan.md 模板。

---

## 阶段二：进度追踪（progress.md）

基于已确认的 plan.md 自动拆解生成，功能项与 plan.md 一一对应。

### 状态标记

| 标记 | 含义 |
|------|------|
| ✅ | 已完成 |
| 🚧 | 进行中 |
| ⏳ | 待开发 |
| ❌ | 已取消（备注原因） |
| 🔬 | 调研中 |

### 测试状态标记

| 标记 | 含义 |
|------|------|
| 🧪 | 待验证 |
| ✅ | 已验证通过 |

progress.md 功能表包含「测试状态」列，区分"代码写完"和"验证通过"：
- 开发完成但未验证 → 开发 ✅ / 测试 🧪
- 验证通过 → 开发 ✅ / 测试 ✅

### 更新规则

- 开始某功能 → 🚧，更新总体进度完成度
- 功能完成 → ✅，填写完成日期，测试状态标记为 🧪
- 验证通过 → 测试状态改为 ✅
- 确认不做 → ❌，备注原因
- **每完成一个阶段**，在更新日志中添加记录

### progress.md 格式

参见 [templates.md](references/templates.md) 中的 progress.md 模板。

---

## 阶段三：技术架构文档（architecture.md，可选）

### 触发条件

满足**任一**即生成：
- 涉及 3 个以上模块交互
- 需要做架构层面的设计决策
- 有复杂的数据流或状态管理
- 用户主动要求

### 内容要点

- 模块划分与职责边界
- 模块间关系与数据流向
- 关键技术选型及理由
- 核心设计决策与权衡

---

## 阶段四：问题记录（FAQ.md）

### 记录范围

不仅记录"遇到的问题"，还包括：

| 类型 | 示例 |
|------|------|
| 问题与解决方案 | 编译报错、运行时异常、API 行为不符预期 |
| 技术选型决策 | 为什么选 A 而不是 B，对比了哪些方案 |
| 非直觉行为 | 框架/API 的意外表现，容易踩的坑 |
| 特殊用法 | 某技术的非常规但必要的使用方式 |

### 记录格式

每条记录包含：Q（问题标题）→ 问题描述 → 原因 → 解决方案 → 注意事项

按技术领域分类归档，保持目录索引。

### 更新时机

编码全程持续更新，**不要等到最后才补**。

### FAQ.md 格式

参见 [templates.md](references/templates.md) 中的 FAQ.md 模板。

---

## 阶段五：技术学习路线（learning.md，可选）

### 触发条件

- 用户提到"不太熟悉"、"第一次用"、"学习"
- AI 判断所用技术较为小众或用户可能不熟悉

### 内容结构

每项技术包含：
- **是什么**：一句话概述
- **为什么选它**：选型理由
- **核心概念**：3-5 个需要掌握的关键点，附简要解释
- **在本项目中的用法**：结合项目代码说明
- **推荐资源**：官方文档 + 1-2 个教程

### learning.md 格式

参见 [templates.md](references/templates.md) 中的 learning.md 模板。

---

## 阶段六：分阶段编码 + 检查点

### 编码规范（强制）

#### 最佳实践
- 遵循所用技术栈的官方推荐和社区共识
- 代码结构清晰，职责单一
- 适当的错误处理和边界情况覆盖

#### 禁止硬编码
- 所有可配置值（URL、阈值、文案、路径等）提取到独立配置文件或常量定义
- 环境相关配置（开发/生产）应可切换

#### 命名规范
- 遵循所用语言的社区惯例
- 命名自解释，体现用途而非实现
- 布尔变量使用 is/has/should 等前缀
- 项目内风格保持一致

#### 配置管理
- 提供独立、完善的配置模块
- 配置项有合理默认值
- 新增配置不应要求修改业务逻辑代码

#### 测试要求

根据功能重要性分级：

| 重要性 | 测试要求 |
|--------|---------|
| 核心逻辑（数据处理、鉴权、支付等） | 必须编写自动化测试（单元/集成），覆盖正常路径+边界用例 |
| 一般功能（CRUD、UI 交互） | 关键路径写测试，其余可按验收标准人工验证 |
| 辅助功能（日志、配置读取） | 按需，不强制自动化测试 |

无论是否有自动化测试，**验收标准都必须逐项确认通过**。

### 阶段检查点

**每完成一个阶段**，执行以下检查：

```
## 阶段 N 回顾

### 完成情况
- [列出本阶段实际完成的功能]

### 偏离与调整
- [是否有偏离 plan.md 的地方？原因是什么？]

### 下一阶段准备
- [下一阶段是否需要调整计划？]
- [是否发现了新的风险或依赖？]
```

检查点输出后，更新 progress.md 和 FAQ.md（如有新问题）。

---

## 阶段七：生成 AGENTS.md

完整流程的**最后一步**：在项目根目录生成 `AGENTS.md`。

此文件包含持续开发规则（任务类型判断、编码后自动更新文档、阶段检查点触发、编码规范提醒），在后续每次对话中自动加载，保证持续开发阶段的规则 100% 生效，且跨编辑器通用。

### 生成规则

- 根据 [templates.md](references/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](references/templates.md)。