用 Goose Recipe 打造团队的 AI Playbook：从 Changelog 自动化到 PR 生成的研发效率实战

2026-09-07 12:05:56作者：滑思眉Philip

导读：本文以 Goose 的 Recipe（配方）机制为核心，系统讲解如何把研发团队中重复性的工作流——从生成 Changelog、编写 Pull Request 描述到日志排查——沉淀为可复用、可共享、可随团队演进的“AI 战术集（AI Play）”。读完本文，你将掌握 Recipe 的字段模型、从会话导出的两种创建方式、校验/运行/分享的完整 CLI 命令链，以及通过 GOOSE_RECIPE_GITHUB_REPO 搭建团队级 Recipe 库的落地方法，并拿到两份可直接复制运行的真实 YAML 配方。

为什么研发团队需要一本共享的“AI 战术书”

现代研发团队通常面临这些结构性挑战：

团队管理的系统与工具链条越来越复杂（IDE、版本控制、CI/CD、Issue 追踪器），要在其中既快又稳地交付软件并不容易；
新人加入后需要花大量时间学习团队的流程与工具习惯；
跨成员、跨项目的产出质量难以保持一致——就像一支球队要反复演练同一套战术，才能保证赛场上执行不走样；
大量“工具编排”类工作停留在个人经验里，没有沉淀为团队标准。

把流程标准化正是“体育队模式”给研发协作的启发：每个成员有明确角色，同时共享一本 Playbook（战术书）。在 AI 时代，这本 Playbook 的载体就是 Goose 的 Recipe——把一次成功的 Goose 会话固化成包含目标、指令与工具的「Play」，团队里的每个人（以及未来的自己）都能一键复现同一种高质量执行方式。

Recipe 是什么：一次会话如何变成团队资产

Goose 是一款开源的通用 AI Agent（Rust 实现，支持 CLI 与桌面端）。在 Goose 中，Recipe 是对“AI 应该如何协助完成任务”的可复用封装，它捕获了：

Instructions：定义 AI 的行为与能力边界（相当于 Agent 的使命声明）；
Prompt（可选）：加载后自动发送的首条消息，适合即开即用的具体任务；
Activities：加载后以可点击气泡展示的示例任务；
Extensions：Recipe 运行所需的扩展（MCP Server 或内置扩展），例如 GitHub MCP、PostgreSQL MCP 或内置 developer 扩展；
Parameters：带数据类型的可选参数，让同一个 Recipe 在不同仓库/场景下复用；
还可选地包含运行所用的 provider/model、重试与结构化输出配置。

从源码看，Recipe 的数据结构定义在 recipe/mod.rs：必填字段为 version（缺省 1.0.0）、title、description，且 instructions 与 prompt 至少二选一；其余为可选的 extensions、settings、activities、author、parameters、response（JSON Schema 结构化输出）、sub_recipes 与 retry。Recipe 文件本身是 YAML（.yaml/.yml）或 JSON（.json），解析层对 {{ 变量 }} 做模板替换，甚至支持 Jinja 风格的 {% if %} 条件逻辑（下文 PR 示例中可以看到）。

对于想要先理解“为什么叫 Recipe”的读者，可以顺带阅读团队早期的类比博客 A Recipe for Success: Cooking Up Repeatable Agentic Workflows，它用“厨房菜谱”解释 Recipe 如何沉淀可复用的 Agentic 工作流。

创建 Recipe：从当前会话导出，或从 YAML 白手起家

创建 Recipe 有两条路径：

路径一：从当前 Goose 会话导出（最省事） 当你在 Goose 中完成一个有价值的任务后，可以把这个会话的“配置”（工具、目标、指令）固化为 Recipe。桌面端在会话底部点击创建入口，系统会提示填写名称与描述，并自动生成可供你审阅、编辑的 activities 与 instructions；创建完成后会得到一个可直接分享给团队成员的链接。详细的分步操作（含从“配方模板”新建、编辑、导入 Recipe Library）参见 Reusable Recipes（会话级 Recipe 指南）。

路径二：在 CLI 会话中用 /recipe 生成骨架 在 Goose 会话中输入斜杠命令即可生成 recipe.yaml 到当前目录：

/recipe

如需自定义文件名：

/recipe my-custom-recipe.yaml

生成后打开文件，自行补充 instructions、prompt 与 activities。需要说明的是：Recipe 文件生成与编辑在 CLI 与桌面端都有完整支持，桌面端还提供“从模板创建”与“编辑已收藏 Recipe”的能力，具体交互可参考上面的会话指南。

用参数让 Recipe 更通用

为了让一个 Recipe 跨项目复用，可以给它声明参数。做法分两步：在 Recipe 内容里用 {{ variable_name }} 写模板变量，再在 parameters 段里声明每个变量的类型与要求。从 recipe/mod.rs 可以看到完整的类型体系：

input_type（参数类型）：string、number、boolean、date、file、select；
requirement（必要性）：required（必填）、optional（可选，必须提供 default 缺省值）、user_prompt（即使非交互模式也强制询问用户）；
default：可选参数的缺省值（file 类型禁止设置默认值，以避免导入用户敏感文件——这一点在源码校验中有硬性检查）；
options：当 input_type 为 select 时的候选项列表。

参数化 Recipe 的完整示例同样收录在 Reusable Recipes（会话级 Recipe 指南）中。

校验、运行与分享：CLI 命令全解析

Recipe 是“代码”，就要像代码一样被测试与校验。

校验 Recipe

写完后在终端运行校验，命令会检查：必填字段是否齐全、instructions/prompt 是否至少存在一个、参数定义是否与模板变量一一对应（缺定义或多余定义都会报错）、可选参数是否带默认值、引用的扩展是否存在且合法、JSON/YAML 语法是否正确。当前仓库 CLI 中，校验子命令位于 recipe 命令组下（定义见 cli.rs）：

goose recipe validate my-recipe.yaml

注：2025 年 5 月发布的原文博客中写作 goose validate <file>；从当前仓库的 CLI 命令定义看，validate 等 Recipe 工具已被收拢为 recipe 命令组的子命令，list/open/deeplink 均在此组之下。若你的 Goose 版本命令不识别，请以 goose recipe --help 为准。

校验的底层逻辑可以追溯到 validate_recipe.rs：它会解析模板参数、校验 retry 配置、用 jsonschema 编译 response.json_schema，并在解析阶段把用户友好化的错误信息（剥离了行列号）返回给上层。

运行 Recipe

使用 Recipe 最简单的方式是让它直接在一个新会话里执行：

goose run --recipe my-recipe.yaml

带参数运行时，可以用 --params key=value 预填模板变量；而 --interactive 交互模式会逐个提示你输入必填参数的值。

PRO TIP（原博客彩蛋）：可以设置一个环境变量指向团队共享的 GitHub Recipe 仓库，之后所有成员都能按名字直接运行 Recipe：
export GOOSE_RECIPE_GITHUB_REPO=github-username/repo-name
goose run --recipe <recipe-name>

分享 Recipe

桌面端创建 Recipe 后会直接给你一个可分享的链接（Recipe Link），同事点击即在其本地打开一个全新会话；
如果维护的是 YAML 文件，可以生成 deeplink 分享：

goose recipe deeplink my-recipe.yaml

该命令还支持预填参数值（--param key1=value1 --param key2=value2），方便你分享一个“已经填好上下文”的版本。CLI 中 open 子命令则可以把本地 Recipe 文件在 Goose Desktop 中打开。

隐私与隔离

分享链接对每个使用者是隔离的：用户之间不共享任何数据，你的 API Key 与敏感信息不会随 Recipe 泄露——Recipe 只捕获指令、活动、扩展配置与（可选的）模型设置，不包含全局/本地记忆、凭证与系统级设置。因此依赖凭据的 Recipe，使用者需要各自配置自己的凭据。

Play 1 实战：从 Git 提交自动生成 Changelog

维护 Changelog 对跟踪项目进展与对外沟通至关重要，但逐条整理提交往往耗时费力。基于 Git 提交自动生成周报式 Changelog，是值得写入 Playbook 的第一套“战术”。

工作流程拆解：

收集数据：AI 读取 Git 仓库中指定 SHA 区间（{{ start_sha }} 与 {{ end_sha }}）之间的全部提交，提取提交信息、日期、引用的 Issue/工单号；
分类信息：按关键词把提交归类为 Features / Bug Fixes / Performance Improvements / Documentation / Refactoring / Other；
格式化输出：按 # [版本/日期]、## Features 等模板生成结构化 changelog 内容，每条都尽量附 PR 链接（找不到 PR 则回退到 commit SHA 链接）；
写回文件：检测现有 CHANGELOG.md 并沿用其格式，把新内容插入文件顶部，且不破坏既有内容。

完整 Recipe（可直接保存为 YAML 运行）：

