HumanLayer 仓库实践：用 Claude Code 自定义命令 `describe_pr` 自动化生成高质量 PR 描述

HumanLayer 仓库实践：用 Claude Code 自定义命令describe_pr自动化生成高质量 PR 描述

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer

导读

Pull Request 描述是代码评审的第一道门面，也是后续回溯变更意图的关键资料，但"写清楚"往往比写代码更耗神。HumanLayer 仓库在.claude/commands/describe_pr.md中内置了一个 Claude Code 自定义命令（slash command），它把"生成 PR 描述"固化为一套九步工作流：读取团队模板 → 定位目标 PR → 拉取 diff 与提交历史 → 深入分析变更 → 运行验证检查 → 按模板成文 → 保存到 thoughts 笔记库 → 回写 PR。本文将以该命令文件为骨架，结合仓库中 hlyr CLI 的 thoughts 系统与 git hooks 源码，讲清这套"模板驱动 + 笔记库同步 + 命令行回写"的完整机制，读完后你可以直接在自己的 Claude Code 环境中复刻并定制它。

命令的定位：把 PR 描述从"自由发挥"变成"模板流水线"

describe_pr是 HumanLayer 仓库 .claude/commands 目录下的一个 Claude Code 自定义命令。Claude Code 会扫描项目.claude/commands/下的 Markdown 文件，把文件名注册为斜杠命令（如/describe_pr）。命令文件的 YAML frontmatter 提供描述信息：

--- description: Generate comprehensive PR descriptions following repository templates ---

这些命令与 agents、settings 一起，由humanlayer claude init命令批量复制到任意项目。从 hlyr/src/commands/claude/init.ts 的源码可以看到，claude init支持交互式选择复制commands、agents、settings三类内容，其中 commands 目录包含 30 个左右的工作流命令（规划、CI、研究、代码生成、测试等），describe_pr就是其中之一。这意味着：这套 PR 描述工作流不是 HumanLayer 独有，而是可以一键分发到团队每个仓库的标准化资产。

命令的核心设计理念是"跨仓库通用、模板本地读取"——命令本身只定义流程，具体要写哪些章节、遵守什么规范，全部由当前仓库 thoughts 目录下的模板文件决定。

九步工作流逐段拆解

describe_pr命令把整个生成过程划分为九个明确步骤，每一步都有可执行的 CLI 操作与判定逻辑。

第一步：读取 PR 描述模板（模板缺失时如何降级）

命令首先检查thoughts/shared/pr_description.md是否存在：

• 存在：通读模板，理解所有章节与要求；
• 不存在：告知用户其humanlayer thoughts初始化不完整，需要在thoughts/shared/pr_description.md创建 PR 描述模板。

这里体现了该命令与 HumanLayer thoughts 系统的强绑定：模板存放在shared/目录意味着它是团队共享的。根据 hlyr/THOUGHTS.md 的目录结构设计，thoughts/shared/通过符号链接指向中央 thoughts 仓库中repos/<project>/shared/，团队可以维护一份统一的 PR 描述规范（如"必须包含 How to verify it 检查清单""破坏性变更要突出标注"），让所有成员的 AI 助手都按同一标准产出。

第二步：定位要描述的 PR

命令按以下顺序确定目标 PR：

# 1. 检查当前分支是否关联了 PR gh pr view --json url,number,title,state 2>/dev/null # 2. 若无关联 PR，或位于 main/master 分支，列出最近的开放 PR gh pr list --limit 10 --json number,title,headRefName,author

当当前分支没有关联 PR、或正处于主分支时，命令会列出前 10 个开放 PR 并询问用户选择哪一个。整个过程依赖 GitHub CLI（gh），因此运行前提是已安装 gh 并通过认证。

第三步：检查是否已有描述

命令检查thoughts/shared/prs/{number}_description.md是否已存在：

• 存在：读取已有内容，并告知用户"将更新它"，同时思考自上次描述之后发生了什么变化；
• 不存在：从零生成。

这一步让命令具备增量更新能力——PR 迭代后可以复用旧描述作为上下文基础，而不是每次推倒重来。

第四步：收集完整的 PR 信息

命令依次获取以下数据：

# 完整 diff gh pr diff {number} # 提交历史 gh pr view {number} --json commits # 基础分支 gh pr view {number} --json baseRefName # PR 元数据 gh pr view {number} --json url,title,number,state

值得注意的错误处理细节：如果gh pr diff报"no default remote repository"错误，命令会指示用户运行gh repo set-default选择正确的仓库。这保证了在 fork 或新克隆场景下也能顺利工作。

第五步：深度分析变更（命令中最强调的一步）

命令要求对代码变更进行"ultrathink"级别的思考，并列出具体分析维度：

• 通读整个 diff；
• 读取 diff 中引用但未展示的相关文件以获得上下文；
• 理解每个变更的目的与影响；
• 区分面向用户的变化与内部实现细节；
• 识别破坏性变更或迁移需求。

这步是整个命令质量的分水岭——PR 描述的质量不取决于模板有多详尽，而取决于分析是否穿透了"改了什么"直达"为什么改、影响了谁"。

第六步：处理验证要求（checklist 自动化勾选）

命令读取模板中"How to verify it"章节的检查清单，并逐项处理：

验证类型	处理方式	示例
可运行的命令	直接执行，通过则勾选	make check test、npm test
失败的验证	保持未勾选并说明失败原因	- [ ]+ 失败说明
需要人工测试	保持未勾选并备注给用户	UI 交互、外部服务

同时文档要求"记录任何无法完成的验证步骤"。这一步把 PR 描述从"文字叙述"升级为可审计的验证记录，评审者看到- [x]就知道该验证项已被 AI 实际执行过。

第七步：按模板生成描述

生成阶段的要求非常具体：

• 逐节填满模板中的每个问题/章节；
• 具体说明解决的问题与做出的改动；
• 在相关位置突出用户影响；
• 技术细节放入对应章节；
• 撰写简洁的 changelog 条目；
• 确保所有 checklist 项都有明确状态（勾选或说明）。

第八步：保存并同步到 thoughts

# 将完成稿写入 thoughts 笔记库 # 路径：thoughts/shared/prs/{number}_description.md # 同步 thoughts 目录 humanlayer thoughts sync

写入thoughts/shared/prs/意味着 PR 描述不仅存在于 GitHub，还沉淀进了团队的知识库——每一条 PR 描述都成为可检索、可复用的变更记录。

第九步：回写 PR 并确认

gh pr edit {number} --body-file thoughts/shared/prs/{number}_description.md

命令会确认更新成功；若仍有未勾选的验证项，则提醒用户在合并前完成。

模板驱动的核心：thoughts 系统如何支撑这套流程

describe_pr依赖的thoughts/目录是 HumanLayer CLI 的开发者笔记管理系统的产物，其实现位于 hlyr/src/commands/thoughts/init.ts 与 hlyr/src/commands/thoughts/sync.ts。

thoughts 目录结构

初始化后，代码仓库会出现一个thoughts/目录，其中与describe_pr相关的关键部分是：

• thoughts/shared/→ 符号链接到中央笔记仓库的团队共享目录，PR 描述模板就放在这里；
• thoughts/shared/prs/→ PR 描述归档目录（命令运行时创建）；
• thoughts/searchable/→ 自动生成的硬链接目录，供 AI 搜索工具在不跟随符号链接的情况下检索全部笔记内容。

git hooks 自动同步与保护

从 thoughts/init.ts 的setupGitHooks函数可以看到，初始化时会向代码仓库安装两个 git hook（当前 hook 版本号 v3）：

• pre-commit hook：检测暂存区是否出现thoughts/路径，一旦出现立即git reset HEAD -- thoughts/并退出码 1，防止 thoughts 目录被误提交进代码仓库；
• post-commit hook：在每次提交后自动后台执行humanlayer thoughts sync --message "Auto-sync with commit: ..."，把 thoughts 变更同步到中央笔记仓库。

hook 安装逻辑还处理了与既有 hook 的共存（重命名为.old并继续调用）以及 worktree 场景（跳过自动同步以避免仓库边界混淆）。这意味着运行describe_pr后，thoughts/sync的同步不仅是手动命令，日常提交代码时笔记库也会自动保持最新。

sync 命令的同步语义

