计划架构师

核心功能: 本技能提供计划、技术债务清理场景等能力。

计划架构师

快速开始

1. 确认运行环境满足依赖说明中的要求
2. 在AI Agent对话中调用本技能,提供必要的输入参数
3. 检查输出结果,根据需要进行后续处理

详细的输入输出格式请参考下方章节说明。 将设计文档转化为可执行的详细实现计划。每个任务都是 2-5 分钟可完成的粒度,包含精确的文件路径、完整的代码片段、明确的验证步骤。让一个"热情但缺乏判断力的初级工程师"也能按计划执行。

主要特点

1. 设计文档解析:读取design.md或设计输入,提取目标/范围/技术栈/数据模型/架构图,识别依赖关系与执行顺序,确认技术栈版本/团队规模/时间约束/测试要求。
2. 任务拆分(2-5分钟粒度):每个任务2-5分钟可完成,有明确"完成"定义,可独立验证,有精确文件路径;按功能模块/层级(数据层→服务层→API层→UI层)/测试优先(TDD)拆分;无依赖任务可并行,有依赖按序执行,标注阻塞关系。
3. TDD驱动计划:红-绿-重构循环(先写失败测试→再写最小实现→最后重构),测试策略(单元80%/集成15%/E2E 5%),测试覆盖率目标80%+。
4. YAGNI与DRY原则:只实现当前需要的功能(不提前实现"可能需要"的功能),重复代码提取为函数/常量/组件(但不过度抽象,遵循Rule of Three)。
5. 计划输出:保存为plan.md(任务列表带编号+依赖关系图+时间预估总计),执行检查清单(每个任务完成后勾选+验证命令一键运行+回滚步骤)。

使用说明

Step 1: 计划输入分析

1.md或设计输入,提取目标/范围/技术栈/数据模型/架构图,识别依赖关系与执行顺序 2. 约束确认:技术栈版本、团队规模与技能、时间约束、测试要求

Step 2: 任务拆分(2-5分钟粒度)

1. 拆分原则:每个任务2-5分钟可完成,有明确"完成"定义,可独立验证,有精确文件路径
2. 拆分维度:按功能模块拆分、按层级拆分(数据层→服务层→API层→UI层)、按测试优先拆分(TDD:先测试后实现)
3. 依赖排序:无依赖任务可并行,有依赖任务按序执行,标注阻塞关系

Step 3: 任务描述格式化

每个任务按以下格式描述:

输入定义

- **文件**: `src/path/to/file.ts` (新建/修改)
- **描述**: [具体做什么]
- **代码**: [完整代码片段或关键改动]
- **验证**: [如何验证这个任务完成]
  - 命令: `npm test -- --grep "test name"`
  - 预期: 测试通过
- **依赖**: Task M (如果有)
- **时间预估**: ~3分钟

Step 4: TDD驱动计划

1. 红-绿-重构循环:先写失败测试(Red)→再写最小实现(Green)→最后重构(Refactor)
2. 测试策略:单元测试(每个函数/方法)、集成测试(模块间交互)、端到端测试(关键用户流程),覆盖率目标80%+
3. 测试金字塔:80%单元测试(快速/隔离)、15%集成测试(模块交互)、5%E2E测试(用户流程)

Step 5: YAGNI与DRY原则检查

1. YAGNI:只实现当前需要的功能,不提前实现"可能需要"的功能,不过度设计接口,不添加未使用的配置项
2. DRY:重复代码提取为函数,重复配置提取为常量,重复模式提取为组件,但不过度抽象(Rule of Three)

Step 6: 计划输出

1. 计划文档:保存为plan.md,任务列表(带编号)+依赖关系图+时间预估总计
2. 执行检查清单:每个任务完成后勾选+验证命令一键运行+回滚步骤(如需要)

用法示例

示例1: 用户认证功能计划

输入:

为Next.js应用添加邮箱密码认证,使用better-auth,数据库用Drizzle+SQLite。
设计文档已批准,需要生成可执行实现计划。

输出 (output/auth-feature/plan.md):

- 目标: 为Next.js应用添加邮箱密码认证
- 技术栈: Next.js 15 + better-auth + Drizzle + SQLite
- 总任务数: 8
- 预估总时间: ~35分钟
- **文件**: package.json (修改)
- **描述**: 安装better-auth及其类型依赖
- **命令**: `cnpm install better-auth`
- **验证**: `cat package.json | grep better-auth` 输出包含better-auth
- **时间**: ~1分钟
- **文件**: tests/auth.test.ts (新建)
- **描述**: 测试auth配置能正确初始化
- **代码**:
```ts
import { describe, it, expect } from "vitest";
import { auth } from "../lib/auth";
describe("auth配置", () => {
  it("应正确初始化auth实例", () => {
    expect(auth).toBeDefined();
    expect(auth.api).toBeDefined();
  });

• 验证: npx vitest run tests/auth.test.ts
• 预期: 测试失败(配置尚未实现) - Red阶段
• 时间: ~3分钟
• 文件: lib/auth.ts (新建)
• 描述: 配置better-auth邮箱密码认证
• 代码:

import { betterAuth } from "better-auth";
import { drizzleAdapter } from "better-auth/adapters/drizzle";
import { db } from "./db";
export const auth = betterAuth({
  database: drizzleAdapter(db, { provider: "sqlite" }),
  emailAndPassword: { enabled: true },
});

• 预期: 测试通过 - Green阶段
• 依赖: Task 1, Task 2
• 时间: ~4分钟
• 文件: lib/db/schema.ts (新建)
• 描述: 创建users/sessions/accounts表
• 验证: npx drizzle-kit push && sqlite3 app.db ".tables"
• 预期: 输出包含users/sessions/accounts表
• 依赖: Task 3
• 时间: 3分钟 ...(共8个任务,总计35分钟)

### 示例2: Bug修复计划
**输入**:

Bug: 用户购物车在刷新后丢失商品。 根因: 购物车数据仅存在内存中,未持久化到localStorage。 需要生成修复计划,包含测试覆盖和防御措施。

**输出** (`output/cart-bugfix/plan.md`):
```markdown
- 现象: 刷新页面后购物车商品丢失
- 根因: 购物车state仅存内存,未持久化
- 修复策略: 添加localStorage持久化
- **文件**: tests/cart.test.ts (修改)
- **描述**: 测试刷新后购物车数据保留
- **代码**: [测试localStorage持久化和恢复的测试用例]
- **验证**: `npx vitest run tests/cart.test.ts`
- **预期**: 测试失败(持久化未实现)
- **时间**: ~3分钟
- **文件**: hooks/useCart.ts (修改)
- **描述**: 添加localStorage读写逻辑
- **代码**: [useEffect持久化+初始化时恢复的代码]
- **预期**: 测试通过
- **依赖**: Task 1
- **时间**: ~4分钟
- **描述**: SSR环境下localStorage不存在,需做安全检查
- **代码**: [typeof window检查+try-catch包裹]
- **验证**: `npm run build` 构建成功(无SSR错误)
- **依赖**: Task 2
- **时间**: ~2分钟

补充代码示例

def parse_design_document(document):
    tasks = document.split('\n')
    detailed_tasks = []
    for task in tasks:
        if '开发' in task:
            detailed_tasks.append(task + ' (5分钟)')
        elif '测试' in task:
append(task + ' (2分钟)')
        else:
append(task + ' (10分钟)')
    return detailed_tasks
design_document = """
功能开发：
- 用户界面设计
- 数据库模型建立
- API接口实现
- 功能测试
系统重构：
- 代码优化
- 性能提升
- 安全加固
"""
detailed_plan = parse_design_document(design_document)
print(detailed_plan)
def create_tdd_plan(tasks):
    tdd_plan = []
    for task in tasks:
        tdd_plan.append(f"Red: {task}")
        tdd_plan.append(f"Green: {task} (实现功能)")
        tdd_plan.append(f"Refactor: {task} (优化代码)")
    return tdd_plan
tdd_plan = create_tdd_plan(detailed_plan)
print(tdd_plan)
def generate_checklist(plan):
    checklist = []
    for step in plan:
        checklist.append(f"- {step}")
    return checklist
checklist = generate_checklist(tdd_plan)
print(checklist)

错误恢复方案

环境要求

运行环境

• Agent平台: Claude Code / Cursor / Codex / Gemini CLI / Windsurf 等支持SKILL.md的任意Agent
• 操作系统: Windows / macOS / Linux
• 运行时: 需要Agent支持exec(命令行执行)能力

依赖说明(补充)

API Key 配置

• 本Skill无需额外API Key配置: 纯方法论指导,计划生成由Agent LLM完成
• 安全要求: API Key零暴露,不写入计划文档、不输出到日志、不硬编码

可用性分类

• 分类: MD+EXEC
• 说明: 纯Markdown,但需要exec能力(命令行执行),用于文件读写和验证命令运行

高频问答

Q1: 计划架构师支持哪些输入格式？

A1: 把设计文档变成可执行计划,任务拆到2-5分钟粒度,初级工程师也能照做。计划架构师把设计文档转化为可执行的详细实现计划,核心功能包括设计文档解析、任务拆分(2-5。支持文本指令和结构化参数输入，具体格式参考使用流程章节。

Q2: 需要配置API Key吗？

A2: 是的，部分功能需要配置对应平台的API Key。请在依赖说明章节查看具体要求，并通过环境变量安全配置。

Q3: 命令行执行失败怎么办？

A3: 检查命令参数是否正确，确认运行环境支持exec能力。如遇权限问题，请参照错误处理章节排查。

安全免责声明

安全风险防范

性能数据

优势分析

主要功能

计划架构师把设计文档转化为可执行的详细实现计划,

• 文件处理: 支持多种文件格式的读取、解析和写入操作
• API集成: 通过标准化接口调用外部服务并处理响应
• 命令执行: 在安全沙箱中执行系统命令并收集结果

计划架构师通用排查步骤

1. 检查输入参数: 确认所有必填参数已提供且格式正确
2. 查看日志输出: 定位具体错误行和异常类型
3. 验证环境配置: 确认依赖库版本和运行环境满足要求
4. 逐步调试: 缩小问题范围,隔离故障模块

异常处理策略

针对计划架构师使用中可能遇到的常见问题,提供以下排查方案: