ghpm：让AI编码助手无缝管理GitHub项目的自动化技能包

1. 项目概述：一个为AI编码助手打造的GitHub项目管理技能包

如果你和我一样，日常开发中已经离不开像Claude Code这样的AI编码助手，同时又需要频繁地在GitHub Projects v2上管理项目任务，那你肯定遇到过这样的割裂感：一边是能理解自然语言、帮你写代码的智能伙伴，另一边是僵硬的看板、繁琐的Issue状态更新和PR创建流程。你不得不在两个工具间反复切换，手动同步信息，效率大打折扣。ghpm（GitHub Project Manager）这个项目，就是为了弥合这道鸿沟而生的。它本质上是一套“技能”（Skills），能让你的AI助手直接“理解”并操作GitHub项目看板，实现从任务分拣、认领、编码到合并PR的完整生命周期自动化。

简单来说，ghpm把你的AI助手变成了一个懂项目管理的“开发组长”。它不再只是一个被动的代码生成器，而能主动查看项目健康度、建议接下来该做什么、为特定Issue创建分支并推进开发流程，最后还能生成关联PR。这一切都通过你与AI助手自然的对话来完成，比如你只需要说“看看项目状态”或者“开始处理Issue #42”，剩下的ghpm会帮你打理。它支持任何实现了“技能”体系的AI编码代理，目前对Claude Code的集成最为深入。对于任何使用GitHub Projects v2进行敏捷开发或开源项目维护的团队或个人开发者，尤其是那些希望将AI深度融入工作流的，ghpm提供了一个极具前瞻性的效率提升方案。

2. 核心设计思路与工作原理解析

2.1 设计哲学：会话式项目管理

ghpm的核心设计理念，是将项目管理抽象为一次可中断、可恢复的“会话”（Session）。传统工具中，一个任务的状态变迁是离散的、记录在数据库里的点。而在ghpm的模型里，处理一个Issue被视作你和AI助手之间的一场持续对话。这场对话有明确的阶段（Phase），如“澄清需求”、“制定计划”、“实施编码”。每个阶段都会产生“决策”（Decisions）——这些是关键的设计选择或结论，会被自动提取并发布到Issue的评论中，作为唯一的真相来源。

这种设计带来了几个关键优势。首先，它极度适配AI助手的工作方式。AI本质上是基于上下文进行推理的，将会话状态和项目状态绑定，使得AI在任何时候都能清晰地知道“我们进行到哪一步了”、“之前做过哪些决定”。其次，它支持非线性工作流。你可以随时中断对一个Issue的处理（比如去处理一个更紧急的Bug），ghpm会将当前会话状态完整保存到本地。当你回来时，只需再次触发ghpm-work <issue-number>，它就能从上次中断的环节无缝恢复，AI助手也能立刻接上之前的思路。最后，它实现了人机协作的透明化。所有自动或半自动执行的操作，以及AI推导出的决策，都以评论形式留痕，整个处理过程对协作者完全可见，避免了“黑盒”自动化带来的困惑。

2.2 架构解析：配置驱动与约定优先

ghpm的架构清晰地分为三层：配置层、技能层和集成层。这种分层设计确保了它的灵活性和可扩展性。

配置层是项目的“大脑”，位于项目根目录的.ghpm/文件夹下（该目录已被自动加入.gitignore）。config.json是这个层的核心，它定义了项目看板的“世界观”。这里不仅包含从GitHub拉取的项目字段（Fields）和视图（Views）信息，更重要的是conventions（约定）和prompts（提示）两大块。conventions用自然语言规则描述团队的工作习惯，例如：“分支命名规则为{类型}/{Issue编号}/{简短描述}，类型需从Issue标签中检测”。ghpm和AI会尝试理解并执行这些规则。prompts则定义了自动化程度，控制哪些操作需要用户确认，哪些可以自动执行。这种配置驱动的方式，使得ghpm可以轻松适配不同团队迥异的工作流，而无需修改代码。

技能层是暴露给用户和AI调用的具体功能集合，也就是那几个ghpm-开头的命令。每个技能都是一个独立的模块：

• ghpm-status: 生成项目健康度仪表盘，快速查看各状态下的任务数量、阻塞项等。
• ghpm-view: 基于保存的视图或临时过滤器查询看板条目。
• ghpm-suggest: 基于优先级、截止日期、依赖关系等约束，智能推荐下一个应该处理的任务。
• ghpm-work: 核心技能，驱动单个Issue的完整处理生命周期。
• ghpm-issue: 快速创建Issue并自动添加到项目看板。

集成层负责与AI助手深度绑定。ghpm-init命令会尝试自动检测你当前使用的AI代理（如Claude Code），并提议安装“钩子”（Hooks）。以Claude Code为例，安装后，ghpm会将当前活跃的会话上下文和阶段信息，注入到AI助手的每一轮对话中。这意味着AI在回答你任何编码问题时，都清楚地知道当前正在处理哪个Issue、处于哪个阶段，从而给出更精准的上下文相关建议。如果没有钩子，ghpm依然可以通过显式的触发词（如decide: <文本>来记录决策）工作，但体验的流畅性会打折扣。

2.3 数据流与状态管理

理解ghpm的数据流对排查问题至关重要。其核心数据流是双向同步的，但以本地缓存为缓冲，以保证操作的响应速度和离线工作能力。

1. 初始化与缓存：执行ghpm-init时，工具会通过GitHub CLI (gh) 访问API，获取指定项目的完整结构（字段、视图、所有条目），并序列化到本地的cache.json中。这个缓存文件是ghpm大部分查询操作（如status,view）的数据源，避免频繁调用API导致速率限制。
2. 会话状态持久化：当开始处理一个Issue（ghpm-work），会在.ghpm/sessions/下创建一个以Issue编号命名的JSON文件。这个文件实时记录当前会话所处的阶段（Phase）、产生的临时数据、以及尚未发布的决策草稿。这个文件在会话完成后不会被删除，而是将phase标记为`"done"，这形成了一个宝贵的历史记录库，可用于后续复盘或分析。
3. 与GitHub的同步：任何修改项目状态的操作（如将Issue状态改为InProgress、发布评论、创建PR），都会通过ghCLI实时推送到GitHub。ghpm自身不存储任何最终状态，GitHub是唯一的事实源。本地缓存会定期（或在某些写操作后）在后台更新，以保持一致性。
4. 决策提取与发布：这是ghpm的智能所在。在“计划”（Plan）和“实施计划”（Impl Plan）阶段，AI会生成详细的方案文本。ghpm会扫描这些文本，利用启发式规则或简单的模式匹配，识别出其中的“设计决策”（例如，“决定采用X算法因为Y”、“选择Z库作为解决方案”）。然后，它会将这些决策汇总，在征得用户同意（根据prompts配置）后，以一条清晰的评论发布到原Issue下。

注意：由于缓存机制，在多人协作的场景下，如果你刚刚通过GitHub网页或其他工具更新了看板，本地ghpm可能不会立即反映变化。对于关键的状态依赖操作（如开始一个刚被分配的任务），可以先运行一次ghpm-view来隐式触发缓存刷新，或者直接使用ghCLI命令来确保获取最新状态。

3. 从零开始：安装、配置与深度集成指南

3.1 环境准备与基础安装

在施展ghpm的魔法之前，需要确保你的“法杖”（环境）已经就绪。这不仅仅是安装一个npm包那么简单。

第一步：夯实基础——GitHub CLI (gh)ghpm的所有GitHub操作都通过官方的ghCLI完成，因此它是绝对的前提。前往 cli.github.com 下载并安装对应你操作系统的版本。安装后，在终端执行gh auth login进行认证。这里有一个关键细节：认证时务必选择正确的令牌范围（Token Scopes）。ghpm需要read:project（读取项目）和project（读写项目）权限。如果你在登录时使用了最小权限，后续操作可能会失败。你可以通过gh auth status查看当前令牌的权限，如果不足，需要重新登录或更新令牌。

第二步：验证项目类型——必须是Projects v2ghpm仅支持GitHub Projects v2（新一代项目），不支持经典的Projects（旧版）。如何区分？直接浏览器打开你的项目看板，如果URL格式是https://github.com/orgs/<组织名>/projects/<数字>或https://github.com/users/<用户名>/projects/<数字>，并且界面是GitHub较新的UI，那很可能就是v2。最保险的方式是尝试用ghCLI访问：gh api /projects/<project_id>。如果返回信息且包含number和owner_url等字段，就是v2。

第三步：安装ghpm技能环境就绪后，安装本身非常简单。在你的项目根目录下（或任何你希望管理项目的目录），运行：

npx skills add jackchuka/ghpm

这条命令会从npm注册表获取ghpm技能包，并将其安装到你的技能运行时环境中。对于Claude Code用户，它通常会自动配置。安装完成后，你可以尝试运行ghpm-status来测试，但此时会提示你尚未初始化项目。

3.2 项目初始化与个性化配置

初始化是连接ghpm与你的具体GitHub项目的桥梁。执行命令：

ghpm-init https://github.com/orgs/your-org/projects/1

请将URL替换为你实际的项目地址。这个命令会执行以下关键操作：

1. 获取项目元数据：通过GitHub API拉取项目的所有自定义字段、视图、状态选项等配置。
2. 创建本地目录结构：在项目根目录生成一个.ghpm/文件夹，里面包含config.json、cache.json和一个空的sessions/目录。
3. 生成初始配置：config.json中会填充项目的结构，并生成默认的conventions和prompts规则。

深度定制config.json默认配置能用，但定制后才能发挥最大威力。打开.ghpm/config.json，重点关注两个部分：

• conventions（约定）：这里用自然语言定义你团队的规则。例如：

  { "conventions": { "branch": "基于Issue标签创建分支。如果存在标签 'bug'，类型为 'fix'；如果存在 'feature'，类型为 'feat'；否则为 'chore'。分支格式：{type}/{issue-number}/{title-slug}。", "status_sync": "当开始处理一个Issue时，如果其当前状态是 'Todo' 或 'Ready'，则自动将其更新为 'In Progress'。", "decisions": "当在计划文本中检测到短语如'我们决定'、'因此选择'、'采用...方案'时，提示用户确认是否将其记录为正式决策。" } }

  这些描述会被AI解析并尝试执行。写得越清晰、越具体，AI的行为就越符合预期。

• prompts（提示）：这是控制自动化与人工干预平衡的开关。配置采用层级覆盖的规则：

  { "prompts": { "default": "prompt", // 全局默认：所有操作都询问 "ghpm-work": { "default": "auto", // 对于ghpm-work技能，默认自动进行 "assign_issue": "prompt", // 但分配Issue时仍需确认 "draft_pr": "prompt" // 创建PR草案前也需确认 }, "ghpm-issue": { "default": "skip" // 创建Issue时，自动执行所有步骤（慎用！） } } }

  解析规则：当执行一个动作时，ghpm会按prompts.<skill>.<action>->prompts.<skill>.default->prompts.default->"prompt"的顺序查找，使用第一个找到的值。这让你可以精细控制每个环节的自动化程度。

3.3 与AI代理的深度集成实践

ghpm与AI的集成程度，直接决定了体验是“好用”还是“惊艳”。

Claude Code深度集成对于Claude Code用户，ghpm-init成功后会询问你是否安装钩子。强烈建议同意。这会在你的Claude Code用户配置（通常是~/.claude/settings.local.json）中添加一个hooks配置。它的作用是：

• 会话上下文注入：每当你与Claude对话时，如果存在活跃的ghpm会话，会话的Issue标题、编号、当前阶段等信息会自动作为背景上下文提供给AI。这意味着你不需要每次都说“关于Issue #42...”，AI天然就知道你在说什么。
• 陈旧会话检测：如果你试图开始一个新会话，但存在未完成的旧会话，AI会提醒你，并询问是否继续旧的或开始新的。

其他AI代理的适配对于其他支持技能的AI代理（如Cursor等），ghpm依然可用，但需要通过显式命令来驱动。核心是理解两个关键触发词：

• decide: <你的决策文本>：当你在与AI讨论中得出一个结论时，手动输入此命令，ghpm会将其作为决策记录到当前会话，并在适当时机发布到Issue。
• wrap up：当你完成一个Issue的所有工作（包括PR创建），使用此命令来优雅地结束当前会话，将其标记为完成。

即使没有自动钩子，你也可以通过手动切换上下文来获得近似体验。例如，在开始与AI讨论前，先告诉它：“我们正在处理Issue #42: 修复登录页面的CSS错位问题，目前处于‘实施计划’阶段。” AI会基于此上下文提供建议。

4. 核心技能实战：驱动完整的开发工作流

4.1 项目洞察与任务选取：ghpm-status与ghpm-suggest

在开始具体编码前，了解全局并选择正确的任务至关重要。ghpm-status和ghpm-suggest就是你的战略仪表盘。

ghpm-status [team]：一眼看清项目健康度运行ghpm-status会生成一个基于终端文本的仪表盘。它不仅仅罗列数字，而是提供洞察：

项目健康度概览 (项目: Awesome-Product) ========================================= 📊 状态分布： - 待办 (Todo): 12 个 (其中 3 个已逾期) - 就绪 (Ready): 5 个 - 进行中 (In Progress): 8 个 (平均停留 2.5 天) - 审查中 (Review): 4 个 - 已完成 (Done): 32 个 (本周新增 5 个) ⚠️ 风险提示： - 阻塞项: 2 个 (Issue #101, #105) - 长期进行中 (>5天): 1 个 (Issue #78 - “重构用户模块”) - 高优先级待办: 3 个 👥 团队负载 (当指定`ghpm-status frontend`时): - @alice: 3 个进行中 - @bob: 1 个进行中， 1 个审查中

这个视图能帮你快速发现瓶颈（如“进行中”任务过多）、识别风险（逾期任务、阻塞项）并平衡团队负载。[team]参数是可选的，可以用来过滤特定团队或组件（如frontend,backend）的任务，这需要在项目的Team字段或标签上有相应的约定。

ghpm-suggest [constraint]：让AI推荐下一步工作当你不知道接下来该做什么时，ghpm-suggest是你的智能顾问。它不仅仅按优先级排序，而是综合多种因素进行推荐：

# 简单推荐 ghpm-suggest # 输出：建议处理 Issue #56: “优化数据库查询X”。理由：优先级高 (P0)，依赖项已解决，预估耗时短 (2点)。 # 添加约束条件 ghpm-suggest “前端相关且耗时小于3点” # 输出：建议处理 Issue #34: “修复按钮点击态样式”。理由：匹配‘前端’标签，故事点估算为2，当前无人处理。

背后的逻辑是，ghpm会读取缓存中的所有Issue，并基于以下规则打分：

1. 优先级与截止日期：高优先级（P0/P1）和临近截止日期的任务得分高。
2. 依赖关系：所有前置任务已完成的Item得分高。
3. 负载均衡：尽量避免推荐给已有过多“进行中”任务的成员。
4. 技能匹配：（如果配置了相关字段）推荐与开发者标签匹配的任务。
5. 约束过滤：根据用户输入的[constraint]（自然语言）进行筛选，如“后端”、“bug”、“本周要完成”。

实操心得：不要完全依赖suggest的结果。把它当作一个强大的过滤器和排序器。最终选择时，还应结合你的当下精力（上午适合复杂任务，下午适合琐事）、任务间的上下文切换成本（连续处理同一模块的任务效率更高）来综合决定。我个人的习惯是每天早站会前运行一次ghpm-suggest，快速了解全局，然后结合团队同步的信息做出最终选择。

4.2 任务处理核心引擎：ghpm-work全生命周期详解

ghpm-work <issue-number>是ghpm的灵魂。它将一个Issue的处理流程标准化、自动化，并嵌入AI辅助。我们以一个具体的Issue #42为例，拆解其完整生命周期。

阶段1：启动与设置 (Setup)执行ghpm-work 42。首先，ghpm会检查本地是否有该Issue的未完成会话。如果没有，则创建一个新会话。

1. 分配与分支：根据conventions.branch规则，AI会分析Issue #42的标签和标题。假设它是一个bug标签的Issue，标题是“登录页面按钮错位”。AI会生成分支名建议，例如fix/42/login-button-misalignment。根据prompts配置，它可能会询问你是否确认创建此分支。确认后，它会通过ghCLI在本地创建并切换到这个分支，同时自动将Git上游分支设置为同名（如果需要）。
2. 状态同步：接着，ghpm会读取Issue当前在项目看板上的状态。假设是Ready for Dev。根据conventions.status_sync规则（“如果状态为Planned或ReadyForDev，则设置为InProgress”），它会自动将项目看板上的状态更新为In Progress。所有这些操作都会被记录，并在终端给出明确反馈。

阶段2：需求澄清 (Clarify)状态更新后，AI（得益于集成的钩子）已经知道上下文。它会自动分析Issue #42的描述和评论。如果描述很模糊，比如只写了“按钮位置不对”，AI会主动提问以澄清需求：

“我看到Issue #42描述说‘按钮位置不对’。为了更好地解决这个问题，我需要澄清几个细节：1. 具体是哪个页面的哪个按钮？2. ‘不对’是和设计稿不符，还是在某些浏览器下错位？3. 是否有相关的截图或错误报告链接？” 这些澄清问题会直接呈现在你与AI的对话中。你的回答会被AI记录，并可能被提炼为“决策”的一部分。这个阶段确保了开发者和AI对问题的理解是一致的，从源头上减少返工。

阶段3：制定方案与计划 (Plan & Implementation Plan)这是AI大显身手的阶段。

• 探索与方案设计 (Plan)：AI会分析代码库（读取相关文件），然后提出一个或多个解决方案。例如：“方案A：调整父容器的CSS flex属性。方案B：修改按钮组件自身的定位方式。我倾向于方案A，因为更符合整体布局模型，且影响面小。” 这个计划文本会被ghpm捕获。
• 决策提取与记录：ghpm会扫描计划文本，识别出其中的决策点（“我倾向于方案A”）。根据prompts.decisions配置，它会询问：“检测到一项决策：‘采用方案A调整父容器CSS’。是否将其记录为正式决策并发布到Issue？” 确认后，这个决策会被暂存。
• 具体实施计划 (Impl Plan)：在方案确定后，AI会进一步拆解为具体的实施步骤：“1. 定位到src/components/LoginForm.css文件。2. 找到.button-container类，将其display属性改为flex并添加justify-content: center。3. 在src/components/LoginForm.js中验证按钮引用。4. 编写一个测试，验证按钮在移动端视口下的位置。” 同样，这个详细的计划也会被捕获，并可能提取出更多决策（如选择的具体CSS属性）。

阶段4：实施与验证 (Implement)AI会根据上一步的详细计划，开始编写或修改代码。你可以与它交互：“实现第一步”，AI就会生成具体的CSS代码变更。或者你可以说“为这个修改写个测试”，AI会生成相应的单元测试代码。在整个编码过程中，ghpm不做过多的流程干预，但会话状态始终保持，AI的上下文始终围绕Issue #42。

阶段5：收尾与交付 (Draft PR)代码完成并本地测试后，你可以指示AI或手动运行命令来进入下一阶段。

1. 提交代码：AI可以帮助生成符合约定的提交信息：git commit -m “fix: correct login button alignment (#42)”。
2. 创建草案PR：这是ghpm-work的一个关键自动操作。根据配置，它会：
   • 将本地分支推送到远程。
   • 使用Issue标题和描述作为基础，自动生成PR标题和描述。
   • 在PR描述中自动关联原Issue（Closes #42或Fixes #42）。
   • 将PR创建为**草案（Draft）**状态。这是一个非常好的实践，表示代码尚未准备好审查，避免误通知评审人。
   • 自动将项目看板上的Issue状态从In Progress更新为In Review（或你配置的下一状态）。
3. 会话结束：PR创建后，当前会话的phase会被标记为"done"。.ghpm/sessions/42.json文件会被保留，成为一个完整的历史档案。

至此，一个Issue从认领到PR创建的全流程，在AI助手的深度参与和ghpm的自动化编排下，高效、透明地完成了。你几乎不需要离开你的编辑器和AI对话界面。

5. 高级配置、问题排查与实战心法

5.1 高级配置技巧：让ghpm更懂你的团队

默认配置是通用的，但通过一些高级调整，可以让ghpm与你的团队文化完美融合。

利用自定义字段（Custom Fields）GitHub Projects v2的强大之处在于自定义字段。ghpm能识别并利用这些字段。例如，如果你的项目有“故事点（Story Points）”、“技术栈（Tech Stack）”、“难度（Difficulty）”等字段，你可以在conventions中引用它们。

{ "conventions": { "suggest_priority": "优先推荐‘故事点’小于3且‘难度’为‘简单’或‘中等’的未开始任务给新成员。", "branch": "如果‘技术栈’字段包含‘React’，则在分支名前缀加上‘react/’。" } }

在ghpm-suggest的推荐算法中，你可以通过修改其背后的逻辑（如果未来版本支持插件）或通过复杂的约束条件来优先考虑这些字段。

设计状态机与流程规则conventions.status_sync是你定义工作流状态机的地方。一个成熟的团队可能有更复杂的流程：

"status_sync": { "on_work_start": "如果状态是‘Backlog’或‘Ready’，则设为‘In Progress’。如果状态是‘Blocked’，则提示用户先解决阻塞项。", "on_pr_draft": "自动将状态从‘In Progress’改为‘Code Review’。", "on_pr_merged": "自动将状态从‘Code Review’改为‘Done’。", "on_pr_closed_without_merge": "自动将状态改回‘In Progress’并添加评论提示。" }

通过精细定义状态转换规则，可以确保看板状态与实际开发活动严格同步。

提示策略的黄金法则配置prompts是一门平衡艺术。我的经验法则是：

• 对“写”操作谨慎：assign_issue（分配任务）、draft_pr（创建PR）、post_decision（发布决策）建议设为"prompt"。这些操作会产生公开影响，需要人工确认。
• 对“读”和内部状态操作放宽：status_sync（状态同步）、clarify_issue（澄清问题）可以设为"auto"，以提升流畅度。
• 对破坏性操作严格：虽然没有直接的“删除”操作，但对于任何可能覆盖或修改重要数据的环节，都应保持手动确认。
• 分技能配置：为ghpm-work设置较自动的默认策略，因为它是一个连贯的工作流。而为ghpm-issue（创建Issue）设置较保守的策略，因为创建新Issue的容错率较低。

5.2 常见问题排查与解决方案实录

即使工具设计得再完善，在实际使用中也会遇到各种问题。以下是我在实践中遇到的一些典型情况及其解决方法。

问题1：ghpm-init失败，提示认证错误或权限不足。

• 症状：Error: Failed to fetch project data. Check your GitHub authentication.
• 排查步骤：
  1. 运行gh auth status，确保你已登录且登录的主机（如 github.com）正确。
  2. 检查令牌权限：确保输出中包含read:project和project作用域。如果没有，需要重新登录：gh auth logout然后gh auth login，在权限选择环节确保勾选“Project”（项目）。
  3. 验证项目URL：确保你复制的是Projects v2的URL，格式正确。尝试用浏览器直接打开该URL确认可访问。
  4. 组织权限：如果你初始化的是组织下的项目，确保你的GitHub账号在该组织中有足够的权限（至少是read权限，write权限才能更新状态）。

问题2：ghpm-work过程中，AI似乎“忘记”了之前的上下文或阶段。

• 症状：AI开始回答与当前Issue无关的问题，或者重复询问已经澄清过的需求。
• 排查步骤：
  1. 检查钩子安装：确认Claude Code的钩子已正确安装。查看~/.claude/settings.local.json，确认其中包含来自ghpm的hooks配置。
  2. 检查会话文件：查看.ghpm/sessions/<issue-number>.json，确认phase字段是否正确记录了当前阶段（如"planning"）。
  3. 手动提供上下文：如果钩子失效，在每次与AI开始重要对话前，手动输入：“当前正在处理Issue # ，阶段是 。” 这可以临时补救。
  4. 重启AI代理：有时AI代理的上下文窗口可能已满或出现混乱，尝试重启你的Claude Code或编辑器。

问题3：项目看板上的状态没有自动更新。

• 症状：本地执行了ghpm-work，但GitHub网页上项目的状态还是旧的。
• 排查步骤：
  1. 检查prompts配置：确认对应操作（如status_sync）没有被设置为"skip"。
  2. 查看终端输出：ghpm-work的每个步骤都会在终端打印日志，确认是否有“Updating project status to 'In Progress'...”这样的成功信息。如果没有，可能是规则未触发。
  3. 检查conventions.status_sync规则：确保规则条件匹配当前Issue的状态。例如，规则是“从Todo改为In Progress”，但Issue当前状态是Backlog，则不会触发。
  4. 手动刷新缓存：运行ghpm-view .（查看所有项）会强制刷新本地缓存，但状态更新是写操作，不依赖缓存。最直接的是用ghCLI 手动更新状态以测试权限：gh project item-edit <item-id> --field status="In Progress"。

问题4：分支命名不符合预期。

• 症状：创建的分支名是42/some-title而不是预期的feat/42/some-title。
• 排查步骤：
  1. 仔细检查conventions.branch规则描述：确保描述清晰无歧义。AI对自然语言的理解有时会有偏差。尝试将规则写得更结构化：“分支模式：{type}/{number}/{slug}。确定type的规则：如果标签包含'feature'，则type='feat'；如果标签包含'bug'，则type='fix'；否则type='chore'。”
  2. 检查Issue标签：确认你的Issue上确实有预期的标签（如feature）。
  3. 查看会话文件：在.ghpm/sessions/xx.json中，搜索branch或proposed_branch字段，看看AI当时解析出了什么信息，这有助于调试规则。

问题5：ghpm-suggest推荐的任务总是不合心意。

• 症状：推荐的任务要么太难，要么不是我负责的模块。
• 解决方案：
  • 使用约束参数：这是最直接的方式。ghpm-suggest “前端 且 优先级高”。
  • 优化项目字段：确保你的项目使用了“优先级”、“组件/模块”、“估算点”等字段，并且这些字段的值是准确、一致的。ghpm-suggest的底层逻辑会依赖这些字段。
  • 理解其局限性：suggest是一个基于简单规则和缓存的推荐系统，它无法理解任务的复杂技术上下文或你当下的心流状态。把它当作一个高效的过滤器，而不是决策者。

5.3 实战心法与最佳实践

经过一段时间的深度使用，我总结出一些能让ghpm发挥最大效能的“心法”。

1. 从“半自动”模式开始不要一开始就把所有prompts都设为auto。建议在熟悉流程的初期，对所有关键操作保持prompt，观察AI会做什么、怎么做。几轮之后，你对它的行为模式建立了信任，再将那些你觉得可靠、低风险的操作改为auto。对于draft_pr这类产生外部影响的操作，我建议长期保持prompt，作为最后一道人工检查关卡。

2. 精心雕琢你的“约定”(Conventions)conventions是你的团队知识库的文本化。花时间与团队一起讨论并精炼这些规则。好的约定应该是：

• 明确无歧义：避免“通常”、“可能”这类模糊词汇。
• 可执行：AI能理解并转化为具体操作。
• 保持更新：当团队工作流变化时，及时更新conventions。

3. 利用会话文件进行复盘与交接.ghpm/sessions/目录下的JSON文件是宝藏。定期回顾完成的会话，你可以分析：

• 效率：每个Issue在各个阶段停留了多久？
• 决策质量：记录的决策是否准确捕捉了关键点？
• AI协作模式：在哪些环节AI提供了最大帮助？哪些环节仍需大量人工干预？ 当需要将未完成的任务交接给另一位同事时，你只需要让他也安装ghpm，他就能通过会话文件立刻了解该任务的所有历史上下文、决策和当前进度，交接成本极大降低。

4. 将ghpm融入团队仪式在每日站会时，可以快速运行ghpm-status来同步进度。在迭代规划会上，使用ghpm-suggest结合优先级和依赖关系来挑选任务。鼓励团队成员在完成ghpm-work后，将其产生的决策评论作为PR描述的一部分，让代码审查者能快速理解设计背景。

5. 接受不完美，保持主导权ghpm和AI是强大的辅助，但不是替代品。它有时会误解约定，推荐不合适的任务，或者生成的计划有瑕疵。这很正常。作为开发者，你始终是工作的主导者。ghpm的价值在于它自动化了那些繁琐、机械的部分，并提供了一个结构化的框架来嵌入AI的能力，从而让你能更专注于真正需要创造力和判断力的核心开发工作。把它当作一个不知疲倦、知识渊博的初级搭档，而你，始终是那个把握方向的资深工程师。