当前位置：首页 > news >正文

Claude Code PM 深度实战指南：AI驱动的GitHub项目管理与并行协作

news 2025/9/6 5:28:53

概述与核心理念
基础入门：环境准备与项目初始化
核心工作流详解：PRD驱动到GitHub同步
日常使用实践：高效开发与协作
高级用法与自动化：多Agent协同与系统集成
实战案例与最佳实践：项目演练与经验总结
常见问题与进阶技巧：解决实操疑难
参考资源与社区：持续学习与交流

1. 概述与核心理念

在软件开发的浩瀚征途中，效率、透明度和可追溯性始终是团队追求的永恒目标。然而，需求变更、上下文丢失、沟通障碍、以及日益增长的复杂性，常常让项目管理举步维艰。而当人工智能（AI）成为开发流程中的重要参与者时，如何有效整合AI能力、使其与人工协作无缝衔接，更是摆在每位开发者和项目经理面前的新课题。

Claude Code PM（ccpm），正是为应对这些挑战而生。它是一套以产品需求文档（PRD）驱动、深度整合人工智能辅助，并与GitHub Issue紧密集成的项目管理系统。ccpm的核心理念在于，将高层次的产品愿景与用户需求，通过AI智能辅助，逐步细化为可执行的代码任务，并确保所有过程在GitHub上透明可追溯，同时支持多智能体（AI Agent）与人工开发者的高效并行协作。

ccpm的目标是打造一个智能化的项目开发与管理中枢，显著提升团队协作效率，减少不必要的沟通成本，确保开发上下文的完整性，并实现任务的透明化与可追溯性。它旨在将AI从一个辅助工具提升为一种核心的、可管理的开发力量，与人类开发者共同驱动项目进展。

1.1 核心理念：AI驱动、PRD先行、GitHub枢纽

A. PRD驱动开发（PRD-Driven Development）：需求的源头

ccpm将 产品需求文档（PRD） 置于项目工作流的核心。PRD不仅是产品的“说明书”，更是所有开发活动的正向起点。通过结构化的PRD，ccpm确保：

需求共识： 将产品愿景、用户故事、功能定义、验收标准等关键信息标准化，确保团队对产品需求的理解高度一致。
上下文完整： AI Agent和人工开发者都能从PRD中获取完整的、一致的需求上下文，避免因信息不对等导致的开发偏差。
可追溯性： 每一行代码、每一个提交、每一个完成的任务，都能最终追溯到PRD中的具体需求点，形成清晰的需求链路。

B. AI辅助开发：智能化的协作伙伴

ccpm充分利用AI的强大能力，作为开发过程中的智能协作伙伴：

智能分解： AI能够辅助解析PRD，将其分解为Epic（史诗）和具体的、可执行的开发任务。
上下文感知： AI Agent在执行任务时，能够持续感知项目的全局上下文，生成更符合项目风格和需求的方案与代码。
并行加速： 支持多个AI Agent同时处理不同任务，实现并行开发，显著加速项目进度。
进度同步与报告： AI Agent能够自动同步其开发进展、代码输出、遇到的问题，并生成项目报告。

C. GitHub Issue深度集成：透明协作与版本控制

ccpm选择GitHub作为其主要的协同与版本控制平台，实现了与GitHub Issue、Pull Request、代码仓库的深度集成：

单一事实来源： GitHub Issue成为任务管理的单一真相来源，所有任务状态、讨论和代码关联都集中于此。
透明可追溯： 每一个需求、任务、代码提交都通过GitHub Issue关联起来，形成完整的开发轨迹，确保所有历史操作可追溯。
分布式协作： 充分利用GitHub的强大协作能力，无论是人工开发者还是AI Agent，都能在统一的平台上进行协同工作。
代码与任务联动： 代码提交可以直接与Issue关联，Pull Request可以关闭Issue，实现代码与任务的无缝联动。

1.2 适用对象：谁能从中受益？

Claude Code PM的设计旨在为不同规模、不同需求的用户群体带来革命性的效率提升：

希望规范流程、减少沟通成本的团队：
在团队协作中，需求理解不一致、沟通障碍、任务分配不清晰等问题屡见不穷。ccpm通过PRD先行、GitHub Issue集中管理、以及AI辅助分解，极大地减少了这些摩擦。每个任务（Issue）都附带明确的上下文和目标，AI或人工只需关注当前任务，大幅降低了沟通成本和返工率。无论是小团队的敏捷开发，还是大团队的复杂项目管理，都能从中获益。
追求高效、自动化、AI辅助开发的个人开发者：
对于个人开发者而言，在进行独立项目开发时，ccpm能够充当一个“虚拟项目经理”和“虚拟开发伙伴”。AI可以帮助你从混沌的想法中整理出PRD，并一步步分解为可执行的任务，甚至自动生成部分代码。这极大地提升了个人的开发效率，让你能将更多精力投入到创造性工作中。
需要系统化落地AI+GitHub协作的组织：
很多组织都在探索AI在软件开发中的应用，但常常面临AI能力碎片化、与现有流程脱节、难以统一管理的问题。ccpm提供了一套端到端的解决方案，将AI深度嵌入到GitHub驱动的开发流程中，使得AI辅助开发不再是零散的工具尝试，而是有章可循、可管理、可扩展的系统化实践。它帮助组织构建真正的AI驱动型DevOps工作流。

1.3 环境要求：准备你的工作台

为了顺畅运行 Claude Code PM，你需要准备一个符合以下要求的开发环境。这些要求确保了ccpm及其依赖项能够稳定、高效地运行。

操作系统（OS）：
- 推荐：Linux/macOS。ccpm的核心脚本基于Bash，在Unix-like系统上运行最为稳定、高效。
- 兼容：WSL (Windows Subsystem for Linux)。对于Windows用户，强烈推荐安装WSL 2，它提供了一个近乎原生的Linux环境，能够完美兼容ccpm的所有功能。
- 有限支持：PowerShell。ccpm提供PowerShell安装脚本，但由于PowerShell与Bash在命令语法和环境特性上的差异，部分高级功能或辅助脚本可能会遇到兼容性问题。建议优先使用WSL。
必须具备的工具：
- Git： ccpm与GitHub深度集成，所有代码版本控制、仓库交互都需要Git。请确保Git已正确安装并配置好用户名和邮箱。
- curl / wget： 用于从GitHub下载ccpm的安装脚本。请确保你的系统至少安装了其中一个。
- Bash (或PowerShell)： 运行ccpm脚本的Shell环境。Bash是Linux/macOS的默认Shell，WSL也使用Bash。
- GitHub账户： ccpm的所有任务、代码、讨论都将同步到你的GitHub仓库中。你需要一个活跃的GitHub账户，并在后续初始化过程中进行认证。
推荐安装的扩展：
- GitHub CLI (gh)： GitHub官方命令行工具，ccpm核心依赖它来与GitHub API进行交互，例如创建Issue、更新评论、管理仓库等。它的认证和操作都非常便捷。
- gh-sub-issue扩展： 这是gh CLI的一个扩展，用于在GitHub Issue中创建和管理父子任务关系（即Sub-Issue）。ccpm利用它来管理Epic与Task之间的层级关系，确保任务分解的清晰度和可追溯性。

2. 基础入门：环境准备与项目初始化

在开始激动人心的AI辅助开发之旅前，我们首先需要搭建好ccpm的工作环境并进行项目初始化。

2.1 环境搭建：让ccpm在家安稳落户

ccpm的安装设计得尽可能简便，支持多种操作系统和安装方式。

A. Linux/macOS 平台安装（推荐）

在Linux或macOS环境下，你可以通过一行命令快速安装ccpm。这个命令会从GitHub下载安装脚本并执行。

打开你的终端（Terminal）。
切换到你想要初始化pm系统的项目根目录。例如，如果你的项目代码在 ~/my-awesome-project，则执行 cd ~/my-awesome-project。注意： ccpm会在当前目录创建 .claude 文件夹，所以务必在你的项目根目录执行。
执行以下任一命令进行安装：
- 使用 curl：
```
cd path/to/your/project/
curl -sSL https://raw.githubusercontent.com/automazeio/ccpm/main/ccpm.sh | bash
```
- 或者使用 wget：
```
cd path/to/your/project/
wget -qO- https://raw.githubusercontent.com/automazeio/ccpm/main/ccpm.sh | bash
```
- 命令解释：
  - curl -sSL ... | bash 或 wget -qO- ... | bash：这部分命令的作用是下载位于 GitHub 上的 ccpm.sh 脚本，并通过管道 (|) 将其内容直接传递给 bash shell 执行。
    - -s 或 -qO-：静默模式，不显示下载进度。
    - -S 或 -L：如果遇到重定向，会自动跟踪。
  - ccpm.sh 脚本通常会：
    - 在当前目录下创建 .claude/ 文件夹。
    - 将ccpm的核心文件和目录结构克隆或复制到 .claude/ 内部。
    - 将 ccpm 命令（实际上是一个函数的别名或可执行脚本）添加到你的Shell配置文件（如 .bashrc, .zshrc），这样你就可以在任何地方直接使用 pm: 开头的命令了。

B. Windows 平台安装（推荐WSL或PowerShell）

对于Windows用户，强烈推荐使用WSL 2（Windows Subsystem for Linux）作为ccpm的运行环境，因为它提供了最佳的兼容性。如果你无法使用WSL，也可以尝试PowerShell。

针对WSL用户（推荐）：
- 确保你已安装并配置好WSL 2（例如Ubuntu发行版）。
- 打开WSL终端。
- 通过 cd /mnt/c/path/to/your/project 等方式切换到你的Windows项目根目录。
- 然后按照上述 A. Linux/macOS 平台安装 的步骤执行命令。
针对PowerShell用户（有限支持）：
- 打开PowerShell终端（以管理员身份运行可能避免部分权限问题）。
- 切换到你的项目根目录。
- 执行以下命令：
```
cd path\to\your\project
iwr -useb https://raw.githubusercontent.com/automazeio/ccpm/main/ccpm.bat | iex
```
- 命令解释：
  - iwr -useb ... | iex：iwr (Invoke-WebRequest) 用于下载脚本，-useb 确保使用基本解析器。下载后，通过管道 (|) 传递给 iex (Invoke-Expression) 执行。
- PowerShell常见问题及解决：
  - 执行策略报错： 如果遇到“禁止执行脚本”的错误，需要修改PowerShell的执行策略。
```
Set-ExecutionPolicy RemoteSigned -Scope CurrentUser
```
    在执行完ccpm安装后，你可以选择将其改回 Restricted。
  - 404 报错 / 兼容性问题： PowerSehll在处理某些脚本特性时可能与Bash存在差异。如果安装失败或后续命令出现异常，强烈建议转用WSL或采用手动安装方式。

C. 快速手动安装（故障排除或高级用户）

如果自动化安装脚本遇到问题，或者你希望对安装过程拥有更多控制权，可以选择手动克隆GitHub仓库。

打开终端/命令提示符。
切换到你的项目根目录。
克隆ccpm仓库内容（而非整个仓库）到当前目录，并清除Git历史：
```
git clone https://github.com/automazeio/ccpm.git . && rm -rf .git/
```
- 解释： 这个命令会将 ccpm 仓库的所有文件（包括 .claude 目录及其他辅助文件）克隆到你的当前项目目录下。&& rm -rf .git/ 命令接着会删除克隆下来的 .git 隐藏目录，这样你的项目就不会意外地被当成 ccpm 仓库的子模块。
- 后续步骤： 手动安装后，你还需要进行以下配置：
  - 将ccpm命令添加到PATH或别名： 找到 ccpm 的主脚本（通常是 .claude/ccpm.sh 或 .claude/ccpm.bat），将其路径添加到你的PATH环境变量，或者在Shell配置文件（如 .bashrc, .zshrc, profile）中添加一个别名，以便可以直接使用 /pm: 格式的命令。例如：
```
# 在 .bashrc 或 .zshrc 中添加
source ~/.claude/ccpm.sh # ccpm.sh 脚本会设置 PM_COMMAND_PREFIX 函数
```
    确保你的Shell加载了该文件。
  - 手动安装 gh CLI 和 gh-sub-issue 扩展： 参照GitHub CLI官方文档和 gh-sub-issue 的安装说明进行安装。ccpm的 /pm:init 命令会自动检测和安装，但手动方式则需要你自行完成。

2.2 项目初始化：为你的项目注入智能PM能力

成功安装ccpm后，下一步就是对你的项目进行初始化，使其具备AI辅助的项目管理能力。

A. 初始化PM系统：`/pm:init`

这是启动ccpm项目管理功能的第一个关键命令。它会进行一系列的检查和配置，确保你的环境为AI驱动的GitHub协作做好准备。

/pm:init

执行步骤与详细解释：
- GitHub CLI (gh) 检查与安装：
  - ccpm会首先检测你的系统是否安装了 gh CLI。如果没有，它会提示你进行安装，并尝试自动执行安装流程。
  - GitHub认证： gh CLI会引导你完成GitHub账户的认证。这通常会弹出一个浏览器窗口让你登录GitHub，并授权gh访问你的仓库。务必确保认证成功，这是ccpm与GitHub交互的基础。
- gh-sub-issue 扩展检查与安装：
  - 接着，ccpm会检查 gh-sub-issue 扩展是否安装。这个扩展对于管理Epic和Task的父子关系至关重要。如果没有，它会提示并尝试自动安装。
- .claude/ 目录结构创建与初始化：
  - 如果当前目录下没有 .claude/ 文件夹，/pm:init 会自动创建它，并在内部生成ccpm所需的标准目录结构（详见下一节）。
- .gitignore 配置：
  - 为了避免将ccpm的临时文件、日志和AI Agent的中间产物提交到Git仓库中，/pm:init 会自动向你的项目 .gitignore 文件中添加必要的忽略规则。如果你的项目还没有 .gitignore 文件，它会为你创建一个。
- AI API Key 配置提示：
  - ccpm会引导你配置你的AI服务API Key（例如OpenAI或Anthropic Claude的Key）。AI Key通常存储在一个环境变量中（如 CLAUDE_API_KEY 或 OPENAI_API_KEY），ccpm的脚本会读取这些变量调用AI。这是AI Agent的核心能力来源。请务必妥善保管你的API Key，切勿直接提交到GitHub仓库中。
带来的价值： /pm:init 一步到位地为你配置了ccpm的运行环境，解决了GitHub工具链的依赖问题，并建立了项目管理的基础文件结构，让你能快速进入AI辅助开发的轨道。

B. 创建CLAUDE.md（项目AI协作核心说明）

CLAUDE.md 是你项目与AI Agent协作的“宪法”。它定义了AI Agent的行为规范、项目风格、技术栈偏好，以及通用开发逻辑。虽然 /pm:init 可能不会直接生成此文件，但你应该手动创建它，并使用 /init include rules from .claude/CLAUDE.md 命令将其内容“注入”到AI的初始上下文。

建议在 .claude/ 目录下创建一个 CLAUDE.md 文件。

CLAUDE.md 示例内容：

# 项目协作指南## 1. 项目概览
- **项目名称:** [你的项目名称]
- **项目目标:** [简述项目最终目的]
- **产品类型:** [例如：Web应用, 移动App, API服务, 库/框架]## 2. 技术栈与编码规范
- **前端:** [例如：React, Next.js, TypeScript, TailwindCSS]
- **后端:** [例如：Node.js, Express, Python, Django, FastAPI]
- **数据库:** [例如：PostgreSQL, MongoDB, Redis]
- **云平台:** [例如：AWS, GCP, Azure]
- **编码风格:** [例如：遵循ESLint/Prettier规则, Python PEP 8]
- **测试框架:** [例如：Jest, React Testing Library, Pytest]
- **文档规范:** [例如：JSDoc for JS, Sphinx for Python]## 3. 协作流程与提交规范
- **分支策略:** [例如：GitFlow, GitHub Flow]
- **Commit Message:** [例如：Conventional Commits规范]
- **PRD与Issue:** 所有开发必须追溯到PRD，并通过Issue进行管理。
- **Pull Request:** 提交前确保通过所有测试，代码整洁，附带清晰的描述和Issue链接。## 4. AI Agent行为规范
- **角色设定:** 你是一名资深全栈工程师，擅长[项目技术栈]。
- **沟通风格:** 简洁、专业，提供清晰的解释和技术方案。
- **决策原则:** 在不确定时，优先寻求人类确认；在可能引入复杂性时，优先选择简洁、成熟的解决方案。
- **输出期望:**- 提供可直接运行的代码片段或文件。- 补充必要的思考过程、技术选型理由和潜在风险。- 遵守编码规范。- 每次输出后，请总结当前进展和下一步计划。## 5. 其他重要说明
- [例如：对性能、安全性、可维护性的特殊要求]
- [例如：与其他外部系统的集成方式]

何时使用 /init include rules from .claude/CLAUDE.md：
这个命令并非一个ccpm的内置命令，而是一个提示AI将你的CLAUDE.md内容载入其工作上下文的指令。你会在首次与AI互动时（例如 /pm:prd-new 或 /pm:epic-decompose 之后）手动输入这个指令，或者在后续的AI提示中提醒AI参考该文件。这个指令并非直接执行一个ccpm内部操作，而是通过AI的指令响应机制，确保AI从一开始就了解并遵循你的项目规则。
带来的价值： CLAUDE.md 确保了AI Agent在项目开始阶段就具备了与项目高度相关的“知识”和“规范”，避免了AI生成不符合项目风格或技术栈的代码和方案，是实现高效AI协作的基础。

C. 初始化项目上下文：`/context:create`

随着项目的推进，会积累大量的文档、讨论和代码，这些构成了项目的“知识库”。/context:create 命令旨在帮助你生成一个项目的全局上下文文档，便于AI Agent和团队成员持久理解项目的全貌。

/context:create

执行步骤与详细解释：
- ccpm会引导你收集项目的基本信息，例如项目名称、简要描述、主要技术栈、当前阶段、核心功能列表等。
- 它可能还会自动扫描 .claude/prds/ 目录下的所有PRD文件，以及 .claude/epics/ 目录下的 epic.md 文件，将其中关键信息提炼出来。
- 最终，ccpm会在 .claude/context/ 目录下生成一个 project_context.md 或类似名称的文档。

project_context.md 示例（AI自动生成或人工补充）：

# 项目全局上下文：智能聊天机器人 (Chatbot)## 1. 项目基本信息
- **项目名称:** 智能聊天机器人 (Chatbot)
- **项目目标:** 构建一个支持多轮对话、上下文记忆和插件扩展的通用聊天机器人平台，提升用户互动体验。
- **当前阶段:** MVP开发阶段，已完成基础结构搭建，正在进行核心功能模块开发。## 2. 核心功能概览
- **NLP模块:** 用户意图识别、实体抽取、多轮对话管理。
- **上下文记忆:** 基于用户ID和会话ID存储对话历史。
- **插件系统:** 支持动态加载外部工具或API。
- **用户界面:** Web端聊天界面，集成聊天窗口、历史记录。
- **认证与授权:** 用户注册/登录，会话管理。## 3. 技术栈
- **后端:** Python (FastAPI), Asyncio, Redis (for session/context cache)
- **NLP:** Hugging Face Transformers (Sentence Transformers), SpaCy
- **前端:** React, TypeScript, Chakra UI
- **数据库:** PostgreSQL (for user/plugin data)
- **部署:** Docker, Kubernetes (暂定，MVP阶段可能使用简单VM)
- **版本控制:** Git, GitHub## 4. 关键Epic与进展
- **Epic: 用户身份认证与会话管理 (完成 80%)**- Task: 用户注册 API (完成)- Task: 用户登录 API (完成)- Task: JWT令牌生成与验证 (完成)- Task: 会话刷新机制 (进行中)
- **Epic: 基础对话理解 (完成 50%)**- Task: 意图识别模型集成 (完成)- Task: 实体抽取逻辑 (进行中)- Task: 基础回复生成 (未开始)
- ... (更多Epic及进展)## 5. 关键依赖与风险
- **外部依赖:** AI模型API (OpenAI/Anthropic) 稳定性。
- **内部依赖:** 插件系统设计高度依赖NLP模块的输出。
- **潜在风险:** NLP模型在复杂语境下的准确率可能不足；插件扩展的安全性问题。## 6. 其它重要信息
- 编码规范请参考 `.claude/CLAUDE.md`。
- 预计MVP发布时间：[日期]

带来的价值： /context:create 创建的全局上下文文档是项目中所有AI Agent和人工开发者共享的“项目记忆”。它确保了所有参与者都能对项目的目标、进展和技术细节保持一致的理解，减少了重复提问和上下文切换的开销，是保障高效协作和AI智能化的重要基石。建议定期使用 /pm:context-update 更新此文档，确保其新鲜度。

2.3 基本命令与目录结构：ccpm的语言和骨架

了解ccpm的目录结构和常用命令框架，是掌握其工作原理和高效操作的基础。

A. 主要目录结构

cd path/to/your/project 后，你的项目根目录下会出现一个 .claude/ 隐藏文件夹，这是ccpm的所有配置、文档和辅助脚本的存储位置。

/your-project/
├── .claude/
│   ├── context/         # 存储项目的全局上下文文档 (project_context.md)。这是AI理解项目全貌的基础。
│   ├── prds/            # 存储所有产品需求文档（PRD）。每个PRD对应一个MarkDown文件，是需求的单一真相来源。
│   ├── epics/           # 存储Epic（史诗）及其分解后的具体任务文件。每个Epic拥有一个子目录。
│   │   └── [epic_name]/ # 某个Epic的专属目录，例如 `memory-system/`
│   │       ├── epic.md  # 详细描述该Epic的实现方案、架构设计、技术选型和子任务概览。
│   │       ├── [task_1].md # 该Epic下的一个具体任务描述文件，定义任务目标和交付物。
│   │       └── [task_2].md # 另一个任务描述文件。
│   ├── agents/          # 存放可自定义的AI Agent配置或脚本。你可以根据项目需求定义不同角色的Agent。
│   ├── commands/        # 定义ccpm的各类核心命令脚本。你可以通过修改或添加脚本来扩展ccpm的功能。
│   ├── scripts/         # 存放辅助性脚本，例如数据处理、代码生成辅助等。
│   └── ccpm.sh          # ccpm的核心启动脚本和命令别名定义。
├── .gitignore           # 项目的Git忽略文件，由ccpm自动添加必要规则。
├── your-code-files/     # 你的实际项目代码文件。
└── ...

解释与功能模块对应：
- .claude/prds/：产品管理模块，需求输入。
- .claude/epics/：任务分解与计划模块，需求转化为可执行任务。
- .claude/context/：知识库模块，AI与团队的共享项目知识。
- .claude/agents/ 和 .claude/commands/：自定义与自动化模块，ccpm的扩展性核心。

B. 常用命令框架：与ccpm对话的语言

ccpm的所有命令都以 /pm: 作为前缀，方便识别和调用。以下是日常使用中，你将频繁接触的核心命令：

/pm:prd-new <功能名>：新建产品需求文档（PRD）
- 作用： 启动一个新的产品功能开发流程，会引导你创建对应的PRD文件。
- 示例： /pm:prd-new user-authentication 将在 .claude/prds/ 下创建 user-authentication.md。
/pm:prd-parse <功能名>：PRD解析为Epic实施计划
- 作用： AI Agent会根据指定的PRD内容，生成一个高层次的Epic实施计划。
- 示例： /pm:prd-parse user-authentication 会在 .claude/epics/user-authentication/ 目录下生成 epic.md。
/pm:epic-decompose <功能名>：Epic分解为具体任务
- 作用： AI Agent会进一步将Epic分解为更小、更具体的开发任务，每个任务对应一个Markdown文件。
- 示例： /pm:epic-decompose user-authentication 将分解 user-authentication Epic下的任务，生成多个 task_*.md 文件。
/pm:epic-oneshot <功能名>：一键分解Epic并同步到GitHub Issue
- 作用： 整合了 /pm:epic-decompose 和 GitHub 同步的流程，一步到位地完成任务分解并在GitHub上创建Issue及子任务关系。
- 示例： /pm:epic-oneshot user-authentication。
/pm:issue-start <任务号>：为某个任务启动AI Agent进行开发
- 作用： 指定一个GitHub Issue编号，AI Agent将开始理解任务上下文，并尝试生成代码、提供方案。
- 示例： /pm:issue-start 123 （其中123是GitHub Issue的ID）。
/pm:issue-sync <任务号>：同步任务进度到GitHub
- 作用： 将AI Agent或人工开发者在本地的开发进展（如代码文件、日志、讨论）同步到对应的GitHub Issue评论区。
- 示例： /pm:issue-sync 123。
/pm:next：推荐下一个优先任务
- 作用： AI Agent会根据当前项目的全局进度、任务依赖、阻塞情况等，智能推荐一个优先级最高的未开始或被阻塞的任务。
- 示例： /pm:next。
/pm:status：查看项目全貌与进展
- 作用： 提供项目当前状态的概览，包括Epic、任务、进度、阻塞项等。
/pm:standup：生成日报
- 作用： AI Agent根据项目最新进展、完成任务、进行中任务和遇到的阻塞，自动生成一份团队日报。
/pm:context-update：更新全局上下文
- 作用： 重新生成或更新项目的 project_context.md 文件，确保AI Agent具有最新的项目知识。
/pm:blocked <任务号> <阻塞原因>：标记任务为阻塞状态
- 作用： 将指定任务标记为阻塞状态，并记录阻塞原因，有助于团队及时发现并解决问题。
- 示例： /pm:blocked 123 "等待后端API接口"。

这些命令构成了ccpm的核心交互语言，通过它们，你可以指挥AI Agent、管理项目流程、追踪任务进度，并与团队高效协作。

3. 核心工作流详解：PRD驱动到GitHub同步

Claude Code PM 的核心价值在于其端到端的工作流，它将产品需求（PRD）的构思、技术方案的制定，再到具体的任务分解和 GitHub Issue 的同步，都纳入了一个流畅、智能化的管理体系中。本节将详细拆解这一核心工作流。

3.1 PRD驱动开发流程：从愿景到可执行计划

PRD驱动是ccpm的核心，它通过PRD的撰写、解析和分解，确保每一个开发任务都紧密围绕产品需求展开。

需求头脑风暴与PRD撰写：/pm:prd-new <功能名>
所有开发活动的起点，皆源于对用户需求和产品功能的细致定义。

/pm:prd-new memory-system

输出： ccpm 会在 .claude/prds/ 目录下生成一个名为 memory-system.md 的Markdown文件。这个文件是你的“原始PRD模板”。
操作： 你需要人工编辑并完善这个Markdown文件，详细填写产品的愿景、目标用户、用户故事、核心功能点、非功能性需求（性能、安全）、以及清晰的验收标准。这一步是确保需求准确、清晰的关键，AI的后续工作质量很大程度上取决于PRD的质量。

示例 memory-system.md 内容（人工补充后）：

# PRD: 上下文记忆系统## 1. 愿景
构建一个高效、可扩展的上下文记忆系统，使得聊天机器人/AI助手能够在多轮对话中保持对用户意图、偏好和对话历史的长期记忆，从而提供更连贯、智能的互动体验。## 2. 目标用户
- AI助手用户：期望获得个性化、连贯对话体验的用户。
- 开发者：希望通过简单API集成记忆功能到其AI应用中的开发者。## 3. 用户故事 (User Stories)
- AS A 用户, I WANT 助手能记住我在上次对话中提到的偏好 (e.g., “我喜欢日料”), SO THAT 它下次推荐时能直接考虑。
- AS A 用户, I WANT 助手能理解我正在谈论的某个实体 (e.g., “上次我问的那个餐厅”), SO THAT 我不需要重复提及完整名称。
- AS A 开发者, I WANT 简洁的API接口来存取用户对话的结构化与非结构化记忆。## 4. 核心功能
- **4.1 长期记忆存储:**- 存储用户偏好、重要实体、关键信息。- 持久化存储，支持跨会话记忆。
- **4.2 短期记忆（会话上下文）管理:**- 存储当前会话的最近N轮对话。- 支持话题切换与保留。
- **4.3 记忆检索与注入:**- 在新对话开始时，能够根据用户ID检索并注入相关长期记忆。- 能够从当前会话中抽取关键信息，更新短期记忆。- 能够根据历史对话，动态生成意图理解所需的上下文。
- **4.4 API接口:**- RESTful API，用于存储、检索、更新记忆。- 支持用户认证与授权。## 5. 非功能性需求
- **性能:** 记忆检索延迟 < 100ms；存储容量支持千万级用户。
- **安全性:** 记忆数据加密存储与传输；API访问鉴权。
- **可扩展性:** 支持未来接入更多AI模型和数据源。
- **可靠性:** 99.9%的服务可用性。## 6. 验收标准
- 机器人可以在3轮对话后，记住用户明确表达的3个偏好。
- 机器人可以在新会话中，引用上次会话中用户提及的一个关键实体。
- API接口文档完善，并提供示例。
- 已集成单元测试和集成测试，覆盖率 > 80%。

PRD解析为Epic实施计划：/pm:prd-parse <功能名>
一旦PRD撰写完成，AI Agent将介入，将其转化为一个更高层次、偏向技术实现的Epic实施计划。

/pm:prd-parse memory-system

输出： ccpm 会在 .claude/epics/memory-system/ 目录下生成一个 epic.md 文件。
操作： AI会初步填充Epic的通用信息、技术方案初稿、架构设计设想和潜在的技术依赖等。你需要作为人类项目经理，审阅并进一步补充或修正这些技术细节，例如决定具体的数据库选型、缓存策略、消息队列使用等。这一步是将产品需求落实到技术实现路径的关键。

示例 epic.md 内容（AI生成后人工补充）：

# Epic: 上下文记忆系统实现计划## 1. Epic 目标
基于 `memory-system.md` PRD，设计并实现一个支持长期记忆和会话上下文管理的后端服务，提供API供机器人调用。## 2. 技术选型
- **后端框架:** Python FastAPI (高性能、异步支持)
- **长期记忆存储:** PostgreSQL (结构化数据存储，支持复杂查询)
- **短期记忆/会话缓存:** Redis (高并发、低延迟键值存储)
- **OR/M:** SQLAlchemy (简化数据库交互)
- **认证:** JWT (Jason Web Token，用于API鉴权)
- **容器化:** Docker
- **其他工具:** Pydantic (数据校验), Uvicorn (ASGI服务器)## 3. 架构设计 (概念图)

*   **FastAPI Service:** 负责处理所有记忆相关的API请求。
*   **Redis Cache:** 存储短期会话上下文（例如最近N轮对话）。
*   **PostgreSQL DB:** 存储用户长期偏好、关键实体等结构化记忆。
*   **Plugin Integration Layer:** (未来扩展) 用于记忆与外部系统/插件的交互。## 4. 接口设计 (示例)
- `POST /memory/store_long_term`: 存储长期记忆
- `GET /memory/retrieve_long_term/{user_id}`: 检索长期记忆
- `POST /context/update_session/{session_id}`: 更新会话上下文
- `GET /context/get_session/{session_id}`: 获取会话上下文## 5. 依赖关系
- **外部依赖:** 需要一个可用的PostgreSQL和Redis实例。
- **内部依赖:** 需等待用户认证服务（JWT生成）就绪。## 6. 风险评估
- **性能风险:** 大规模并发记忆检索可能瓶颈，需进行性能测试。
- **数据安全:** 敏感记忆的加密与访问控制。
- **数据一致性:** Redis与PostgreSQL之间的数据同步策略。## 7. 验收标准 (与PRD呼应)
- 所有API接口均通过Postman/Swagger测试。
- 长期记忆和短期记忆功能按预期工作。
- 完成性能基准测试。
- 安全性评估通过。

Epic分解为独立任务：/pm:epic-decompose <功能名>
在Epic实施计划确定后，AI Agent将进行更细致的任务分解。它将把一个大的Epic拆解成多个相互独立、粒度适中、可并行执行的开发任务（Task）。
```
/pm:epic-decompose memory-system
```
- 输出： ccpm 会在 .claude/epics/memory-system/ 目录下生成多个 task_*.md 文件，例如 task_setup_fastapi_project.md, task_implement_long_term_memory_api.md 等。每个文件都是一个独立的任务描述。
- 操作： 你需要审阅这些任务文件，可以根据需要进行调整，例如合并或拆分任务、修改任务描述、添加详细的技术指导或引用代码库。每个任务都应是可独立交付的最小工作单元。
同步到GitHub Issue：/pm:epic-oneshot <功能名>
这是将本地需求和计划转化为GitHub可见、可管理的任务的核心步骤。
```
/pm:epic-oneshot memory-system
```
- 操作： ccpm 会自动执行以下操作：
  - 在GitHub仓库中创建一个名为“Epic: 上下文记忆系统实现计划”的父级Issue。这个Issue会包含 .claude/epics/memory-system/epic.md 中的内容。
  - 为 .claude/epics/memory-system/ 目录下每个 task_*.md 文件创建一个子级Issue。这些子级Issue会自动关联到父级Epic Issue，形成清晰的父子关系。
  - 为子任务Issue添加适当的标签（如 todo, enhancement）。
- 带来的价值： 一键完成从本地文档到GitHub Issue的转换，极大地节省了手动创建和管理大量Issue的时间。GitHub的父子Issue关系（通过 gh-sub-issue 扩展实现）使得Epic和Task的层级一目了然，方便团队按层次追踪。至此，整个开发团队，无论是人工还是AI Agent，都可以在GitHub上看到明确的任务清单和层级结构。

3.2 任务执行与并行开发：AI与人工的协同

在GitHub Issue列表已经构建完成之后，团队成员和AI Agent就可以认领并执行各自的任务了。ccpm支持多Agent并行开发，最大化项目推进速度。

AI Agent 接手任务：/pm:issue-start <任务号>
当一个任务被分配给AI Agent时，这个命令会启动Agent，让它开始理解任务并着手开发。
```
/pm:issue-start 1234 # 假设1234是“Task: Setup FastAPI Project”的GitHub Issue ID
```
- 操作：
  - AI Agent会读取对应GitHub Issue中的详细描述，理解任务目标、验收标准。
  - 它还会加载项目的全局上下文 (.claude/context/project_context.md) 和AI协作规范 (.claude/CLAUDE.md)，确保其开发符合项目整体要求。
  - AI Agent会在本地的工作区开始生成代码、配置文件、提供技术方案等。
  - 首次启动可能还会自动在Issue下生成一个“AI Agent开始工作”的评论。
- 带来的价值： 自动化任务执行，AI Agent能够基于上下文进行智能开发，将开发任务从概念转化为实际代码。
人工开发者认领并执行：
人工开发者可以直接在GitHub上认领Issue，并在本地开发。ccpm的命令行工具也能辅助人工开发者：
- /pm:issue-pull <任务号>： 拉取最新Issue信息到本地，刷新本地上下文。
- /pm:issue-comment <任务号> <内容>： 从命令行快速给Issue添加评论。
- /pm:issue-log <任务号>： 查看某个Issue的本地开发日志，了解AI或自己的开发历史。
任务并行与多Agent协同：
ccpm天生支持多个任务同时进行。
- 多个人工开发者： 可以同时认领并开发不同的子任务。
- 多个AI Agent： 你可以同时启动多个AI Agent来处理不同的Task Issue。每个Agent会保持自己独立的上下文和工作进程，互不干扰，从而实现真正的并行开发。例如：
```
/pm:issue-start 1234 # AI Agent A 开发后端API
/pm:issue-start 1235 # AI Agent B 开发前端UI
```
- 人工与AI混合协作： 这是ccpm的理想状态。人工开发者负责复杂的设计、架构与决策，AI Agent负责实现标准模块、编写测试、生成辅助代码，相互协作，最大化团队的开发吞吐量。

3.3 上下文与进度管理：掌握项目脉搏

在并行开发的过程中，保持项目上下文的更新和进度的透明是至关重要的。ccpm提供了一系列命令来帮助你掌握项目的最新脉搏。

更新全局上下文：/context:update
项目的上下文不是静态的，会随着PRD的修订、Epic的完成、任务的进展而不断变化。
```
/context:update
```
- 操作： 这个命令会重新读取所有PRD、Epic和已完成的任务信息，自动更新 .claude/context/project_context.md 文件。
- 带来的价值： 确保AI Agent和团队成员始终具备最新的项目全貌，避免因信息滞后导致的开发偏差。建议在关键里程碑或重要信息变更后，定期执行此命令。
同步本地开发进展到GitHub：/pm:issue-sync <任务号>
这是实现开发透明化的关键。无论是AI Agent还是人工开发者，都应该频繁地将工作进展同步到GitHub Issue。
```
/pm:issue-sync 1234
```
- 操作： ccpm会将本地关于该任务的最新开发日志、重要的代码片段、遇到的问题或解决方案，以及AI Agent的思考过程，自动作为评论添加到GitHub上对应的Issue中。
- 带来的价值：
  - 增强透明度： 所有团队成员（甚至外部协作方）都能实时了解任务的最新进展，无需额外沟通。
  - 上下文留痕： Issue的评论区成为该任务的完整开发日志，方便未来的追溯和复盘。
  - AI互动： AI Agent会将其生成的代码和思考过程同步到Issue，供人工开发者审阅和指导。
- 最佳实践： 建议每次完成一个小阶段的工作、生成重要代码或遇到问题时，都及时运行 /pm:issue-sync。
查看项目全貌与进展：/pm:status、/pm:epic-show <功能名>、/pm:in-progress
这些命令提供了不同粒度的项目状态视图。
- /pm:status：
  - 作用： 提供整个项目的概览，包括所有Epic的列表、它们的整体进度百分比、进行中和已完成任务的数量，以及任何被标记为阻塞的项。
  - 带来的价值： 帮助项目经理和团队成员快速掌握全局，识别高风险区域或瓶颈。
- /pm:epic-show <功能名>：
  - 作用： 展示特定Epic的详细信息，包括其下的所有子任务、每个子任务的状态（待办、进行中、已完成、阻塞）、负责人、以及与GitHub Issue的链接。
  - 示例： /pm:epic-show memory-system
  - 带来的价值： 深入了解单个Epic的进展及所有构成任务，便于聚焦管理。
- /pm:in-progress：
  - 作用： 列出所有当前处于“进行中”状态的任务，包括人工和AI Agent正在处理的任务，通常会显示任务的简要描述和Issue ID。
  - 带来的价值： 快速了解团队当前的活跃工作负载，便于协调资源。
日报生成：/pm:standup
简化团队的每日站会（Daily Standup）流程。
```
/pm:standup
```
- 作用： AI Agent会根据GitHub Issue的最新状态（如昨日完成的任务、今日计划处理的任务、遇到的阻塞）、结合本地的开发日志，自动生成一份格式化的日报。
- 带来的价值： 大幅减少人工撰写日报的时间，确保日报内容基于真实的项目数据，提升团队沟通效率。
发现阻塞项：/pm:blocked
快速识别项目中的瓶颈，确保问题能被及时发现和解决。当一个任务依赖于另一个外部条件，例如等待某个API接口、某个设计稿、或者其他团队的交付时，就可以将其标记为阻塞。
```
/pm:blocked
```
- 操作： 这个命令会列出所有当前被标记为“阻塞（Blocked）”状态的任务，并显示其阻塞原因和负责人。
- 带来的价值： 帮助团队迅速聚焦需要关注和解决的关键问题，避免不必要的等待和延误。

4. 日常使用实践：高效开发与协作

掌握了ccpm的核心工作流和基础命令后，本节将通过典型的开发流程演练，展示如何在日常工作中高效地运用ccpm，实现多人/多AI并行开发，并有效追踪和排查问题。

4.1 典型开发流程演练：一步步构建功能

以下是一个功能开发的完整生命周期，演示了ccpm各命令如何串联工作：

构思与需求定义：
你有一个新的功能想法——“推理引擎”。
```
/pm:prd-new 推理引擎
```
- 操作： ccpm生成 .claude/prds/推理引擎.md。
- 人工任务： 你会打开这个文件，详细补充推理引擎的愿景、用户故事、核心功能、性能要求和验收标准等。这是你与产品经理（如果你就是产品经理）的沟通结果，是后续一切开发的基石。
技术方案与Epic规划：
根据完善的PRD，你需要规划技术实现方案。
```
/pm:prd-parse 推理引擎
```
- 操作： ccpm（由AI辅助）会读取 .claude/prds/推理引擎.md，并在 .claude/epics/推理引擎/ 下生成 epic.md。这个文件包含了AI初步设想的技术栈、架构草图、主要模块划分等。
- 人工任务： 你会审阅并完善 epic.md。你可能会对技术选型做出最终决定，绘制更详细的架构图，或补充具体的接口设计草案。
任务分解与GitHub同步：
有了详细的Epic规划，现在是时候将其分解成可执行的任务并同步到GitHub了。
```
/pm:epic-oneshot 推理引擎
```
- 操作： ccpm会自动将Epic分解为多个独立的子任务（Task），在本地生成各自的Markdown文件。然后，它会连接GitHub，创建一个父级Issue（对应Epic），并为每个子任务创建子级Issue，建立清晰的父子关系。
- 人工任务： 你可以检查GitHub Issue列表，确保任务分解合理，并根据需要分配负责人（可以是人工开发者，也可以是特定的AI Agent）。
AI Agent开始开发：
现在，你可以启动AI Agent来处理其中一个或多个子任务了。假设“1234”是“推理引擎构建”Epic下的一个具体任务ID（例如，“实现核心推理逻辑”）。
```
/pm:issue-start 1234
```
- 操作： AI Agent会开始分析GitHub上的Issue #1234，理解任务要求和整个项目的上下文，然后在本地生成代码或设计方案。AI会在本地创建工作目录，并在这里进行思考和输出。
- 人工任务： 你可以切换到其他任务，或进行代码审查、架构设计等更高价值的工作。
开发中：持续同步进度：
当AI Agent在本地完成阶段性工作，或者你在本地进行了修改并希望AI继续接管时，都需要同步进度。
```
/pm:issue-sync 1234
```
- 操作： ccpm会将本地AI Agent生成的代码、日志、思考过程或你的人工修改，作为评论同步到GitHub Issue #1234中。这使得团队成员可以随时查看AI的最新工作和你的反馈。
- 人工任务： 持续审查AI生成的代码，提供反馈意见，甚至直接修改代码，然后再次运行 /pm:issue-sync 将你的修改和指示同步给AI。ccpm旨在构建一种“人教AI，AI协作人”的互动模式。

通过反复执行上述步骤，你和你的团队可以高效地从需求构思，到技术实现，再到具体的代码开发和进度追踪，完成一整个功能的构建。

4.2 多人/多AI并行开发：加速项目进展

ccpm 的设计理念之一就是最大化并行度。它支持多个人工开发者与多个AI Agent在同一项目内无缝协同，共同推进任务。

独立的上下文与工作区：
- 每个GitHub Issue都代表一个独立的任务上下文。无论是人工开发者还是AI Agent，在处理一个Issue时，都会聚焦于该Issue的描述、评论及其关联的代码，避免相互干扰。
- AI Agent在 /pm:issue-start 时会为其创建独立的临时工作目录，确保其工作环境的隔离。
Epic与Issue的父子结构保证全程溯源与分工明确：
- 通过 gh-sub-issue 扩展，ccpm 在GitHub上建立了Epic与子任务Issue之间的层级关系。
- 这使得团队可以清晰地看到整个项目的宏观分解（Epic），以及每个Epic下有多少具体的任务正在进行或已完成。
- 即使有多个AI Agent和人工开发者并行处理任务，也能通过这些层级关系，轻松追溯每个任务属于哪个大功能，以及它当前所处的状态。这极大地简化了项目经理的工作，也让团队成员对项目的整体结构有更清晰的认识。

实战场景：
假设你的“推理引擎”Epic分解为：

#1234: 实现核心推理逻辑（由AI Agent A开发）
#1235: 构建推理API接口（由人工开发者开发）
#1236: 设计推理结果可视化UI（由AI Agent B开发）
#1237: 编写单元测试（由人工开发者开发）

你可以同时启动：

/pm:issue-start 1234
/pm:issue-start 1236

同时，人工开发者可以分别认领 #1235 和 #1237。每个参与者都在独立的任务上下文中工作，并通过 /pm:issue-sync 将进展同步到GitHub，实现了最大化的并行效率。

4.3 进度跟踪与问题排查：实时掌握项目状况

在并行开发和AI辅助的流程中，实时、准确地掌握项目进度和快速排查问题至关重要。ccpm提供了一系列工具来帮助你完成这些任务。

快速定位进展：多维度视图
- /pm:status： 最直观的宏观视图。它会输出所有Epic的整体进度、进行中任务、待办任务和阻塞任务的汇总信息。通过这个命令，你可以一眼看出项目的整体健康状况。
- /pm:epic-show <Epic名>： 深入了解单个Epic的详细进度。它会列出该Epic下所有子任务的ID、标题、状态和负责人，以及任务在GitHub上的链接。
```
/pm:epic-show 推理引擎
# 查看推理引擎Epic下的所有任务详情
```
- /pm:in-progress： 聚焦当前活跃的工作流。它会列出所有处于“进行中”状态的任务，包括AI Agent和人工开发者正在处理的任务。
- gh issue list / gh issue view： 结合GitHub CLI，你可以直接在命令行查看GitHub Issue的详细信息，包括评论区的讨论、代码片段和文件更新。
发现与管理阻塞：/pm:blocked 与 AI提醒
- /pm:blocked： 如前所述，这是一个高效发现项目瓶颈的命令。
```
/pm:blocked
# 列出所有被标记为阻塞的任务
```
- AI自动提醒： 当一个AI Agent在执行任务过程中识别到其依赖的其他任务未完成，或者外部资源不可用时，它可能会通过/pm:issue-sync在Issue评论区自动报告阻塞，并建议你使用/pm:blocked来正式标记。
- 人工处理： 一旦发现阻塞项，人工项目经理或相关负责人可以及时介入，协调资源、解决依赖，或调整任务优先级。
gh issue 命令结合使用，GitHub侧实时可见：
ccpm 与 gh CLI 的深度集成，意味着所有ccpm的操作（创建Issue、添加评论、更新状态）都会实时反映在GitHub上。
- 浏览器查看： 你可以随时打开GitHub仓库的Issues页面，以可视化的方式查看所有Epic和Task的层级关系、状态、讨论和代码关联。
- gh issue view <issue_id>： 在命令行查看任何Issue的完整内容和评论。
- gh issue close <issue_id>： 当一个任务彻底完成后，你可以直接在gh CLI中关闭对应的Issue，或者让AI Agent在完成任务后自动关闭。

通过这些功能，团队可以实时掌握项目状况，及时发现并解决问题，确保项目按计划高效推进。

5. 高级用法与自动化：多Agent协同与系统集成

Claude Code PM 不仅提供基础的项目管理功能，更通过其高度的可扩展性和自动化能力，为高级用户和组织提供了定制化、智能化的开发体验。本节将深入探讨多Agent协同、自定义Agent与命令扩展，以及跨项目复用等高级用法。

5.1 多Agent协同与并行流：打造智能开发流水线

ccpm 允许你启动多个AI Agent，每个Agent拥有独立的上下文和任务，从而能够并行处理复杂的开发流程，实现真正的“分层开发”和“流水线作业”。

一个Epic拆解为多个并行Agent：各司其职
- 核心理念： 对于一个庞大的Epic，在 pm:epic-decompose 之后会生成多个TaskList。你可以将这些不同的Task分配给不同配置或侧重点的AI Agent。
- 实战场景：
```
# 假设 Epic "用户认证系统" 分解出以下任务
# #1001: 设计数据库Schema（DBA Agent）
# #1002: 实现认证API后端（Backend Agent）
# #1003: 开发前端登录UI（Frontend Agent）
# #1004: 编写API集成测试（QA Agent）# 启动 DBA 属性的 Agent
/pm:issue-start 1001 --agent=dba_agent# 启动 Backend 属性的 Agent
/pm:issue-start 1002 --agent=backend_agent# 启动 Frontend 属性的 Agent
/pm:issue-start 1003 --agent=frontend_agent# 启动 QA 属性的 Agent
/pm:issue-start 1004 --agent=qa_agent
```
- 带来的价值：
  - 专业化开发： 每个Agent专注于其擅长的领域，例如一个Agent专门负责数据库设计，另一个负责前端UI，确保代码质量和专业度。
  - 并行加速： 多个Agent同时工作，极大缩短了整体开发周期。
  - 职责分离： 清晰地划分了AI Agent的职责，便于问题排查和管理。
“分层开发”——数据库、API、UI、测试Agent同步推进：
- 核心理念： 这是多Agent协同的典型应用。不同的技术栈层级（如数据层、业务逻辑层API、用户界面层、测试层）可以同步进行开发。
- 详细流程：
  1. AI DBA Agent： 接收“设计数据库Schema”Task，生成SQL或ORM模型代码。
  2. AI Backend Agent： 接收“实现认证API后端”Task，依赖DBA Agent的Schema，生成API接口代码。
  3. AI Frontend Agent： 接收“开发前端登录UI”Task，依赖Backend Agent的API接口文档，生成React/Vue组件。
  4. AI QA Agent： 接收“编写API集成测试”Task，依赖Backend Agent的API接口，生成测试用例。
- 交互机制： Agent之间往往通过GitHub Issue评论区进行“沟通”。例如，Backend Agent在完成API实现后，会在Issue #1002中同步其API文档，这成为Frontend Agent和QA Agent启动工作的输入。
- 带来的价值： 这种分层开发模式将复杂度分解，同时保持不同层级开发的并行性，最大化AI辅助的效率。它类似于一个高度自动化的微服务开发团队。

5.2 自定义Agent与命令扩展：打造你的专属AI开发助手

ccpm 鼓励用户根据自身项目和团队的特定需求，深度定制 AI Agent 的行为并扩展 ccpm 的命令功能。

自定义 .claude/agents/ 下的Agent脚本：定义AI角色与能力
- 核心理念： 每个AI Agent的核心行为逻辑都由 .claude/agents/ 目录下的脚本定义。你可以创建多个不同的Agent脚本，每个脚本可以设定不同的“角色”（Prompt）、技术偏好、代码生成风格和思考过程。
- 自定义步骤：
  1. 复制现有Agent模板： 从 .claude/agents/ 目录中复制一个现有的agent脚本作为起点。
  2. 修改Prompt： 最关键的是修改Agent脚本中的初始Prompt。这个Prompt定义了AI Agent遇到任务时的“思维模式”和“角色设定”。
```
# 示例：自定义一个专门处理前端的 Agent
# .claude/agents/frontend_agent.sh
# ...
INITIAL_PROMPT="你是一名资深的React和TailwindCSS前端工程师，精通响应式设计和组件化开发。你的任务是根据给定的PRD和API文档实现前端UI。请优先使用TypeScript编写代码，并遵循原子设计原则。每次输出请提供具体的JSX/TSX代码和CSS/Tailwind类，并解释设计思路。"
# ...
```
  3. 调整工具链与输出格式： 你还可以调整Agent的辅助工具（例如，让它优先调用某个代码格式化工具）和输出格式。
- 带来的价值： 强大的灵活性，让你的AI Agent不再是通用的聊天机器人，而是具备特定专业知识和编码风格的“虚拟团队成员”，能更好地融入你的项目。
.claude/commands/ 可添加自定义流程命令：扩展ccpm的功能集
- 核心理念： ccpm 的所有 /pm: 命令实际上都是 .claude/commands/ 目录下的Bash脚本。这意味着你可以通过编写自己的Bash脚本来扩展ccpm的功能。
- 自定义步骤：
  1. 创建新的脚本文件： 在 .claude/commands/ 目录下创建一个新的Bash脚本，例如 my-custom-command.sh。
  2. 编写脚本逻辑： 在脚本中编写你想要执行的逻辑。你可以调用 gh CLI、Git命令、或者其他辅助脚本。
  3. 定义命令： 确保你的脚本是可执行的 (chmod +x my-custom-command.sh)。这样你就可以通过 /pm:my-custom-command 来调用它了。
- 示例：创建一个 /pm:deploy-staging 命令
```
#!/bin/bash
# File: .claude/commands/deploy-staging.shecho "🚀 Starting staging deployment..."# 1. 确保所有修改已提交
if ! git diff-index --quiet HEAD --; thenecho "Error: Uncommitted changes detected. Please commit or stash your changes first."exit 1
fi# 2. 切换到部署分支（假设为 staging）
git checkout staging
if [ $? -ne 0 ]; thenecho "Error: Failed to checkout staging branch. Does it exist?"exit 1
fi# 3. 拉取最新代码
git pull origin staging# 4. 执行部署脚本（这里只是一个占位符）
echo "Executing actual deployment scripts (e.g., calling CI/CD pipeline, running Ansible/Terraform)..."
# /usr/local/bin/your_ci_cd_trigger_script --branch=staging --project=$PROJECT_NAME
# docker-compose -f docker-compose.staging.yml up -d --buildecho "✅ Staging deployment triggered successfully!"
git checkout - # 返回之前的分支
```
- 带来的价值： 极大的灵活性，让ccpm不仅仅是项目管理工具，更是你的专属自动化工作流平台。你可以将任何重复性的开发、运维、报告生成等任务，封装成自定义命令。
高级用法：与CI/CD、ChatOps集成，实现自动化审查、测试、部署：
通过自定义命令和Agent，ccpm可以深度集成到你现有的DevOps工具链中。
- CI/CD触发： 自定义命令可以在代码提交、Issue状态变更时，自动触发CI/CD流水线。例如，/pm:deploy-staging 命令可以调用Jenkins或GitHub Actions触发器。
- ChatOps集成： 将ccpm命令暴露给团队的聊天工具（如Slack Bot、Teams Bot），团队成员可以直接在聊天界面中输入 /pm:deploy-staging 来触发部署。
- 自动化审查与测试： 配置AI Agent在特定任务完成后，自动创建Pull Request，并触发代码审查Agent进行初步审查，甚至启动自动化测试流水线。
- 部署： AI Agent可以在通过所有测试后，自动执行部署脚本或请求部署。
- 带来的价值： 实现开发、测试、部署的高度自动化，将AI从辅助编程提升到辅助整个DevOps流程，极大提升效率和交付速度。

5.3 跨项目复用与项目迁移：知识沉淀与效率最大化

ccpm 的模块化设计，使其内部的知识库（上下文、PRD、Epic）和自定义配置（Agent、命令）可以轻松地在不同项目间进行复用和迁移，从而实现组织级的知识沉淀和效率最大化。

.claude/context/、prds/、epics/ 可整体迁移到新项目：知识的复用
- 核心理念： 许多项目的底层逻辑、通用模块或文档结构是相似的。ccpm的知识文件（PRD、Epic 定义和Context）都是Markdown格式，与项目代码分离。
- 迁移步骤：
  1. 从现有项目复制 .claude/context/、prds/ 和 epics/ 目录。
  2. 粘贴到新项目的 .claude/ 目录下。
  3. 在新项目中使用 /pm:init 进行初始化（如果尚未）。
  4. 运行 /pm:context-update 刷新新项目的全局上下文。
  5. （可选）根据新项目需要，修改或调整导入的PRD和Epic内容。
- 实战场景：
  - 微服务开发： 如果你有多个微服务项目，它们的用户认证模块可能非常相似。你可以将被验证的“用户认证系统”的PRD和Epic直接导入到新微服务项目中，节省从零开始的时间。
  - SaaS产品线： 不同的SaaS产品可能共享用户管理、计费系统等通用功能。
  - 重构项目： 当进行项目重构时，可以导入旧项目的PRD和Epic作为新项目需求的参考。
- 带来的价值： 加速新项目启动，避免重复工作，确保不同项目之间的一致性和最佳实践的传播。这有助于形成组织内部的“知识资产”。
结合GitHub fork/clone，支持多项目共享最佳实践：
- 核心理念： 对于组织而言，可以将一套标准化的 .claude/ 模板仓库化。新项目可以直接fork或克隆这个模板仓库，作为其ccpm配置的起点。
- 具体实践：
  1. 创建模板仓库： 建立一个名为 organization/ccpm-template 的GitHub仓库。在这个仓库中，只包含一个精心配置好的 .claude/ 目录，其中包含通用的 CLAUDE.md、示例PRD、Epic分解的最佳实践，以及自定义的Agent脚本和命令。
  2. 新项目使用模板： 当团队启动一个新项目时，他们可以 git clone organization/ccpm-template .ccpm，或者直接将 .claude 目录复制到新项目根目录，然后执行 /pm:init。
  3. 共享与同步： 团队可以定期更新中央模板仓库，并鼓励各项目将更新同步过去，从而实现最佳实践的共享和持续改进。
- 带来的价值： 确保整个组织内AI辅助开发流程、编码规范和项目管理标准的一致性，构建统一的自动化开发基础设施，提升组织整体的研发效能和治理水平。

通过这些高级用法，Claude Code PM 从一个简单的项目管理工具，升级为一套可定制、可扩展、可复用的智能开发框架，赋能团队和组织构建面向未来的开发生态系统。

6. 实战案例与最佳实践：项目演练与经验总结

理论结合实践，方能融会贯通。本节将通过多个实战项目场景，指导你如何将 Claude Code PM（ccpm）的核心功能应用于实际开发，并提炼出在AI辅助协作中的最佳实践。

6.1 Claude Code PM 实战训练项目清单

本清单为进阶用户设计，涵盖多种典型研发/协作场景。建议每个项目都走完整的 PRD → Epic → 任务分解 → GitHub同步 → 并行开发 → 进度追踪 → 复盘的全流程，实践 Claude Code PM 的全部能力。

1. AI 助手/聊天机器人项目

目标： 构建一个支持多轮对话、上下文记忆与插件扩展的智能聊天机器人。
练习点：
- 复杂 PRD 的拆解与需求追踪： 机器人的多轮对话逻辑、上下文管理、插件接口等需求复杂，需要仔细在PRD中定义，并通过ccpm确保分解后的任务能有效追踪到这些需求。
- 多模块（NLP、插件、UI）并行开发： 机器人项目通常涉及后端NLP处理、插件系统的业务逻辑、以及前端UI展示等多个模块，非常适合利用ccpm实现多AI Agent或人工并行开发。例如，一个Agent处理NLP逻辑，另一个处理前端UI。
- 任务依赖与进度同步： 插件系统的开发可能依赖于核心NLP模块的输出。在ccpm中，通过GitHub Issue的关联和状态更新，能清晰管理这些依赖，并及时同步进度。

2. 电商平台微服务重构

目标： 将一个传统的单体电商系统重构为订单、库存、支付等独立微服务。
练习点：
- Epic 间依赖管理： 微服务之间存在复杂依赖（如订单服务依赖库存服务）。在ccpm中，你需要明确在Epic和Task描述中指出这些依赖，并通过 /pm:blocked 命令标记，确保开发顺序。
- 多服务团队协作与 Issue 分配： 不同微服务可能由不同的团队或AI Agent负责。ccpm的Issue系统可以清晰分配任务，并通过父子Issue结构保持对整个重构项目的管理。
- 跨 repo 的进度同步（可尝试多项目多 .claude 目录）： 重构项目常涉及多个代码仓库。你可以尝试为每个微服务单独初始化一个ccpm系统（在不同的repo根目录下），然后通过GitHub Issue的URL链接或API，实现跨repo的PRD和Issue互引用。

3. 数据可视化仪表盘

目标： 开发一个实时数据可视化的 Dashboard，包括多数据源接入、复杂图表渲染与精细的用户权限管理。
练习点：
- 前后端分工与并行： Dashboard项目通常分为后端的数据接口服务和前端的展示页面。ccpm可以有效管理前后端团队的并行开发任务，通过Issue追踪接口定义和UI实现。
- Epic 级别上下文文档管理： Dashboard的功能（如数据源、图表类型、权限模型）需要大量的上下文信息。确保 /context:update 定期运行，使AI Agent和团队对项目数据模型、API契约有统一认知。
- 高级 Agent 定制（如 UI/测试 Agent）： 可以尝试自定义一个专门擅长 React 或 Vue 组件开发的Frontend Agent，以及一个擅长编写E2E测试的QA Agent，分化其职责。

4. 自动化测试与 CI/CD 集成

目标： 为已有项目建立自动化测试流水线，包括单元测试、集成测试与自动部署。
练习点：
- 测试相关 PRD 编写与落地： 如何将“确保代码质量”这样的需求，转化为具体的测试类型、覆盖率目标、测试报告生成等，并在PRD中明确。
- Epic 拆解为脚本开发、配置、文档等子任务： CI/CD集成不仅是编写脚本，还包括环境配置、测试用例编写、文档更新等。将这些工作拆解为可管理的Task。
- 与 GitHub Action/CI 工具链结合： 尝试编写ccpm的自定义命令，使其能在Issue状态变更或代码提交时，触发GitHub Actions或你选择的CI工具（如Jenkins, GitLab CI），实现真正的自动化。

5. 企业级权限/认证系统

目标： 开发一个支持多租户、OAuth2、RBAC（基于角色的访问控制）的权限管理与认证系统。
练习点：
- 复杂业务场景 PRD 拆解： 权限系统业务复杂，涉及多种角色、权限粒度、认证方式。在PRD中需要清晰定义这些细枝末节，并确保AI Agent能准确理解。
- 多角色/多 Agent 并行开发： 可以有专门的Backend Agent处理OAuth2协议，另一个Agent处理RBAC逻辑，还有Agent负责安全审计日志。
- 审计与安全相关任务的追踪与复盘： 权限系统对安全性要求极高。ccpm能确保所有与安全相关的任务（如安全审计、漏洞修复）在GitHub Issue上清晰记录，便于跟踪、验证和复盘。

6.2 详细实训操作步骤：手把手教你跑通项目

本节将以实际命令行操作，详细指导你如何在ccpm中实践上述项目。

1. 智能聊天机器人项目实训

项目目标： 构建一个具备多轮对话、上下文记忆、插件扩展能力的聊天机器人。
操作步骤：
1. 初始化项目根目录（如果尚未）：
```
cd /path/to/your/new-chatbot-project
/pm:init # 初始化ccpm，配置GitHub认证
```
2. 创建 CLAUDE.md 并使其生效：
  创建一个 .claude/CLAUDE.md 文件，定义项目技术栈（Python FastAPI, React, Redis, PostgreSQL等）和AI Agent行为规范。
  在首次与AI互动时，请在提示中提醒AI：
```
/init include rules from .claude/CLAUDE.md # 这不是pm命令，是对AI的指示
```
3. PRD 需求分析与撰写：
```
/pm:prd-new chatbot
```
  - 人工任务： 打开 .claude/prds/chatbot.md，详细补充机器人的愿景、核心功能（NLP、上下文记忆、插件系统、UI）、用户故事、以及验收标准。务求清晰。
4. PRD 解析为 Epic 实施计划：
```
/pm:prd-parse chatbot
```
  - 人工任务： 审阅并补充 .claude/epics/chatbot/epic.md，确定技术选型（如使用Redis作为记忆缓存）、架构草图、接口设计初稿和潜在风险。
5. Epic 任务分解：
```
/pm:epic-decompose chatbot
```
  - 操作： ccpm会在 .claude/epics/chatbot/ 下生成多个任务文件，如 task_implement_nlp_processing.md, task_design_memory_storage.md, task_build_chatbot_ui.md 等。
  - 人工任务： 细化这些任务，确保每个任务是独立且可交付的。
6. 一键同步到 GitHub Issuess：
```
/pm:epic-oneshot chatbot
```
  - 操作： GitHub上将自动创建父级Epic Issue，以及子任务Issues，并形成层级关系。记下这些Issue ID。
7. 并行开发与进度同步：
  - AI Agent 开发 NLP 模块：
```
/pm:issue-start <NLP模块Issue号> --agent=nlp_agent # 假设你已自定义了nlp_agent
```
    在AI生成代码后，定期：
```
/pm:issue-sync <NLP模块Issue号>
```
  - 人工开发者进行 UI 开发：
    人工在本地编码，当完成小功能或有进展时：
```
/pm:issue-sync <UI模块Issue号> # 将人工的进展同步到GitHub Issue
```
  - AI Agent 开发插件系统：
```
/pm:issue-start <插件系统Issue号> --agent=backend_agent # 假设使用通用后端Agent
```
    同步进展：
```
/pm:issue-sync <插件系统Issue号>
```
8. 进度追踪与复盘：
  - 查看项目整体状态：
```
/pm:status
```
  - 查看特定 Epic 详情：
```
/pm:epic-show chatbot
```
  - 查看进行中任务：
```
/pm:in-progress
```
  - 生成日报：
```
/pm:standup
```
  - 如果遇到任务阻塞（例如，UI开发等待NLP模块的API接口）：
```
/pm:blocked <UI模块Issue号> "等待NLP模块提供意图识别API"
```

2. 电商平台微服务重构项目实训

项目目标： 将单体电商系统重构为订单、库存、支付等独立微服务。
操作步骤：
1. 初始化项目：
  为整个重构项目或每个微服务分别初始化ccpm环境。我们假设你在一个主仓库统一管理。
```
cd /path/to/ecommerce-reconstruction
/pm:init
# ... 配置 CLAUDE.md 等
```
2. PRD 需求拆解：
```
/pm:prd-new ecommerce-microservices
```
  - 人工任务： 明确各服务的职责边界、数据同步/一致性需求、API接口定义、以及整体重构的里程碑和非功能性需求（性能、可扩展性）。
3. PRD 解析为 Epic 实施计划：
```
/pm:prd-parse ecommerce-microservices
```
  - 人工任务： 在 epic.md 中细化微服务拆分方案、技术路线（如使用Kafka进行事件驱动通信）、服务间通信协议和数据模型。
4. Epic 级任务分解（按微服务拆分）：
```
/pm:epic-decompose ecommerce-microservices
```
  - 操作： ccpm将Epic分解为更具体的Task，例如：
    - task_order_service_api_definition.md
    - task_inventory_service_db_design.md
    - task_payment_service_gateway_integration.md
    - task_user_service_authentication_logic.md
  - 人工任务： 确保每个Task都清晰地属于某个微服务，并标注服务间的依赖。
5. 同步 GitHub 并分配任务：
```
/pm:epic-oneshot ecommerce-microservices
```
  - 操作： GitHub上自动创建 Epic 和各微服务的子任务 Issue。
  - 人工任务： 分别将订单服务集群任务、库存服务任务等分配给不同的团队负责人或AI Agent。
6. 并行推进各服务：
  - 团队A（或AI Agent）开发订单服务：
```
/pm:issue-start <订单服务Issue号> --agent=order_service_agent
```
    定期同步：
```
/pm:issue-sync <订单服务Issue号>
```
  - 团队B（或AI Agent）开发库存服务：
```
/pm:issue-start <库存服务Issue号> --agent=inventory_service_agent
```
    定期同步：
```
/pm:issue-sync <库存服务Issue号>
```
  - 确保在各自的本地分支上开发，并通过Pull Request提交代码。
7. 日常进度与同步：
```
/pm:in-progress # 查看所有进行中的微服务任务
/pm:blocked # 发现微服务间可能存在的阻塞（如库存服务未就绪，订单服务无法测试）
/pm:epic-show ecommerce-microservices # 查看整个重构项目的详细进展
```

3. 数据可视化仪表盘项目实训

项目目标： 开发支持多数据源接入、实时图表渲染、权限管理的 Dashboard。
操作步骤：
1. 初始化项目：
```
cd /path/to/dashboard-project
/pm:init
# ... 配置 CLAUDE.md, 强调前端技术栈 (e.g., React, Echarts/D3)
```
2. 新建 PRD：
```
/pm:prd-new dashboard
```
  - 人工任务： 列出支持的数据源（如数据库、第三方API）、主要图表类型（折线图、柱状图、地图）、用户权限需求（角色、数据视图控制）、实时刷新需求。
3. PRD 解析和架构：
```
/pm:prd-parse dashboard
```
  - 人工任务： 细化数据源适配方案、图表渲染库选择、权限模型（如RBAC）、前后端API接口约定。
4. 任务细分与分解：
```
/pm:epic-decompose dashboard
```
  - 操作： 可能分解为以下Task：
    - 数据源适配器开发（针对不同数据源）
    - 核心图表组件库开发
    - 用户权限管理后台模块
    - Dashboard UI 框架搭建
    - 实时数据刷新机制实现
  - 人工任务： 确保前后端任务边界清晰。
5. 一键同步 GitHub：
```
/pm:epic-oneshot dashboard
```
6. 并行开发与同步：
  - 团队A（或AI Agent）开发数据源适配器（后端）：
```
/pm:issue-start <数据源Issue号> --agent=backend_data_agent
```
    定期同步：
```
/pm:issue-sync <数据源Issue号>
```
  - 团队B（或AI Agent）开发图表组件和UI（前端）：
```
/pm:issue-start <图表Issue号> --agent=frontend_agent
```
    定期同步：
```
/pm:issue-sync <图表Issue号>
```
7. 项目追踪：
```
/pm:status # 整体进度
/pm:standup # 生成日报，总结前后端团队进展
```

4. 自动化测试与 CI/CD 集成项目实训

项目目标： 为现有项目搭建自动化测试与 CI/CD 流水线。
操作步骤：
1. 初始化项目：
  在目标项目仓库内初始化ccpm。
```
cd /path/to/your-existing-project
/pm:init
# ... 配置 CLAUDE.md, 强调测试框架和CI/CD工具 (e.g., Jenkins, GitHub Actions)
```
2. PRD 编写：
```
/pm:prd-new ci-cd
```
  - 人工任务： 明确测试类型（单元测试、集成测试、E2E测试）、预期的测试覆盖率目标、自动化部署的触发条件和环境、回滚策略。
3. PRD 转 Epic：
```
/pm:prd-parse ci-cd
```
  - 人工任务： 规划CI/CD流水线的具体步骤（构建、测试、部署），选择具体的CI/CD工具和相关配置。
4. 任务分解：
```
/pm:epic-decompose ci-cd
```
  - 操作： 可能分解为以下Task：
    - 单元测试框架集成与基础测试用例编写
    - 集成测试环境搭建与API测试用例
    - 编写 .github/workflows/main.yml (GitHub Actions配置)
    - 部署脚本编写与生产环境配置
    - 代码质量检查工具集成 (e.g., SonarQube)
  - 人工任务： 确保任务涵盖了整个CI/CD流程的所有环节。
5. GitHub 同步：
```
/pm:epic-oneshot ci-cd
```
6. 各任务并行推进：
  - AI Agent 编写单元测试：
```
/pm:issue-start <单元测试Issue号> --agent=test_agent # 假设自定义了test_agent
```
    然后同步代码和报告：
```
/pm:issue-sync <单元测试Issue号>
```
  - 人工开发者配置 CI/CD 流程：
    人工在 CI/CD 平台（如GitHub Actions）上配置 .yml 文件，当配置完成后：
```
/pm:issue-sync <CI配置Issue号> # 将配置成功信息和遇到的问题同步到Issue
```
  - 其他任务依此类推。
7. 进度和阻塞排查：
```
/pm:in-progress # 了解CI/CD各环节的并行进展
/pm:blocked # 发现因外部工具问题或配置问题导致的阻塞
```
  - 进阶： 可自定义ccpm命令，如 /pm:run-ci，直接从命令行触发CI流水线，并将结果同步回Issue。

5. SaaS 产品 MVP 快速孵化实训

项目目标： 从0到1搭建一个标准 SaaS 产品原型（MVP），包含用户注册、主功能、计费等。
操作步骤：
1. 初始化项目：
```
cd /path/to/saas-mvp-project
/pm:init
# ... 配置 CLAUDE.md，特别是产品目标和AI Agent的角色设定 (e.g., "你是一个SaaS产品经理兼全栈开发者...")
```
2. PRD 头脑风暴与撰写：
```
/pm:prd-new saas-mvp
```
  - 人工任务： 与AI共同定义MVP的核心功能清单。详细列出目标用户、核心业务流程、最小可行功能集、注册登录流程、概略的计费模型、以及MVP的发布标准。这是最关键的环节，决定了MVP的成败。
3. PRD 解析为 Epic 实施计划：
```
/pm:prd-parse saas-mvp
```
  - 人工任务： 审阅 epic.md，确定整体架构（如使用 Next.js 全栈框架）、数据库选型、主要第三方服务（如Stripe for payments）集成方案。
4. 任务分解：
```
/pm:epic-decompose saas-mvp
```
  - 操作： ccpm将Epic分解为更细粒度的Task，通常会涵盖：
    - 用户认证模块 (注册、登录、会话管理)
    - 核心业务逻辑模块 (MVP主功能实现)
    - 数据库设计与实现
    - UI/UX 设计与前端开发
    - 简易计费系统集成
    - 部署与CI/CD基础配置
    - 管理后台基础功能
  - 人工任务： 确保MVP的任务颗粒度足够小，以便快速迭代。
5. 一键同步与分工：
```
/pm:epic-oneshot saas-mvp
```
  - 人工任务： 根据任务类型，分配给不同的AI Agent或人工开发者。例如，一个AI Agent负责用户认证，另一个负责主业务模块。
6. 并行开发、同步进度：
  - 启动多个AI Agent并行开发：
```
/pm:issue-start <用户认证Issue号> [--agent=auth_agent]
/pm:issue-start <核心功能Issue号> [--agent=feature_agent]
# ... 等等
```
    在每次AI生成代码或人工修改后，进行同步：
```
/pm:issue-sync <对应任务Issue号>
```
7. 进度追踪与复盘：
  - 定期 /pm:status、/pm:epic-show saas-mvp 检查整体进度。
  - 每日 /pm:standup 自动生成日报，了解昨日进展、今日计划和阻塞。
  - 特别关注 /pm:blocked，确保MVP开发过程中遇到的任何外部依赖或技术难题都能及时解决。

6.3 最佳实践：提升AI辅助协作的效率与质量

在实战中运用ccpm，遵循以下最佳实践能够进一步提升你的开发效率和项目管理质量：

重视 PRD 撰写与完善，保证“每一行代码皆可追溯”：
PRD是AI理解需求、人工达成共识的基础。投入时间编写高质量、详尽、无歧义的PRD，会为后续的开发节省数倍的时间。确保PRD中的每一个功能点都可被分解为任务，且最终的代码提交都能关联到PRD中的需求。
建议每个 Epic 粒度合理，便于并行与管理：
一个Epic不宜过大（导致分解任务过于庞杂），也不宜过小（失去宏观指导意义）。理想的Epic应聚焦于一个相对独立、有明确业务价值的大功能模块。在 /pm:prd-parse 之后，人工应审阅Epic的粒度。
定期 /context:update，保持项目知识库新鲜：
项目的进展是动态的。每次重要的需求变更、里程碑达成或关键技术决策后，都应运行 /context:update 来更新项目的全局上下文。这确保了AI Agent能够基于最新的项目知识做出决策。
遇到复杂需求，优先分解为独立可交付任务：
这是敏捷开发的精髓，也是AI Agent高效协作的前提。将大任务拆解为小任务，不仅降低了AI的认知负荷，也使得任务更容易分配、开发、测试和集成。
善用 /pm:next 智能推荐，提升团队协作效率：
pm:next 能够根据项目的实时状态智能推荐下一个优先任务。这对于项目经理在分配任务，或团队成员在选择待办任务时非常有帮助，确保资源总是投入到最关键的路径上。
推崇“透明开发”，进度/讨论/决策全部留痕：
通过频繁使用 /pm:issue-sync，将AI Agent的思考过程、代码输出，以及人工开发者的进展、讨论、决策都同步到GitHub Issue评论区。GitHub Issue成为团队协作的“单一真相来源”，所有历史操作可追溯，极大降低了项目移交和人员变动时的上下文丢失风险。
自定义 Agent 角色，优化 AI 产出：
不要满足于默认的AI Agent。根据你的项目技术栈（如前端用React/Vue，后端用Python/Node.js），在 .claude/agents/ 目录下自定义不同角色的Agent脚本，明确其专业领域、编码风格和决策偏好。这将使AI的产出更符合你的期望。
结合人工审查与AI辅助，形成“人机交互式开发”：
AI Agent是一个强大的助手，但它不能替代人类的最终判断。人工开发者应定期审查AI生成的代码，提供反馈、修正和优化。通过这种“人教AI，AI协作人”的迭代模式，既能利用AI的速度，又能确保代码质量和符合人类的创造性。

7. 常见问题与进阶技巧：解决实操疑难

在使用 Claude Code PM 过程中，你可能会遇到一些常见问题，并希望探索更高级的用法。本节将为你提供解决方案和进阶技巧。

7.1 FAQ：常见问题与排查指南

PowerShell 安装报错 404 或脚本执行异常：
- 问题： iwr 命令无法下载脚本，或者下载后执行时出现PowerShell特有的语法或权限错误。
- 解决方案： 优先考虑使用 WSL (Windows Subsystem for Linux)。在WSL终端中，你可以像Linux/macOS用户一样无缝安装和运行ccpm。如果必须在原生PowerShell下使用，请确保：
  1. 你的PowerShell执行策略允许运行下载的脚本（Set-ExecutionPolicy RemoteSigned -Scope CurrentUser）。
  2. 如果仍然报错，可以直接进行快速手动安装：git clone https://github.com/automazeio/ccpm.git . && rm -rf .git/，然后手动配置环境变量并安装 gh CLI 和 gh-sub-issue 扩展。
GitHub 认证失败 (gh auth login 报错)：
- 问题： 在 /pm:init 过程中或手动执行 gh auth login 时，认证失败，通常是由于网络问题、GitHub token权限不足或浏览器回调问题。
- 解决方案：
  1. 检查网络连接： 确保你的网络可以正常访问 GitHub。
  2. 重新运行 gh auth login： 强制重新认证。在提示选择认证方式时，通常选择“Web browser”最方便。
  3. 手动生成 Personal Access Token (PAT)： 作为备用方案，你可以在GitHub设置中手动生成一个PAT（Personal Access Token），并确保它拥有所有必要的仓库权限（repo, workflow, write:packages, delete:packages, admin:org 等）。然后在 gh auth login 提示时，选择“Paste an authentication token”并输入PAT。
  4. 检查Token权限： 确保你的PAT权限足够用于创建Issue、评论和管理仓库。
Issue 同步异常 (/pm:issue-sync 报错)：
- 问题： 无法将本地进展同步到GitHub Issue，可能出现网络错误、权限错误或 gh-sub-issue 相关问题。
- 解决方案：
  1. 确认 gh 和 gh-sub-issue 已正确安装： 运行 gh extension list 确认 sub-issue 是否在列表中。如果缺失，尝试 gh extension install yahsan2/gh-sub-issue。
  2. 检查 GitHub 认证状态： 运行 gh auth status 确认你是否已登录且token有效。
  3. 检查网络连接： 确保网络畅通。
  4. 查看详细错误信息： ccpm的报错信息通常会引导你排查问题。根据具体错误提示进行调试。
  5. 手动同步（备用）： 如果是临时问题，可以手动将本地AI Agent的输出复制粘贴到GitHub Issue的评论区。
AI Agent 生成的代码不符合预期/风格：
- 问题： AI Agent生成的代码不符合项目技术栈、编码规范或你的期望。
- 解决方案：
  1. 优化 CLAUDE.md： 检查 .claude/CLAUDE.md 中的“技术栈与编码规范”和“AI Agent行为规范”部分。确保你提供了足够具体、清晰的指导，例如指定Python版本、框架、Linter规则、甚至提供示例代码风格。
  2. 自定义 Agent 脚本： 在 .claude/agents/ 目录下创建或修改Agent脚本，调整其 INITIAL_PROMPT，让AI Agent扮演更特定的角色（如“资深的Python FastAPI工程师”）。
  3. 提供明确反馈： 在GitHub Issue评论中，对AI生成的代码提出具体、可操作的修正意见，让AI从错误中学习。例如：“请使用FastAPI的依赖注入而不是全局变量”或“CSS请使用TailwindCSS工具类”。

7.2 进阶技巧：提升ccpm的使用效率

为组织内所有项目统一配置 .claude，实现知识复用：
- 技巧： 创建一个组织级的“ccpm模板仓库”，其中包含一套标准的 .claude/ 目录（含通用 CLAUDE.md、常用Agent脚本、自定义命令和示例PRD/Epic结构）。
- 实施： 新项目启动时，只需克隆或复制这个模板仓库中的 .claude/ 目录到其项目根目录。这样，所有项目都能共享组织的最佳实践和AI配置，形成统一的开发规范和效率基线。
可用 Makefile、CI流程自动触发 /context:update、/pm:status：
- 技巧： 将ccpm的一些管理命令集成到项目的自动化流程中。
- 实施：
  - Makefile集成： 在项目的 Makefile 中添加规则，例如 make context-update 来执行 /context:update。
  - CI/CD触发： 配置 GitHub Actions 或其他 CI/CD 工具，在特定事件（如 main 分支代码合并、每周定时任务）发生时，自动执行 /context:update 和 /pm:status。可以将 /pm:status 的输出作为构建报告的一部分，或发送到团队聊天。
配合团队每日 standup，自动生成日报：
- 技巧： 将 /pm:standup 命令集成到团队的日常工作流中。
- 实施： 在每日站会开始前，由项目经理或指定人员运行 /pm:standup。AI Agent会根据项目最新的GitHub Issue状态和本地日志，自动生成一份简洁明了的日报，总结昨日进展、今日计划和遇到的阻塞。这大大节省了人工准备日报的时间，并确保信息基于项目真实数据。
自定义 Agent 的工具调用能力：
- 技巧： 进阶用户可以修改 .claude/agents/ 下的Agent脚本，增加AI Agent调用外部工具的能力。
- 实现： 在Agent的Prompt中，你可以指示AI Agent在需要时执行特定的Bash命令或Python脚本（前提是这些脚本已在Agent的环境中可用），并将执行结果反馈给AI以辅助其决策。例如，指示AI在生成代码后自动运行 linter 或格式化工具。
利用 GitHub Labels 和 Project Boards 增强管理：
- 技巧： 虽然ccpm提供了强大的命令行管理，但结合GitHub原生的Labels和Project Boards功能，可以进一步提升可视化管理能力。
- 实施：
  - 自定义Labels： 为Issue设置自定义Labels（如 backend, frontend, bug, refactor, priority:high），便于筛选和分类。
  - Project Boards： 在GitHub Project Boards中创建看板，以拖拽方式管理Epic和Task的流程（如 Todo -> In Progress -> Code Review -> Done）。ccpm的Issue同步会实时更新Issue状态，Project Boards也会相应更新。
结合 GitHub Pull Request (PR) 流程：
- 技巧： AI Agent完成代码后，可以提交PR。
- 实施： 引导AI Agent在完成一个Task后，不仅同步到Issue，还创建对应的Pull Request。PR中可以包含AI的代码、测试报告、思考过程。人工开发者再对PR进行审查。当PR合并时，可以配置GitHub Actions自动关闭关联的Issue，形成完整的GitFlow/GitHub Flow。

掌握这些进阶技巧，将帮助你更深度地挖掘 Claude Code PM 的潜力，构建一个高度自动化、智能化的开发与项目管理生态系统。

8. 参考资源与社区

持续学习、积极交流是发挥 Claude Code PM 最大价值的关键。以下是一些重要的参考资源和社区，供你深入探索和获取帮助。

官方仓库 README：
- https://github.com/automazeio/ccpm/blob/main/README.md
- 价值： 这是ccpm最新功能、安装说明和核心理念的官方来源。定期查阅可以获取最新更新和最佳实践。
快速安装说明：
- https://github.com/automazeio/ccpm/tree/main/install
- 价值： 详细的平台特定安装指南和故障排除建议，是解决安装问题的第一手资料。
gh-sub-issue 扩展：
- https://github.com/yahsan2/gh-sub-issue
- 价值： 理解ccpm如何实现GitHub Issue父子任务管理的关键工具。如果你对其工作原理好奇或遇到问题，可以查阅其官方文档。
Automaze 官网：
- https://automaze.io
- 价值： 了解ccpm的开发者Automaze团队，以及他们围绕AI驱动开发的其他产品和愿景。
GitHub Discussions/Issues：
- https://github.com/automazeio/ccpm/issues
- 价值： 这是ccpm最活跃的社区交流平台。
  - Issues： 提交Bug报告、功能请求或你遇到的具体问题。
  - Discussions： 参与社区讨论、分享使用经验、寻求帮助。在提出问题前，建议先搜索现有Issue和Discussion，看是否已有类似问题和解决方案。
X/Twitter @aroussi：
- https://x.com/aroussi
- 价值： 关注项目开发者的最新动态、功能预告、理念分享和社区互动。