从 sync.ts 可见其完整流程：git add -A暂存所有变更 → 检查是否有待提交变更 → 提交（默认消息为Sync thoughts - <ISO 时间>）→git pull --rebase拉取远端（冲突时明确提示手动解决并git rebase --continue）→ 有远端时推送未推送的提交。这保证了多机器、多成员场景下团队共享模板能持续收敛。

配置结构与 profiles 扩展

describe_pr命令读取的模板路径位于 thoughts 配置的共享目录中。thoughts 配置整体存储于 HumanLayer 配置文件（hlyr/src/thoughtsConfig.ts 中定义结构），核心字段如下：

{ "thoughts": { "thoughtsRepo": "~/thoughts", "reposDir": "repos", "globalDir": "global", "user": "alice", "repoMappings": { "/Users/alice/projects/app": "app_thoughts" }, "profiles": {} } }

• thoughtsRepo：中央笔记仓库位置（默认~/thoughts），不存在时会自动git init并生成基础.gitignore；
• reposDir/globalDir：仓库专属笔记与跨仓库笔记的目录名；
• repoMappings：代码仓库路径 → 笔记子目录名的映射；
• profiles：多笔记仓库支持，不同组织上下文（个人项目、不同客户）可各用一套 thoughts 仓库。

若模板缺失时命令提示"thoughts 初始化不完整"，对应的修复命令正是humanlayer thoughts init（详见 hlyr/src/commands/thoughts.ts 中的命令注册）。

与相邻命令的协作：commit、ci_describe_pr

describe_pr并非孤立存在，.claude/commands 目录里还有两个强关联命令：

• commit.md：提交变更前先git status/git diff分析、向用户呈现提交计划并获得确认，且严禁添加 Claude 署名或 Co-Authored-By，提交作者归属用户本人；
• ci_describe_pr.md：与describe_pr内容几乎一致（仅 frontmatter 中文件名差异），说明这套工作流在 CI 语境下同样被使用。

三者的组合形成了"分析 → 提交 → 生成 PR 描述 → 回写"的完整闭环：commit保证提交质量与归属，describe_pr保证 PR 描述质量，而 thoughts 系统负责模板与成果的双向沉淀。

落地实践：如何在你的仓库启用这套工作流

环境准备

1. 安装 HumanLayer CLI（npm install -g hlyr）与 GitHub CLI（gh），并通过gh auth login完成认证；
2. 初始化 thoughts 系统：humanlayer thoughts init（需要代码仓库已git init）；
3. 初始化 Claude Code 配置：humanlayer claude init，选择复制commands类别（该命令源码见 hlyr/src/commands/claude/init.ts）；
4. 创建团队 PR 描述模板：在thoughts/shared/pr_description.md中定义章节（建议包含：变更概述、解决的问题、用户影响、技术细节、How to verify it 检查清单、changelog 条目、破坏性变更说明）。

使用流程

在 Claude Code 会话中运行/describe_pr，按提示确认目标 PR 后，AI 会完成"拉取信息 → 分析 → 验证 → 成文 → 同步 → 回写"的全流程。若gh未配置默认仓库，按提示执行gh repo set-default即可。

关键注意事项（源自命令文档）

• 模板优先：命令跨仓库可用，但永远读取当前仓库的本地模板——想改团队规范，改thoughts/shared/pr_description.md，而非命令文件；
• 聚焦 why 而非 what：描述应可快速扫读，变更原因与用户影响优先于实现罗列；
• 破坏性变更醒目：breaking changes 与迁移要求必须在描述中突出展示；
• 验证优先：凡是能运行的验证命令都要实际执行，人工验证项明确留给用户；
• 多组件 PR：涉及多个组件的变更要按组件合理组织描述结构。

小结

describe_pr展示了 Claude Code 自定义命令的一种高价值范式：命令文件只定义流程骨架，业务规范由团队共享模板注入，产物同时沉淀到笔记库与 PR 平台。它把"写 PR 描述"这一高频、易敷衍的开发任务，转化为可重复、可审计、团队对齐的自动化流水线。如果你在构建自己的 AI 编码工作流，这套"命令 + thoughts 模板 + gh CLI 回写"的组合值得直接借鉴——相关实现细节可继续阅读 hlyr/src/commands/thoughts/init.ts、hlyr/src/commands/thoughts/sync.ts 与 hlyr/THOUGHTS.md。

【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer