计划架构师

计划架构师把设计文档转化为可执行的详细实现计划,核心功能包括设计文档解析、任务拆分(2-5分钟粒度)、TDD驱动计划(红-绿-重构)、YAGNI与DRY原则应用、计划文档与执行检查清单输出。适用于项目实施、功能开发、系统重构、技术迁移、Bug修复计划、技术债务清理场景。触发关键词:项目计划、任务拆分、TDD开发、实现计划、工程效率、计划架构、设计转计划。 功能涵盖: plan, architect。 功能涵盖: plan, architect。

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

快速开始

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: 任务描述格式化

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

输入定义

参数名	类型	必填	说明
input	string	是	计划架构师处理的输入数据或指令
options	object	否	附加配置选项,如模式选择、格式偏好等
callback_url	string	否	异步处理完成后的回调通知URL

text

- **文件**: `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: 用户认证功能计划

输入:

text

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

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

markdown

- 目标: 为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邮箱密码认证
• 代码:

ts

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分钟)

text

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

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

text

**输出** (`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分钟

补充代码示例

python

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)

错误恢复方案

异常类型	触发条件	根因排查	恢复方案
鉴权异常	API Key缺失或无效	检查环境变量是否设置,Key是否过期	重新配置Key,重启会话
配额耗尽	请求频率超出限额	查看API调用计数和配额限制	等待配额刷新或升级套餐
连接超时	网络不可达或响应慢	检查DNS解析,代理设置,防火墙规则	切换网络或配置代理
参数校验失败	必填参数缺失或值非法	对照参数说明表逐项检查	修正参数后重新提交
内部错误	服务端500/502/503	平台侧故障,通常暂时性	等待1分钟后重试,最多2次

环境要求

运行环境

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

依赖说明(补充)

依赖项	类型	是否必需	获取方式	国内替代方案
LLM API	API	必需	由Agent内置LLM提供计划生成	国内Agent(通义/文心/智谱)均可
前置Skill	Skill	推荐	brainstorm-facilitator输出的设计文档	任何能产出设计文档的方法
后续Skill	Skill	推荐	plan-executor或subagent-orchestrator执行计划	手动执行也可
测试框架	工具	推荐	项目对应的测试框架(Jest/pytest/Go test/vitest)	国内cnpm/pip安装
Git	工具	可选	版本控制,每个任务一个提交	国内用Gitee/GitCode
包管理器	工具	必需	npm/pnpm/pip/cargo	国内用cnpm/tnpm/清华源

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密钥泄露	高	通过环境变量配置，禁止硬编码	定期检查代码和配置文件
命令执行风险	高	仅执行白名单命令，避免拼接用户输入	使用沙箱环境测试
网络通信安全	中	使用HTTPS协议，验证SSL证书	定期检查证书有效期
敏感数据暴露	高	输出结果中不包含密钥、令牌等敏感信息	日志脱敏审查
未授权访问	中	限制访问权限，实施认证机制	定期审计访问日志
使用前请确认已阅读依赖说明章节，确保运行环境满足安全要求。

性能数据

操作场景	手动耗时	自动化耗时	效率提升
文件解析与提取	5-10分钟/个	<5秒/个	60-120x
批量文件处理(100个)	8-16小时	<5分钟	96-192x
API调用与响应解析	2-3分钟/次	<1秒/次	120-180x
多接口数据聚合	15-30分钟	<10秒	90-180x
命令执行与结果收集	3-5分钟/次	<2秒/次	90-150x
重复任务批量执行	因任务而异	线性缩减	5-50x
错误排查与修复	10-30分钟	<30秒	20-60x

优势分析

对比维度	计划架构师	传统手动方式	通用脚本工具
自动化程度	全流程自动	完全手动	部分自动
错误处理	内置错误恢复	依赖人工经验	基本try-catch
可复用性	参数化配置	一次性脚本	模板化
安全合规	内置安全检查	无安全保障	无安全保障
适用场景	"把设计文档变成可执行计划,任务拆到2-5分钟粒度,初级工程师也能照做。计划架构	通用场景	通用场景

主要功能

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

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

计划架构师通用排查步骤

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

异常处理策略

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

错误类型	原因分析	解决方案
API认证失败(401)	API密钥错误或过期	检查密钥配置,重新生成token
接口限流(429)	请求频率超出限制	降低调用频率,启用重试退避策略
响应超时(504)	网络延迟或服务端负载过高	增加超时阈值,检查网络连接
文件不存在	路径错误或文件未创建	检查路径拼写,确认文件已生成
文件格式不支持	扩展名不在支持列表中	转换为支持的格式后重试
权限不足	当前用户无读写权限	检查文件权限,以管理员身份运行
命令执行失败	参数错误或环境依赖缺失	检查命令语法,确认依赖已安装
进程超时	命令执行时间过长	增加超时设置,优化命令参数
网络连接失败	DNS解析失败或防火墙拦截	检查网络配置,确认代理设置