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 CLIgh因此运行前提是已安装 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 版本号 v3pre-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并生成基础.gitignorereposDir/globalDir仓库专属笔记与跨仓库笔记的目录名repoMappings代码仓库路径 → 笔记子目录名的映射profiles多笔记仓库支持不同组织上下文个人项目、不同客户可各用一套 thoughts 仓库。若模板缺失时命令提示thoughts 初始化不完整对应的修复命令正是humanlayer thoughts init详见 hlyr/src/commands/thoughts.ts 中的命令注册。与相邻命令的协作commit、ci_describe_prdescribe_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 系统负责模板与成果的双向沉淀。落地实践如何在你的仓库启用这套工作流环境准备安装 HumanLayer CLInpm install -g hlyr与 GitHub CLIgh并通过gh auth login完成认证初始化 thoughts 系统humanlayer thoughts init需要代码仓库已git init初始化 Claude Code 配置humanlayer claude init选择复制commands类别该命令源码见 hlyr/src/commands/claude/init.ts创建团队 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 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 CLIgh因此运行前提是已安装 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 版本号 v3pre-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并生成基础.gitignorereposDir/globalDir仓库专属笔记与跨仓库笔记的目录名repoMappings代码仓库路径 → 笔记子目录名的映射profiles多笔记仓库支持不同组织上下文个人项目、不同客户可各用一套 thoughts 仓库。若模板缺失时命令提示thoughts 初始化不完整对应的修复命令正是humanlayer thoughts init详见 hlyr/src/commands/thoughts.ts 中的命令注册。与相邻命令的协作commit、ci_describe_prdescribe_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 系统负责模板与成果的双向沉淀。落地实践如何在你的仓库启用这套工作流环境准备安装 HumanLayer CLInpm install -g hlyr与 GitHub CLIgh并通过gh auth login完成认证初始化 thoughts 系统humanlayer thoughts init需要代码仓库已git init初始化 Claude Code 配置humanlayer claude init选择复制commands类别该命令源码见 hlyr/src/commands/claude/init.ts创建团队 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考