Payload 的 AI 问题分析工作流：analyze-issue 命令解析与配套工程实践

Payload 的 AI 问题分析工作流：analyze-issue 命令解析与配套工程实践

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload

Payload 开源仓库在.claude/commands/目录下内置了一套面向 Claude Code 的项目级 AI 命令，其中analyze-issue命令定义了"从 GitHub issue 到修复方案"的标准化分析流程：获取并解析 issue 数据、深入代码库定位根因、输出一份不写任何代码的综合修复计划。本文以 analyze-issue.md 为主体，逐条拆解其 8 步工作流与 8 要素计划结构，并结合 settings.json 的权限白名单、PostToolUse 钩子、同级 triage 命令以及 CLAUDE.md 中的工程约定，说明这套"只出方案、不写代码"的流程是如何在当前仓库中被支撑和落地的。读完本文，你可以完整复现 Payload 团队处理 issue 的分析方法，并理解其命令体系背后的设计取舍。

一、analyze-issue 命令的定位：一个"只出方案"的项目级命令

analyze-issue.md 是一个 Claude Code 项目级 slash command 文件，采用 YAML frontmatter + Markdown 提示词的结构。frontmatter 只有两个字段，但各有明确职责：

命令正文第一句即确立了核心约束（见 analyze-issue.md）：

Deep-dive on the GitHub issue provided in $ARGUMENTS. Find the problem and generate a plan.Do not write code.

这里的$ARGUMENTS是 Claude Code 的命令参数注入变量，会替换为用户传入的 issue 编号或 URL。紧接着还有一条防御性规则：

PROMPT for the issue number or URL if not provided, and stop here.

即：参数缺失时必须向用户提问并立即停止，而不是自行猜测——这条规则在文末再次以"ONLY CREATE A PLAN. DO NOT WRITE ANY CODE"的形式被强化。这种"参数缺失即停、产出限定为方案"的双重约束，是整条命令设计的灵魂：它把 Agent 严格限制在理解问题 + 制定策略的决策层，把写代码的动作推迟到人工评审方案之后。

二、8 步分析工作流逐条解析

命令正文用编号列表定义了完整的 8 步流程（见 analyze-issue.md），下面逐步展开其要点与实际含义。

Step 1：用ghCLI 拉取 issue 的结构化数据

gh issue view $ARGUMENTS --json author,title,number,body,comments,labels

这是整个流程的数据入口。gh issue view配合--json参数可以按需选择字段，命令显式指定了 6 个字段：author（报告者）、title、number、body（issue 描述正文）、comments（全部评论）、labels（标签）。选择这些字段是有讲究的：author和comments用于还原"问题是怎么被发现的、维护者追问了什么"，labels则提供了问题域的先验分类（如 bug、某类 feature），可帮助 Agent 快速缩小代码搜索范围。

这一命令能在 Agent 中无确认执行，依赖于仓库权限白名单——settings.json 的permissions.allow中明确列出了Bash(gh issue view:*)，Agent 调用它时不会触发逐次授权弹窗。

Step 2：解析 JSON，提取四个维度

从 JSON 响应中提取：标题与编号、描述（body）、带作者的全部评论、标签。这一步的意义在于把非结构化的 issue 讨论整理成可分析的上下文——尤其是评论区往往包含报告者补充的复现步骤、版本信息和维护者的初步判断，只读 body 而忽略 comments 会丢失大量关键信息。

Step 3–4：格式化并复核 issue 上下文

第 3 步要求"clearly format the issue context"，第 4 步要求"review the issue context and details"。这两步看似冗余，实际是在 Agent 动身去读代码之前，强制其先把问题陈述成一段自洽的"故障现象 + 触发条件 + 期望行为"。这一步的产出质量直接决定后续代码检索的方向是否跑偏。

Step 5：深入阅读相关代码库

Examine the relevant parts of the codebase. Analyze the code thoroughly until you have a solid understanding of how it works.

注意约束词是 "until you have a solid understanding"——命令不指定"读几个文件"，而是以"真正理解其工作原理"为完成标准。在 Payload 这样的 monorepo 中，这一步要求 Agent 掌握仓库的目录语义：packages/payload是核心 CMS 逻辑、packages/db-*是数据库适配器、test/<feature>/是按功能切分的测试套件（每个目录含独立的轻量config.ts），这些结构说明来自 CLAUDE.md，是 Agent 定位相关代码时的路线图。

Step 6：批判性地解释问题与根因

There is no guarantee the issue is valid, so be critical and thorough in your analysis.

这是该命令区别于"机械复现型"排查的精髓：issue 的陈述不保证成立。报告者看到的"bug"可能源于误用配置、环境差异或预期不符。因此方案必须包含对"问题是否真实存在"的论证，而非默认成立后再找修复点。

Step 7：产出覆盖 8 个维度的综合修复计划

这是命令的最终交付物，也是信息密度最高的部分。计划必须包含（见 analyze-issue.md）：

1. Required code changes—— 需要修改的代码（定位到模块/文件层面，而非直接写 diff）；
2. Potential impacts on other parts of the system—— 对其他部分的潜在影响；
3. Necessary tests to be written or updated—— 需要新增或更新的测试；
4. Documentation updates—— 文档更新；
5. Performance considerations—— 性能考量；
6. Security implications—— 安全影响；
7. Backwards compatibility (if applicable)—— 向后兼容性（如适用）；
8. Reference link to the source issue and any related discussions—— 源 issue 及相关讨论的引用链接。

这 8 个维度并非随意罗列：它们恰好对应 Payload 仓库评审一个修复时的真实关注点。例如"安全影响"对应 CLAUDE.md 中强调的访问控制红线——Payload 的 server functions、views、endpoints 中必须使用overrideAccess: false并显式传入user，否则操作会绕过所有访问控制，这被明确标注为 security vulnerability。一个合格的 analyze-issue 计划若涉及这些入口，就必须在"安全影响"一节对照这条规则自查。再如"必要测试"一项，需要遵循仓库既定的测试结构：每个test/<feature>/目录包含轻量的config.ts、Vitest 集成测试int.spec.ts、Playwright 端到端测试e2e.spec.ts和生成的payload-types.ts（见 CLAUDE.md），而 issue 的复现约定则是把最小配置放进test/_community/目录并用pnpm dev _community启动（见 ISSUE_GUIDE.md）。

Step 8：深度思考边缘情况

Think deeply about all aspects of the task. Consider edge cases, potential challenges, and best practices.

最后一步要求主动枚举边缘情况、潜在难点与最佳实践——例如 Payload 是多数据库适配器（MongoDB、Postgres、SQLite 等）架构，一个查询层面的修复可能只在一个适配器上成立，"对其他部分的潜在影响"一节就需要覆盖适配器差异。

三、"方案优先"约束的工程支撑

单靠提示词不足以让"只出方案"可靠执行。Payload 仓库在命令之外还有三层工程设施，与analyze-issue命令配套构成完整工作流。

1. 权限白名单：只开放分析所需的能力

settings.json 的permissions.allow是一份细粒度白名单，与 analyze-issue 的信息采集步骤一一对应：

• Bash(gh issue view:*)、Bash(gh pr view:*)、Bash(gh release view:*)、Bash(gh run list:*)、Bash(gh run view:*)—— 对应"拉取 issue/PR/发布/CI 数据"；
• Bash(git log:*)、Bash(git diff:*)、Bash(git show:*)、Bash(git blame 相关命令)等 git 只读命令 —— 对应 Step 5 追溯"相关代码何时引入、哪个 PR 改动过"；
• Bash(pnpm run:*)、Bash(pnpm list:*)、Bash(pnpm why:*)—— 允许运行构建/测试/依赖分析命令来验证判断，但整体仍以分析型命令为主；
• WebFetch(domain:payloadcms.com)、WebFetch(domain:docs.aws.amazon.com)等 —— 允许查阅官方文档与第三方 SDK 文档；
• Skill(superpowers:systematic-debugging)、Skill(superpowers:writing-plans)等 —— 通过 superpowers 插件市场（在extraKnownMarketplaces中配置，来源为obra/superpowers仓库）引入的系统化调试与写计划技能。

这种"命令级"的授权（如Bash(gh issue view:*)而非Bash(gh:*)）意味着 Agent 即便失控，其破坏面也被限制在白名单内——这与 analyze-issue"不写代码"的软约束形成了硬约束兜底。

2. PostToolUse 钩子：写文件即格式化

settings.json 注册了一个PostToolUse钩子：每当 Agent 执行Write工具后，自动运行 .claude/hooks/post-write-format.sh。该脚本从 stdin 读取 JSON、提取file_path，再按文件类型分派格式化：package.json走sort-package-json，.yml/.json与.md/.mdx走 prettier（md 额外尝试 markdownlint），.js/.ts/.tsx走eslint --fix+ prettier。对 analyze-issue 工作流而言，它的价值在于：即使流程被扩展为"顺手落盘方案文档"（如同级命令 triage 会把结果存到.claude/artifacts/目录），产出物的格式一致性也由钩子自动保证，Agent 无需关心。

3. 同级命令：triage 与 analyze-issue 的分工

.claude/commands/下还有 triage.md 和 respond-to-discussion-features.md，三者构成递进关系：

