执行项目开发计划

🎯 Skill 用途

自动读取 docs/plans/ 目录下的结构化计划文档，理解任务需求，并以 plan 模式设计实施方案。

核心功能：

•查找计划文档：根据序号在 docs/plans/ 目录中定位计划文件
•读取计划内容：解析 YAML front matter 和 Markdown 内容
•执行任务：以 plan 模式理解需求并设计实施方案
•智能匹配：支持多版本计划自动选择最新版本

📋 何时使用此 Skill

当以下情况发生时，Claude 会自动提议使用此 Skill（或您也可以手动请求）：

•
用户明确请求执行计划
- •"执行计划 002"
- •"运行 plan 003"
- •"/zco-plan 001"
•
用户提及计划文档
- •"按照 docs/plans/plan.002.*.md 实施"
- •"实现计划 003 中的功能"
•
定期任务执行
- •每日/每周的开发任务
- •迭代计划执行

📥 参数说明

命令格式：

bash

zco-plan {seq_number}

参数：

•seq_number - 计划序号（必需），任意位数字（1、02、003、0100 均可）

示例：

bash

zco-plan 002  # 执行计划 002
zco-plan 010  # 执行计划 010

无参数调用：

bash

zco-plan      # 列出所有可用计划

🚀 使用步骤

Step 1: 解析参数

首先，我会提取用户提供的计划序号：

markdown

用户输入：zco-plan 002
提取序号：002

Step 2: 查找计划文档

使用 Glob 工具在 docs/plans/ 目录查找匹配的计划文档：

bash

# 查找模式：plan.{seq}.{extra}.md
# 示例：plan.002.20260108.md, plan.2.feature.md, plan.0100.issue946.md

查找逻辑：

•✅ 搜索 docs/plans/plan.{seq}.*.md（支持任意长度序号）
•✅ 如果找到唯一文件 → 直接使用
•✅ 如果找到多个文件 → 选择日期最新的（按文件名排序）
•✅ 如果未找到 → 提示错误并列出可用计划

Step 3: 读取计划内容

使用 Read 工具读取计划文档的完整内容：

bash

# 读取计划文档
cat docs/plans/plan.002.20260108.md

文档结构：

yaml

---
seq: 002
title: "任务标题"
author: ""
status: "draft:0"
priority: "p2:中:可纳入后续迭代计划"
created_at: ""
updated_at: ""
tags: []
---

# 开发任务：{任务标题}

## 🎯 目标
任务核心目标

## 📋 详细需求
具体功能描述

## ✅ 验证标准
完成标准清单

## 🧪 测试计划
测试场景和用例

Step 3.5: 自动更新计划状态

在开始执行任务前，自动更新计划元数据：

bash

# 调用 metadata 更新脚本
echo '{"plan_path": "docs/plans/plan.002.md", "action": "start", "tags": ["feature", "backend"]}' | \
  python3 .claude/zco-scripts/update-plan-metadata.py

自动更新的字段：

•✅ status: draft:0 → ongoing:2 (开始执行)
•✅ created_at: 首次执行时设置 (YYYY-MM-DD HH:MM:SS)
•✅ updated_at: 每次执行时更新
•✅ tags: Claude 根据任务内容生成

状态转换：

•draft:0 → ongoing:2 (开始执行)
•ongoing:2 → completed:3 (任务完成)
•ongoing:2 → failed:4 (执行失败)

执行完成后：

bash

# 成功完成
echo '{"plan_path": "docs/plans/plan.002.md", "action": "complete"}' | \
  python3 .claude/zco-scripts/update-plan-metadata.py

# 执行失败
echo '{"plan_path": "docs/plans/plan.002.md", "action": "fail"}' | \
  python3 .claude/zco-scripts/update-plan-metadata.py

Step 4: 解析并执行任务

我会：

•✅ 解析 YAML front matter 中的元数据
•✅ 理解任务目标和详细需求
•✅ 识别验证标准和测试计划
•✅ 进入 plan 模式设计实施方案
•✅ 按照计划逐步执行任务

Step 5: 更新计划状态（自动）

任务完成后，自动更新计划文档的状态字段：

yaml

status: draft:0 → ongoing:2 → completed:3
created_at: 2026-01-09 15:30:00 (首次执行时设置)
updated_at: 2026-01-09 16:45:00 (每次执行时更新)

📝 计划文档格式说明

YAML Front Matter（元数据）

字段	说明	示例
`seq`	计划序号（任意位数字）	`002`, `1`, `0100`
`title`	任务标题	`"实现用户认证功能"`
`author`	作者/负责人（可空）	`"张三"` 或 `""`
`status`	任务状态（枚举）	`draft:0`, `ongoing:2`, `completed:3`
`priority`	优先级（枚举）	`p0:紧急:重要`, `p2:中:可纳入后续迭代计划`
`created_at`	创建时间（自动填充）	`2026-01-09 15:30:00`
`updated_at`	更新时间（自动更新）	`2026-01-09 16:45:00`
`tags`	标签列表（自动生成）	`[feature, backend, api]`

状态枚举值：

•draft:0 - 起稿中
•ready:1 - 准备就绪
•ongoing:2 - 进行中（zco-plan 执行时自动设置）
•completed:3 - 执行完成（zco-plan 完成时自动设置）
•failed:4 - 执行失败
•canceled:5 - 已取消
•archived:8 - 已归档

优先级枚举值：

•p0:紧急:重要 - 紧急且重要
•p1:高:当前迭代/排期内重点解决
•p2:中:可纳入后续迭代计划（默认）
•p3:低:可记录，待后续评估
•p4:无:不影响当前迭代/排期

Markdown 内容结构

必需部分：

•🎯 目标 - 任务核心目标（1-2 句话）
•📋 详细需求 - 功能描述、特殊要求、输入输出
•✅ 验证标准 - 完成标准清单

推荐部分：

•🧪 测试计划 - 单元测试、集成测试、手动测试
•📚 参考信息 - 相关文档、现有实现、技术选型

🔧 查找计划文档逻辑

单一匹配（最常见）

bash

# 示例：只有一个 plan.002 的文件
docs/plans/plan.002.20260108.md

# 结果：直接使用此文件

多版本匹配

bash

# 示例：存在多个 plan.002 的版本
docs/plans/plan.002.20260105.md  # 旧版本
docs/plans/plan.002.20260108.md  # 新版本

# 结果：自动选择日期最新的（20260108）

选择策略：

•按文件名字母序降序排序（sort -r）
•选择第一个（日期最新的）

未找到计划

bash

# 用户输入：zco-plan 999
# 结果：未找到任何 plan.999.*.md

# 提示信息：
未找到计划 999
可用的计划列表：
- plan.001.260107.md - 配置同步功能
- plan.002.260108.md - .claudeignore 生成

⚠️ 注意事项

前置条件

•✅ docs/plans/ 目录必须存在
•✅ 计划文档命名格式必须为 plan.{seq}.**.md
•✅ 计划文档必须包含有效的 YAML front matter
•✅ seq_number 是数字（可以用0前缀, 比如001-999, 不限位数）

计划文档规范

•✅ 使用标准模板创建（docs/plans/plan.template.md）
•✅ YAML front matter 格式正确
•✅ 至少包含目标、详细需求、验证标准三个部分
•✅ 验证标准使用清单格式（- [ ]）

命名规范

正确格式：

code

plan.001.20260108.md  ✅ (seq=001)
plan.002.权限验证.md  ✅ (seq=002)
plan.0100.issue946.md  ✅  (seq=0100)
plan.0100.issue946.用户鉴权.md  ✅ (seq=0100)
plan.1.20260108.md     ✅ (seq=1)
plan.002.md            ✅ (seq=002)

错误格式：

code

plan-002-20260108.md   ❌ (使用了 - 而非 .)
task.002.20260108.md   ❌ (不是 plan 前缀)

🐛 失败排查

错误 1: "未找到计划 {seq}"

原因：docs/plans/ 目录中不存在对应序号的计划文档

解决方案：

bash

# 1. 查看所有可用计划
ls docs/plans/

# 2. 确认序号是否正确
# 3. 或创建新的计划文档

错误 2: "docs/plans/ 目录不存在"

原因：项目根目录缺少 docs/plans/ 目录

解决方案：

bash

# 创建目录
mkdir -p docs/plans/

# 复制模板
cp docs/plans/plan.template.md docs/plans/plan.001.$(date +%y%m%d).md

错误 3: YAML front matter 解析失败

原因：计划文档的 YAML 格式不正确

解决方案：

bash

# 检查 YAML 语法
head -15 docs/plans/plan.002.20260108.md

# 确保格式为：
# ---
# key: value
# ---

错误 4: 参数格式错误

原因：seq_number 不是 3 位数字

解决方案：

bash

# 错误示例
zco-plan 2     # 应该是 002
zco-plan abc   # 必须是数字

# 正确示例
zco-plan 002   # ✅
zco-plan 010   # ✅

📚 使用示例

示例 1: 执行现有计划

用户请求：

code

zco-plan 002

Claude 执行流程：

•✅ 解析参数：seq = 002
•✅ 查找文档：找到 docs/plans/plan.002.20260108.md
•✅ 读取内容：解析 YAML 和 Markdown

•✅ 显示计划概览：

code

📋 计划 002：.claudeignore 生成功能
作者：张三
状态：pending
优先级：medium
创建时间：2026-01-08 10:30:00

•✅ 进入 plan 模式并执行任务

示例 2: 列出所有可用计划

用户请求：

code

zco-plan

Claude 执行流程：

•✅ 扫描 docs/plans/ 目录

•✅ 列出所有计划文档：

code

可用的计划列表：

📋 plan.001.260107.md
   标题：配置同步功能
   状态：completed
   日期：2026-01-07

📋 plan.002.260108.md
   标题：.claudeignore 生成
   状态：pending
   日期：2026-01-08

•✅ 提示用户选择要执行的计划

示例 3: 处理多版本计划

用户请求：

code

zco-plan 002

文件系统状态：

code

docs/plans/plan.002.20260105.md  (旧版本)
docs/plans/plan.002.20260108.md  (新版本)

Claude 执行流程：

•✅ 查找到 2 个匹配文件
•✅ 按日期排序选择最新版本：plan.002.20260108.md

•✅ 提示用户：

code

找到多个版本的计划 002，自动选择最新版本：
✅ plan.002.20260108.md (2026-01-08)

•✅ 继续执行

示例 4: 计划不存在

用户请求：

code

zco-plan 999

Claude 执行流程：

•❌ 未找到任何匹配文件

•✅ 提示错误并列出可用计划：

code

未找到计划 999

可用的计划列表：
- plan.001.260107.md
- plan.002.260108.md

提示：
- 检查序号是否正确
- 或创建新的计划文档

🔗 相关资源

项目文件

•计划目录: docs/plans/
•计划模板: docs/plans/plan.template.md
•使用指南: docs/plans/README.md
•Skill 定义: .claude/skills/zco-plan/SKILL.md（本文件）

创建新计划

方式 1：手动创建

bash

# 1. 复制模板
cp docs/plans/plan.template.md docs/plans/plan.003.$(date +%y%m%d).md

# 2. 编辑文档
vim docs/plans/plan.003.260108.md

# 3. 填写任务信息

方式 2：使用脚本（如果可用）

bash

# 自动创建新计划
bash .claude/zco-scripts/co-plan-new.sh 003 "实现用户认证"

💡 最佳实践

1. 计划文档管理

命名约定：

•✅ 使用 3 位序号：001, 002, 003...
•✅ 使用 YYMMDD 日期格式：260108
•✅ 保持简洁：plan.{seq}.{date}.md

版本控制：

•✅ 提交计划文档到 Git
•✅ 重大修改时创建新版本（新日期）
•✅ 完成后更新 status 字段

目录组织：

code

docs/plans/
├── plan.001.260107.md  (已完成)
├── plan.002.260108.md  (进行中)
├── plan.003.260108.md  (待开始)
├── plan.template.md    (模板)
└── README.md           (使用指南)

2. 任务执行流程

推荐工作流：

•创建计划文档（填写需求和验证标准）
•提交到 Git（团队审查）
•执行计划：zco-plan {seq}
•Claude 设计方案（plan 模式）
•用户审批方案
•Claude 实施任务
•验证完成标准
•更新计划状态为 completed

3. 计划文档质量

必须包含：

•✅ 清晰的目标描述
•✅ 详细的功能需求
•✅ 明确的验证标准
•✅ 输入输出规范

推荐包含：

•⭐ 测试计划
•⭐ 参考资料
•⭐ 技术选型依据
•⭐ 潜在风险说明

4. 与团队协作

共享计划：

•✅ 计划文档提交到 Git
•✅ Code Review 时审查计划内容
•✅ 使用统一的模板格式
•✅ 定期清理已完成的计划

状态同步：

•pending - 待开始
•in-progress - 进行中
•completed - 已完成
•cancelled - 已取消

🎓 技术细节

Skill 调用逻辑

•

参数提取：

code

用户输入 "zco-plan 002"
→ 提取参数 args = "002"
→ 验证格式（3 位数字）

•

文档查找：

code

→ 使用 Glob: docs/plans/plan.002.*.md
→ 排序选择最新版本
→ 验证文件存在性

•

内容读取：

code

→ 使用 Read 读取完整文档
→ Claude 自然理解 YAML + Markdown
→ 无需手动解析 YAML

•

任务执行：

code

→ 进入 plan 模式
→ 设计实施方案
→ 等待用户批准
→ 执行任务

工具限制

允许的工具：

•✅ Bash - 执行 find、ls 等命令
•✅ Read - 读取计划文档
•✅ Glob - 搜索匹配文件

禁止的工具（仅读取，不修改）：

•❌ Write - 不能创建文件
•❌ Edit - 不能修改文档

原因：Skill 只负责读取和执行计划，创建和修改由用户或专用脚本完成。

错误处理策略

python

# 伪代码示例
def execute_plan(seq_number):
    # 1. 验证参数
    if not is_valid_seq(seq_number):
        return error("序号必须是 3 位数字")

    # 2. 查找文档
    files = glob(f"docs/plans/plan.{seq_number}.*.md")

    if len(files) == 0:
        list_all_plans()  # 显示可用计划
        return error(f"未找到计划 {seq_number}")

    if len(files) > 1:
        plan_file = max(files)  # 选择最新
        warn(f"找到多个版本，使用最新: {plan_file}")
    else:
        plan_file = files[0]

    # 3. 读取并执行
    content = read_file(plan_file)
    show_plan_summary(content)
    execute_in_plan_mode(content)

🌟 扩展功能（未来）

计划状态自动更新

yaml

# 执行前
status: pending

# 执行时
status: in-progress
updated: 2026-01-08 14:30:00

# 完成后
status: completed
updated: 2026-01-08 16:45:00

计划列表命令

bash

# 显示所有计划
zco-plan-list

# 按状态过滤
zco-plan-list --status=pending

# 按优先级过滤
zco-plan-list --priority=high

计划归档

bash

# 自动归档已完成计划
docs/plans/plan.001.260107.md
→ docs/plans/archive/2026/01/plan.001.260107.md

计划模板库

code

docs/plans/templates/
├── feature.md     # 新功能开发模板
├── bugfix.md      # Bug 修复模板
├── refactor.md    # 重构任务模板
└── research.md    # 技术研究模板

Skill 版本: 1.0.0 最后更新: 2026-01-08 维护者: 开发团队

执行项目开发计划

🎯 Skill 用途

📋 何时使用此 Skill

📥 参数说明

🚀 使用步骤

Step 1: 解析参数

Step 2: 查找计划文档

Step 3: 读取计划内容

Step 3.5: 自动更新计划状态

Step 4: 解析并执行任务

Step 5: 更新计划状态（自动）

📝 计划文档格式说明

YAML Front Matter（元数据）

Markdown 内容结构

🔧 查找计划文档逻辑

单一匹配（最常见）

多版本匹配

未找到计划

⚠️ 注意事项

前置条件

计划文档规范

命名规范

🐛 失败排查

错误 1: "未找到计划 {seq}"

错误 2: "docs/plans/ 目录不存在"

错误 3: YAML front matter 解析失败

错误 4: 参数格式错误

📚 使用示例

示例 1: 执行现有计划

示例 2: 列出所有可用计划

示例 3: 处理多版本计划

示例 4: 计划不存在

🔗 相关资源

项目文件

相关 Skills

创建新计划

💡 最佳实践

1. 计划文档管理

2. 任务执行流程

3. 计划文档质量

4. 与团队协作

🎓 技术细节

Skill 调用逻辑

工具限制

错误处理策略

🌟 扩展功能（未来）

计划状态自动更新

计划列表命令

计划归档

计划模板库