---

name: zco-plan description: 读取并执行 docs/plans/ 目录下的项目开发计划。当用户需要执行某个编号的计划任务时使用此 Skill。 allowed-tools: Bash, Read, Glob

执行项目开发计划

🎯 Skill 用途

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

核心功能：

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

📋 何时使用此 Skill

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

1. 用户明确请求执行计划

   • "执行计划 002"
   • "运行 plan 003"
   • "/zco-plan 001"

2. 用户提及计划文档

   • "按照 docs/plans/plan.002.*.md 实施"
   • "实现计划 003 中的功能"

3. 定期任务执行

   • 每日/每周的开发任务
   • 迭代计划执行

📥 参数说明

命令格式：

zco-plan {seq_number}

参数：

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

示例：

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

无参数调用：

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

🚀 使用步骤

Step 1: 解析参数

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

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

Step 2: 查找计划文档

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

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

查找逻辑：

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

Step 3: 读取计划内容

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

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

文档结构：

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

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

## 🎯 目标
任务核心目标

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

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

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

Step 3.5: 自动更新计划状态

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

# 调用 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 (执行失败)

执行完成后：

# 成功完成
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: 解析并执行任务

我会：

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

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

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

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 句话）
• 📋 详细需求 - 功能描述、特殊要求、输入输出
• ✅ 验证标准 - 完成标准清单

推荐部分：

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

🔧 查找计划文档逻辑

单一匹配（最常见）

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

# 结果：直接使用此文件

多版本匹配

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

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

选择策略：

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

未找到计划

# 用户输入：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 格式正确
• ✅ 至少包含目标、详细需求、验证标准三个部分
• ✅ 验证标准使用清单格式（- [ ]）

命名规范

正确格式：

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)

错误格式：

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

🐛 失败排查

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

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

解决方案：

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

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

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

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

解决方案：

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

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

错误 3: YAML front matter 解析失败

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

解决方案：

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

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

错误 4: 参数格式错误

原因：seq_number 不是 3 位数字

解决方案：

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

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

📚 使用示例

示例 1: 执行现有计划

用户请求：

zco-plan 002

Claude 执行流程：

1. ✅ 解析参数：seq = 002
2. ✅ 查找文档：找到 docs/plans/plan.002.20260108.md
3. ✅ 读取内容：解析 YAML 和 Markdown
4. ✅ 显示计划概览：

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

5. ✅ 进入 plan 模式并执行任务

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

用户请求：

zco-plan

Claude 执行流程：

1. ✅ 扫描 docs/plans/ 目录
2. ✅ 列出所有计划文档：

   可用的计划列表：
   
   📋 plan.001.260107.md
      标题：配置同步功能
      状态：completed
      日期：2026-01-07
   
   📋 plan.002.260108.md
      标题：.claudeignore 生成
      状态：pending
      日期：2026-01-08
   

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

示例 3: 处理多版本计划

用户请求：

zco-plan 002

文件系统状态：

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

Claude 执行流程：

1. ✅ 查找到 2 个匹配文件
2. ✅ 按日期排序选择最新版本：plan.002.20260108.md
3. ✅ 提示用户：

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

4. ✅ 继续执行

示例 4: 计划不存在

用户请求：

zco-plan 999

Claude 执行流程：

1. ❌ 未找到任何匹配文件
2. ✅ 提示错误并列出可用计划：

   未找到计划 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（本文件）

相关 Skills

命名约定：所有自定义 skills 使用 zco- 前缀（Zhicheng Custom Operations）

• zco-docs-update - 更新 CLAUDE.md 元信息
• zco-plan - 执行项目开发计划（本 Skill）

创建新计划

方式 1：手动创建

# 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 .claude/zco-scripts/co-plan-new.sh 003 "实现用户认证"

💡 最佳实践

1. 计划文档管理

命名约定：

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

版本控制：

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

目录组织：

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

2. 任务执行流程

推荐工作流：

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

3. 计划文档质量

必须包含：

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

推荐包含：

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

4. 与团队协作

共享计划：

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

状态同步：

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

🎓 技术细节

Skill 调用逻辑

1. 参数提取：

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

2. 文档查找：

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

3. 内容读取：

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

4. 任务执行：

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

工具限制

允许的工具：

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

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

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

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

错误处理策略

# 伪代码示例
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)

🌟 扩展功能（未来）

计划状态自动更新

# 执行前
status: pending

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

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

计划列表命令

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

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

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

计划归档

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

计划模板库

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

---

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