• triage.md：快速分诊。输出结构化的裁决报告——Verdict: Valid | Invalid | Needs Info加Confidence: High | Medium | Low，列出Code Locations（path/file.ts:123形式）与简略的Fix Direction，并自动存盘到.claude/artifacts/triage-<issue-number>.md。值得注意的是它的 frontmatter 带allowed-tools: Bash(gh issue view:*), Task, TodoWrite, Write, AskUserQuestion，用工具白名单进一步收紧了分诊阶段的行动面；结尾通过AskUserQuestion（multiSelect）让用户选择"写失败测试 / 生成完整修复计划 / 到此为止"。
• analyze-issue.md：深度分析 + 完整方案，即本文主体，是 triage 判定 "Valid" 之后的下一步。
• respond-to-discussion-features.md：面向社区的另一面——用gh release view抓取近 N 个月 release notes 中的feat:/fix:条目，与 open 状态的功能请求 discussion 做关键词+语义匹配，生成回帖草稿存到.claude/artifacts/。

三者共同点是用.claude/artifacts/目录沉淀产物、用TodoWrite显式化进度（triage 要求"upfront 建 4 步待办"），体现了 Payload 对 Agent 工作流"可观察、可中断、可续接"的一致要求。

四、方案落地时要遵守的仓库约定

analyze-issue 计划中的"Required code changes"和"Tests"最终会由人（或后续 Agent 执行）转成 PR，因此在 Payload 仓库里，一份可执行的方案还应预设以下既有约束（均来自 CLAUDE.md）：

• API 风格：函数参数一律使用对象参数（fn({ name }: { name: string })），以保障向后兼容——这直接影响计划中"backwards compatibility"一节如何评估破坏面；
• 测试规范：集成测试必须使用test/__helpers/int/vitest.ts提供的test.suite({ config: './config.ts' })包装器，从 hook 参数读取payload/restClient，禁止手动初始化 Payload 或自加数据库重置钩子；测试命名以 "should" 开头；
• 提交格式：遵循 Conventional Commits，PR 标题为<type>(<scope>): <title>，scope 与包名对应（如feat(db-mongodb): ...、fix(ui): ...），合并时 squash 为一条；
• 运行环境前提：Node >=24.15.0、pnpm ^11.9.0（见 CLAUDE.md）。

方案中若涉及"复现"，则按 ISSUE_GUIDE.md 的社区约定执行：在test/_community/中用尽可能少的 fields/collections 重建最小配置（config.ts+ 可选int.spec.ts/e2e.spec.ts），pnpm dev _community启动 admin UI 手工复现，pnpm test:int _community跑集成测试。

五、如何在自己项目中复刻这套流程

Payload 的做法可以抽象为三步，迁移到任何使用 Claude Code 的仓库成本都很低：

1. 建命令文件：在仓库.claude/commands/下新建<command-name>.md，frontmatter 写description与argument-hint，正文写清：数据入口命令（如gh issue view ... --json ...）、分步流程、输出结构（强制小节）、停止条件（参数缺失/命令失败/信息不足时"ask for clarification rather than guessing"）。analyze-issue.md 本身就是最小可复制范本。
2. 配权限白名单：在.claude/settings.json的permissions.allow中只放行分析所需的Bash(...)前缀与文档域名的WebFetch，避免Bash(gh:*)这类过宽授权；
3. 用钩子保格式：参照 post-write-format.sh 注册 PostToolUse 钩子，按扩展名分派 prettier/eslint，保证 Agent 产出物与人类提交物格式一致。

另外，Payload 还在payloadnpm 包内随包发布了 agent skill（安装后位于node_modules/payload/skills/payload/），使 AI 助手获得与所装 Payload 版本严格匹配的 API 指引，其接入方式（在根目录添加AGENTS.md/CLAUDE.md指向该 skill）记录在 docs/getting-started/ai-tooling.mdx——这是"让 Agent 的版本知识与项目实际版本对齐"的另一条路线，可与本文的命令体系配合使用。

小结

analyze-issue.md 的价值不在提示词本身，而在于它与 settings.json 的权限白名单、PostToolUse 格式化钩子、triage.md 分诊命令以及 CLAUDE.md 工程约定形成的组合：ghJSON 采集保证了输入结构化，"批判性验证 issue 有效性"防止了无效修复，8 要素计划结构对齐了仓库的真实评审维度，而权限与钩子则让"只出方案"这条软约束具备了硬兜底。理解这套组合，就能把握当前 Payload 仓库中 AI 辅助开发工作流的完整面貌。

【免费下载链接】payloadPayload is the open-source, fullstack Next.js framework, giving you instant backend superpowers. Get a full TypeScript backend and admin panel instantly. Use Payload as a headless CMS or for building powerful applications.项目地址: https://gitcode.com/GitHub_Trending/pa/payload