HumanLayer 自动化 PR 描述生成基于 Claude Code Slash Command 与 Thoughts 系统的完整工作流【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer导读ci_describe_pr是 HumanLayer 仓库内置的一个 Claude Code slash command它让 AI 编码助手能够自动分析当前分支的 Pull Request读取仓库团队约定的 PR 描述模板生成符合规范、包含验证清单与变更日志的完整 PR 描述并将其同步到 HumanLayer Thoughts 系统中归档最后直接回写 GitHub PR。读完本文你将掌握这套模板驱动 变更分析 自动验证 归档同步的 PR 描述生成流水线并能复用到你自己的仓库中。一、命令是什么一个模板驱动的 PR 描述生成器ci_describe_pr的定义文件位于 .claude/commands/ci_describe_pr.md它属于 Claude Code 的自定义 Slash Command与仓库中 describe_pr.md、commit.md 等命令并列。该命令的核心设计哲学是模板驱动不凭空生成描述而是严格读取仓库内的pr_description.md模板逐节填写本地归档生成的描述先写入 Thoughts 系统的thoughts/shared/prs/目录再同步到中央 thoughts 仓库而非直接丢弃验证闭环模板中如何验证How to verify it清单内的可运行命令会被实际执行通过则勾选- [x]失败则保留- [ ]并附说明跨仓库可用命令本身不绑定特定仓库始终读取当前仓库本地的模板。整个命令包含 9 个步骤读取模板 → 识别 PR → 检查已有描述 → 收集 PR 信息 → 深度分析变更 → 处理验证要求 → 生成描述 → 保存并同步 → 更新 PR。二、前置条件HumanLayer Thoughts 系统与 PR 描述模板命令的第一步就是检查thoughts/shared/pr_description.md是否存在。这个路径是 Thoughts 系统的标准目录结构之一意味着使用该命令前必须完成 Thoughts 初始化。2.1 Thoughts 系统的目录结构执行humanlayer thoughts init后当前代码仓库会生成一个thoughts/目录它通过符号链接映射到独立的 thoughts git 仓库。根据 hlyr/THOUGHTS.md 的说明结构如下your-project/ ├── src/ ├── tests/ ├── thoughts/ # 由 Thoughts 系统生成 │ ├── alice/ # → ~/thoughts/repos/your-project/alice个人笔记 │ ├── shared/ # → ~/thoughts/repos/your-project/shared团队共享 │ ├── global/ # → ~/thoughts/global跨仓库笔记 │ │ ├── alice/ │ │ └── shared/ │ ├── searchable/ # AI 搜索用的硬链接索引自动生成 │ └── CLAUDE.md # 自动生成的 AI 上下文说明 └── .gitignore其中shared/目录正是团队共享笔记的存放位置pr_description.md模板放在thoughts/shared/下意味着 PR 描述模板属于团队共享级别的资料。中央 thoughts 仓库默认~/thoughts的对应路径为~/thoughts/repos/{repo_name}/shared/pr_description.md。2.2 初始化 Thoughts 并创建模板# 1. 初始化 Thoughts在代码仓库根目录执行 humanlayer thoughts init # 2. 手动创建 PR 描述模板 # 编辑 thoughts/shared/pr_description.md写入团队约定的模板如果thoughts/shared/pr_description.md不存在命令会提示用户Thoughts 设置不完整需要先创建该模板文件。这也是使用该命令前最需要确认的前置条件——模板决定了最终 PR 描述的章节结构与验收标准。2.3 Thoughts 命令族全景ci_describe_pr在最后一步依赖humanlayer thoughts sync归档描述。整个 Thoughts 命令族在 hlyr/src/commands/thoughts.ts 中注册包括命令作用humanlayer thoughts init初始化当前仓库的 Thoughts--force强制重配--directory跳过交互--profile指定配置档案humanlayer thoughts uninit移除当前仓库的 Thoughts 设置humanlayer thoughts sync手动同步 Thoughts 到中央仓库-m, --message指定提交信息humanlayer thoughts status查看 Thoughts 配置、仓库映射、git 状态与未提交变更humanlayer thoughts config查看/编辑配置--edit用$EDITOR打开--json输出 JSONhumanlayer thoughts profile create/list/show/delete管理多套 Thoughts 配置档案三、识别目标 PR从当前分支或 PR 列表中定位命令的第二步确定要为哪个 PR 生成描述# 先检查当前分支是否已有关联 PR gh pr view --json url,number,title,state 2/dev/null # 若当前分支无 PR或正处在 main/master 上列出最近的 PR 供用户选择 gh pr list --limit 10 --json number,title,headRefName,author执行逻辑为优先尝试从当前分支获取关联 PR若失败无 PR 或位于主干分支则列出最近 10 个 PR 并询问用户选择哪一个。该步骤产出的 PR 编号number将贯穿后续所有步骤包括归档文件名的命名。四、检查既有描述增量更新而非重复生成在生成新描述前命令会检查归档目录中是否已存在历史描述# 检查 thoughts/shared/prs/{number}_description.md 是否已存在若文件已存在读取旧描述告知用户将执行更新操作并对比分析自上次描述以来发生的新变更若不存在视为全新 PR从头生成。这一设计保证了同一个 PR 多次迭代如 review 后的二次修改时描述能够增量演进而不是被覆盖丢失。五、全方位收集 PR 信息命令通过 GitHub CLI 一次性拉取 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并选择正确的仓库之后再重试。六、深度分析变更从 diff 到架构影响这一步是命令的思考核心要求对代码变更进行深入分析通读整个 diff理解每个变更的目的与影响面读取 diff 中引用但未展示的上下文文件例如被调用的函数定义、被修改模块的周边代码区分用户可见变更与内部实现细节——用户可见变更需要重点描述其影响识别破坏性变更或迁移要求并在描述中突出标注对于涉及多个组件前端、后端、数据库、SDK 等的 PR按组件维度组织描述内容。这一步骤的价值在于PR 描述不应只是 diff 的罗列而应回答为什么改、改了什么、对谁有影响、是否需要迁移。七、处理验证要求命令级验证清单闭环模板中的如何验证它How to verify it章节通常包含一组 checklist。命令会逐个处理验证类型处理方式可运行的命令如make check test、npm test实际执行通过勾选- [x]失败保留- [ ]并注明失败原因需要人工测试UI 交互、外部服务保留- [ ]并在注释中标注需人工验证无法完成的验证步骤在描述中如实记录验证清单的执行结果会原样体现在最终 PR 描述中并在命令结束时提醒用户若有未勾选的验证项合并前需补齐。这使 PR 描述不仅是一份说明更是一份可追溯的验收记录。八、生成描述逐节填写模板命令会严格按照模板的每个章节填写内容针对模板中的每个问题/章节给出具体回答明确写出解决的问题与作出的变更涉及用户影响的变更重点描述其体验影响技术细节放入对应技术章节撰写简洁的 changelog 条目确保所有 checklist 项均被勾选或给出解释。写作准则来自命令文件的 Important notes描述应详尽但简洁、易于扫读为什么与做了什么同样重要破坏性变更与迁移说明需置于显眼位置。九、保存、同步与更新 PR完整闭环9.1 写入归档并同步# 将完成的描述写入 Thoughts 归档目录 # 写入路径thoughts/shared/prs/{number}_description.md # 同步 Thoughts 目录到中央仓库 humanlayer thoughts synchumanlayer thoughts sync的底层实现在 hlyr/src/commands/thoughts/sync.ts 中其执行序列为在中央 thoughts 仓库执行git add -A检测是否有变更有变更则以-m提供的消息或默认时间戳消息执行git commit提交后执行git pull --rebase拉取远端更新——若检测到合并冲突输出包含CONFLICT (、Automatic merge failed、Patch failed at等特征串会明确提示用户手工解决冲突后再git rebase --continue并重新 sync若存在origin远端尝试git push推送失败仅警告不中断可能需手动推送无远端则提示未配置远端。此外sync 还会重建thoughts/searchable/硬链接索引目录方便 AI 搜索工具在无需跟随符号链接的情况下检索全部 thoughts 内容见 hlyr/src/commands/thoughts/sync.ts 中createSearchDirectory的实现它遍历符号链接并生成硬链接跳过CLAUDE.md与隐藏文件。9.2 回写 GitHub PRgh pr edit {number} --body-file thoughts/shared/prs/{number}_description.md最后一步将归档的描述文件直接作为 PR 正文写入 GitHub并确认更新成功。至此整个流程形成闭环分析 → 生成 → 归档 → 同步 → 回写。十、Thoughts 配置参考理解归档路径的来源ci_describe_pr依赖的归档路径全部由 Thoughts 配置驱动。Thoughts 配置存放在 HumanLayer 全局配置文件中默认~/.config/humanlayer/humanlayer.json见 hlyr/src/config.ts 中getDefaultConfigPath的实现结构如下{ api_key: ..., thoughts: { thoughtsRepo: ~/thoughts, reposDir: repos, globalDir: global, user: alice, repoMappings: { /Users/alice/projects/app: app_thoughts, /Users/alice/projects/api: api_backend } } }关键字段字段说明thoughtsRepo中央 thoughts git 仓库路径默认~/thoughts支持~展开见 hlyr/src/thoughtsConfig.ts 中expandPathreposDir仓库级 thoughts 的子目录名默认reposglobalDir全局 thoughts 子目录名默认globaluser当前用户名不能命名为global该名称被保留repoMappings代码仓库路径 → thoughts 目录名的映射可升级为{ repo: ..., profile: ... }对象格式以关联 profileprofiles可选的多套配置档案每套含独立的thoughtsRepo/reposDir/globalDir因此thoughts/shared/prs/{number}_description.md的实际落盘位置是{thoughtsRepo}/{reposDir}/{映射名}/shared/prs/{number}_description.md而pr_description.md模板位于同一shared/目录下。目录创建逻辑可参考 hlyr/src/thoughtsConfig.ts 中的createThoughtsDirectoryStructure会创建user/与shared/两个子目录并写入 README。十一、使用建议与注意事项11.1 关键注意事项先确认模板存在首次使用前务必完成humanlayer thoughts init并创建thoughts/shared/pr_description.md否则命令会中止并提示设置不完整gh CLI 依赖命令依赖 GitHub CLIgh且需先通过gh auth login完成认证出现远端仓库未设置错误时执行gh repo set-default多组件 PR涉及多个组件的变更按组件组织描述便于 reviewer 快速定位验证步骤如实记录无法自动验证的步骤明确标注需人工测试不能假装通过归档即资产thoughts/shared/prs/中的描述会随humanlayer thoughts sync提交进中央 thoughts 仓库形成可检索的 PR 历史档案——这正是把描述写入 thoughts 而非临时文件的设计意图。11.2 与仓库其他命令的配合在 docs/workshop.mdx 的实践指南中该工作流与 .claude/commands/commit.md 配合使用先借/commit生成提交信息并推送分支再调用/describe_pr生成 PR 描述。ci_describe_pr是这一流程的 CI/脚本化变体二者的模板与归档约定完全一致。十二、小结ci_describe_pr是一个典型的AI 编码助手 团队规范 知识管理三合一工作流它用模板约束 AI 的输出结构用验证清单保证描述的真实性用 Thoughts 系统实现跨仓库、可检索的归档。如果你想在自己的仓库复刻这套方案核心只需三步初始化humanlayer thoughts、在thoughts/shared/放置pr_description.md模板、按.claude/commands/ci_describe_pr.md的九步流程配置命令即可。对应的命令注册与实现细节可进一步阅读 hlyr/src/commands/thoughts.ts 与 hlyr/src/commands/thoughts/sync.ts 加深理解。【免费下载链接】humanlayerThe best way to get AI coding agents to solve hard problems in complex codebases.项目地址: https://gitcode.com/GitHub_Trending/hu/humanlayer创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考