version: 1.0.0
title: Generate Changelog from Commits
description: Generate a weekly Changelog report from Git Commits
prompt: perform the task to generate change logs from the provided git commits
instructions: |
  Task: Add change logs from Git Commits

  1. Please retrieve all commits between SHA {{start_sha}} and SHA {{end_sha}} (inclusive) from the repository.

  2. For each commit:
    - Extract the commit message
    - Extract the commit date
    - Extract any referenced issue/ticket numbers (patterns like #123, JIRA-456)

  3. Organize the commits into the following categories:
    - Features: New functionality added (commits that mention "feat", "feature", "add", etc.)
    - Bug Fixes: Issues that were resolved (commits with "fix", "bug", "resolve", etc.)
    - Performance Improvements: Optimizations (commits with "perf", "optimize", "performance", etc.)
    - Documentation: Documentation changes (commits with "doc", "readme", etc.)
    - Refactoring: Code restructuring (commits with "refactor", "clean", etc.)
    - Other: Anything that doesn't fit above categories

  4. Format the release notes as follows:

    # [Version/Date]
    ## Features
    - [Feature description] - PR #number
    ## Bug Fixes
    - [Bug fix description] - PR #number
    [Continue with other categories...]

    Example:
    - Optimized query for monthly sales reports - [PR #123](https://github.com/fake-org/fake-repo/pull/123)

  5. Ensure all commit items have a PR link. If you cannot find it, try again. If you still cannot find it, use the commit sha link instead. For example: commit sha

  6. If commit messages follow conventional commit format (type(scope): message), use the type to categorize and include the scope in the notes as a bug, feature, etc

  7. Ignore merge commits and automated commits (like those from CI systems) unless they contain significant information.

  8. For each category, sort entries by date (newest first).

  9. Look for an existing CHANGELOG.md file and understand its format; create the file if it doesn't exist. Then, output the new changelog content at the top of the file, maintaining the same markdown format, and not changing any existing content.

extensions:
- type: builtin
  name: developer
  display_name: Developer
  timeout: 300
  bundled: true
activities:
- Generate release notes from last week's commits
- Create changelog for version upgrade
- Extract PR-linked changes only
- Categorize commits by conventional commit types
author:
  contact: goose-community

这段 YAML 用到了几类关键字段：instructions 承载了完整的多步骤任务规程，extensions 声明了内置 developer 扩展（提供 Shell 等执行工具，timeout 300 秒），activities 则是加载后展示给用户的示例动作。值得注意的是，从源码看（recipe/mod.rs 的 ensure_analyze_for_developer），当 Recipe 声明了内置 developer 扩展而未显式声明 analyze 扩展时，Goose 会自动注入 analyze 平台扩展——这也解释了为什么该配方无需手写额外的代码分析依赖。

Play 2 实战：自动生成 Pull Request 描述

清晰的 PR 描述能帮助 reviewer 快速理解改动意图，写出高质量 PR 却相当耗时。PR 自动生成 Play 的目标是：无需向用户追问任何信息，自主分析本地 Git 仓库并产出完整 PR 描述。

工作流程拆解：

分析变更：AI 读取本地仓库的暂存区改动（git diff --staged）与未推送提交（git log @{u}..HEAD）；
判断变更类型：区分 feature / fix / refactor / enhancement 等；
生成描述：输出含变更摘要、技术实现细节、改动文件清单、影响面分析、测试方案、迁移/破坏性变更、关联 Issue 的结构化 PR 描述；
可选：自动推送：若参数 push_pr=true，则生成 kebab-case 分支名（如 feature-add-user-auth）、自动提交并 git push，最终调用 gh 创建 PR 并打印 PR 链接。

完整 Recipe：

version: 1.0.0
title: PR Generator
author:
  contact: goose-community
description: Automatically generate pull request descriptions based on changes in a local git repo
instructions: Your job is to generate descriptive and helpful pull request descriptions without asking for additional information. Generate commit messages and branch names based on the actual code changes.
parameters:
  - key: git_repo_path
    input_type: string
    requirement: first_run
    description: path to the repo you want to create PR for
  - key: push_pr
    input_type: boolean
    requirement: optional
    default: false
    description: whether to push the PR after generating the description
extensions:
    - type: builtin
      name: developer
      display_name: Developer
      timeout: 300
      bundled: true
    - type: builtin
      name: memory
      display_name: Memory
      timeout: 300
      bundled: true
      description: "For storing and retrieving formatting preferences that might be present"
prompt: |
  Analyze the staged changes and any unpushed commits in the git repository {{git_repo_path}} to generate a comprehensive pull request description. Work autonomously without requesting additional information.

  Analysis steps:
  1. Get current branch name using `git branch --show-current`
  2. If not on main/master/develop:
     - Check for unpushed commits: `git log @{u}..HEAD` (if upstream exists)
     - Include these commits in the analysis
  3. Check staged changes: `git diff --staged`
  4. Save the staged changes diff for the PR description
  5. Determine the type of change (feature, fix, enhancement, etc.) from the code

  Generate the PR description with:
  1. A clear summary of the changes, including:
     - New staged changes
     - Any unpushed commits (if on a feature branch)
  2. Technical implementation details based on both the diff and unpushed commits
  3. List of modified files and their purpose
  4. Impact analysis (what areas of the codebase are affected)
  5. Testing approach and considerations
  6. Any migration steps or breaking changes
  7. Related issues or dependencies

  Use git commands:
  - `git diff --staged` for staged changes
  - `git log @{u}..HEAD` for unpushed commits
  - `git branch --show-current` for current branch
  - `git status` for staged files
  - `git show` for specific commit details
  - `git rev-parse --abbrev-ref --symbolic-full-name @{u}` to check if branch has upstream

  Format the description in markdown with appropriate sections and code blocks where relevant.

  {% if push_pr %}
  Execute the following steps for pushing:
  1. Determine branch handling:
     - If current branch is main/master/develop or unrelated:
       - Generate branch name from staged changes (e.g., 'feature-add-user-auth')
       - Create and switch to new branch: `git checkout -b [branch-name]`
     - If current branch matches changes:
       - Continue using current branch
       - Note any unpushed commits

  2. Handle commits and push:
     a. If staged changes exist:
        - Create commit using generated message: `git commit -m "[type]: [summary]"`
        - Message should be concise and descriptive of actual changes
     b. Push changes:
        - For existing branches: `git push origin HEAD`
        - For new branches: `git push -u origin HEAD`

  3. Create PR:
     - Use git/gh commands to create PR with generated description
     - Set base branch appropriately
     - Print PR URL after creation

  Branch naming convention:
  - Use kebab-case
  - Prefix with type: feature-, fix-, enhance-, refactor-
  - Keep names concise but descriptive
  - Base on actual code changes

  Commit message format:
  - Start with type: feat, fix, enhance, refactor
  - Followed by concise description
  - Based on actual code changes
  - No body text needed for straightforward changes

  Do not:
  - Ask for confirmation or additional input
  - Create placeholder content
  - Include TODO items
  - Add WIP markers
  {% endif %}

这个例子最有价值的地方在于它演示了 Recipe 的两种高级语法：{{ git_repo_path }} 参数替换（运行前由用户提供仓库路径）与 {% if push_pr %} 条件分支（只有参数为 true 时才激活“提交 + 推送 + 建 PR”整段自动化指令），同时通过 memory 扩展记住团队偏好的 PR 格式。参数被声明为 requirement: optional 且带 default: false，因此在默认情况下它只“生成不推送”，非常安全。

源码视角：Recipe 如何被加载、校验与保障安全

理解底层实现能帮助你写出更“健壮”的配方：

文件格式与加载：Recipe 文件支持 YAML 与 JSON 两种扩展名（见 recipe/mod.rs 的 RECIPE_FILE_EXTENSIONS），加载逻辑还会兼容“recipe: 外层包裹”的旧结构；
参数一致性校验：validate_recipe.rs 会把模板变量集合与 parameters 声明的 key 做差集比较——模板里用了但没声明、或声明了却没用到的参数都会报错，避免了运行时模板悬空；
安全边界：file 类型参数禁止带默认值，防止意外导入敏感文件；optional 参数必须显式提供默认值；Recipe 内容中的指令、prompt 与 activities 还会被扫描以检测异常 Unicode 编码内容（用于对抗提示注入类风险，见 recipe/mod.rs）；
结构约束：instructions 与 prompt 至少填一个，否则校验直接失败（这是 validate_recipe.rs 里的硬性规则）。

此外，会话级 Recipe 指南还介绍了面向自动化场景的高级能力：retry（带成功校验的自动重试与失败清理）、response.json_schema（结构化 JSON 输出，供脚本用 jq 直接解析）、sub_recipes（子配方编排）以及定时运行（goose schedule add --cron ...），而完整的字段规格可查阅 Recipe Reference Guide。CLI 侧完整的 recipe/list/open/deeplink 用法见 goose-cli-commands。

从个人技巧到团队 Playbook

一支高效团队的进化路径，往往是“个人经验 → 标准化 → 全员复用 → 持续改进”。Goose Recipe 恰好提供了这条路径的落地载体：

先做出来：让每位成员在完成高质量任务时，顺手 /recipe 把它固化成配方；
写进 Playbook：把 Recipe 文件放入团队统一的 GitHub 仓库（目录名即 Recipe 名，文件名为 recipe.yaml/recipe.json），并配置 GOOSE_RECIPE_GITHUB_REPO 或通过 goose configure 的 “goose recipe github repo” 项指向它；
像代码一样维护：用 goose recipe validate 做 CI 级校验，随团队规范演进持续修订，就像球队不断打磨战术；
新人即战力：新成员不再靠口口相传，而是直接运行团队 Playbook 中的标准配方快速产出高质量结果。