adk-dev-guide

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

ADK Development Workflow & Guidelines

ADK Agent开发工作流与指南

Session Continuity

会话连续性

If this is a long session, re-read the relevant skill before each phase —

/adk-cheatsheet

before writing code,

/adk-eval-guide

before running evals,

/adk-deploy-guide

before deploying,

/adk-scaffold

before scaffolding. Context compaction may have dropped earlier skill content.

如果是长会话，在每个阶段开始前重新阅读相关技能——编写代码前查看

/adk-cheatsheet

，运行评估前查看

/adk-eval-guide

，部署前查看

/adk-deploy-guide

，搭建脚手架前查看

/adk-scaffold

。上下文压缩可能会丢失早期的技能内容。

DESIGN_SPEC.md — Your Primary Reference

DESIGN_SPEC.md — 你的首要参考文档

IMPORTANT: If

DESIGN_SPEC.md

exists in this project, it is your primary source of truth.

Read it FIRST to understand:

Functional requirements and capabilities
Success criteria and quality thresholds
Agent behavior constraints
Expected tools and integrations

The spec is your contract. All implementation decisions should align with it. When in doubt, refer back to DESIGN_SPEC.md.

重要提示：如果项目中存在

DESIGN_SPEC.md

，它就是你的首要事实依据。

请先阅读它以了解：

功能需求与能力
成功标准与质量阈值
Agent行为约束
预期使用的工具与集成

规范就是你的契约。所有实现决策都应与它保持一致。如有疑问，请回头参考DESIGN_SPEC.md。

Phase 1: Understand the Spec

阶段1：理解规范

Before writing any code:

Read
```
DESIGN_SPEC.md
```
thoroughly
Identify the core capabilities required
Note any constraints or things the agent should NOT do
Understand success criteria for evaluation

在编写任何代码之前：

彻底阅读
```
DESIGN_SPEC.md
```
识别所需的核心能力
记录所有约束条件以及Agent不应执行的操作
理解评估的成功标准

Phase 2: Build and Implement

阶段2：构建与实现

Implement the agent logic:

Write/modify code in the agent directory (check the agent guidance file, e.g. GEMINI.md or CLAUDE.md, for directory name)
Use
```
make playground
```
(or
```
adk web .
```
) for interactive testing during development
Iterate on the implementation based on user feedback

For ADK API patterns and code examples, use

/adk-cheatsheet

实现Agent逻辑：

在Agent目录中编写/修改代码（请查看Agent指导文件，如GEMINI.md或CLAUDE.md，确认目录名称）
使用
```
make playground
```
（或
```
adk web .
```
）在开发过程中进行交互式测试
根据用户反馈迭代实现方案

如需ADK API模式和代码示例，请查看

/adk-cheatsheet

。

Phase 3: Evaluate

阶段3：评估

This is the most important phase. Evaluation validates agent behavior end-to-end using evalsets and scoring metrics.

MANDATORY: Activate

/adk-eval-guide

before running evaluation. It contains the evalset schema, config format, and critical gotchas. Do NOT skip this.

Tests (
pytest
) are NOT evaluation. They test code correctness but say nothing about whether the agent behaves correctly. Always run

adk eval

Start small: Begin with 1-2 sample eval cases, not a full suite
Run evaluations:
```
adk eval
```
(or
```
make eval
```
if the project has a Makefile)
Discuss results with the user
Fix issues and iterate on the core cases first
Only after core cases pass, add edge cases and new scenarios
Repeat until quality thresholds are met

Expect 5-10+ iterations here.

这是最重要的阶段。评估通过评估集和评分指标端到端验证Agent的行为。

强制要求：在运行评估前激活

/adk-eval-guide

。它包含评估集 schema、配置格式以及关键注意事项。请勿跳过此步骤。

测试（
pytest
）不等同于评估。测试仅验证代码正确性，但无法说明Agent行为是否符合预期。务必运行

adk eval

。

从小处着手：先从1-2个评估示例案例开始，而非完整套件
运行评估：
```
adk eval
```
（如果项目有Makefile，也可使用
```
make eval
```
）
与用户讨论评估结果
修复问题并优先迭代核心案例
仅在核心案例通过后，再添加边缘案例和新场景
重复上述步骤直至达到质量阈值

预计在此阶段需要5-10+次迭代。

Phase 4: Deploy

阶段4：部署

Once evaluation thresholds are met:

Deploy when ready — see
```
/adk-deploy-guide
```
for deployment options

IMPORTANT: Never deploy without explicit human approval.

一旦达到评估阈值：

准备就绪后进行部署——请查看
```
/adk-deploy-guide
```
了解部署选项

重要提示：未经明确的人工批准，绝不要部署。

Operational Guidelines for Coding Agents

Agent编码操作指南

Principle 1: Code Preservation & Isolation

原则1：代码保留与隔离

When executing code modifications, your paramount objective is surgical precision. You must alter only the code segments directly targeted by the user's request, while strictly preserving all surrounding and unrelated code.

Mandatory Pre-Execution Verification:

Before finalizing any code replacement, verify:

Target Identification: Clearly define the exact lines or expressions to be changed, based solely on the user's explicit instructions.
Preservation Check: Ensure all code, configuration values (e.g.,
```
model
```
,
```
version
```
,
```
api_key
```
), comments, and formatting outside the identified target remain identical.

Example:

User Request: "Change the agent's instruction to be a recipe suggester."

Incorrect (VIOLATION):

python

root_agent = Agent(
    name="recipe_suggester",
    model="gemini-1.5-flash",  # UNINTENDED - model was not requested to change
    instruction="You are a recipe suggester."
)

Correct (COMPLIANT):

python

root_agent = Agent(
    name="recipe_suggester",  # OK, related to new purpose
    model="gemini-3-flash-preview",  # PRESERVED
    instruction="You are a recipe suggester."  # OK, the direct target
)

在执行代码修改时，你的首要目标是精准操作。你必须仅修改用户请求直接指向的代码段，同时严格保留所有周边及无关代码。

执行前强制验证：

在最终确定任何代码替换前，请验证：

目标识别：仅根据用户的明确指令，清晰定义需要修改的确切代码行或表达式。
保留检查：确保所有目标范围外的代码、配置值（如
```
model
```
、
```
version
```
、
```
api_key
```
）、注释和格式保持完全一致。

示例：

用户请求："将Agent的指令修改为食谱推荐器。"

错误示例（违规）：

python

root_agent = Agent(
    name="recipe_suggester",
    model="gemini-1.5-flash",  # 非预期修改——未要求更改模型
    instruction="You are a recipe suggester."
)

正确示例（合规）：

python

root_agent = Agent(
    name="recipe_suggester",  # 符合要求，与新用途相关
    model="gemini-3-flash-preview",  # 已保留
    instruction="You are a recipe suggester."  # 符合要求，直接修改目标
)

Principle 2: Execution Best Practices

原则2：执行最佳实践

Model Selection — CRITICAL:
- NEVER change the model unless explicitly asked. If the code uses
```
gemini-3-flash-preview
```
  , keep it as
```
gemini-3-flash-preview
```
  . Do NOT "upgrade" or "fix" model names.
- When creating NEW agents (not modifying existing), use Gemini 3 series:
```
gemini-3-flash-preview
```
  ,
```
gemini-3-pro-preview
```
  .
- Do NOT use older models (
```
gemini-2.0-flash
```
  ,
```
gemini-1.5-flash
```
  , etc.) unless the user explicitly requests them.
Location Matters More Than Model:
- If a model returns a 404, it's almost always a
```
GOOGLE_CLOUD_LOCATION
```
  issue (e.g., needing
```
global
```
  instead of
```
us-central1
```
  ).
- Changing the model name to "fix" a 404 is a violation — fix the location instead.
- Some models (like
```
gemini-3-flash-preview
```
  ) require specific locations. Check the error message for hints.

ADK Built-in Tool Imports (Precision Required):

python

# CORRECT - imports the tool instance
from google.adk.tools.load_web_page import load_web_page

# WRONG - imports the module, not the tool
from google.adk.tools import load_web_page

Pass the imported tool directly to

tools=[load_web_page]

, not

tools=[load_web_page.load_web_page]

Running Python Commands:
- Always use
```
uv
```
  to execute Python commands (e.g.,
```
uv run python script.py
```
  )
- Run
```
make install
```
  (or
```
uv sync
```
  ) before executing scripts
- Consult
```
Makefile
```
  and
```
README.md
```
  for available commands (if present)
Breaking Infinite Loops:
- Stop immediately if you see the same error 3+ times in a row
- Don't retry failed operations — fix the root cause first
- RED FLAGS: Lock IDs incrementing, names appending v5->v6->v7, "I'll try one more time" repeatedly
- State conflicts (Error 409: Resource already exists): Import existing resources with
```
terraform import
```
  instead of retrying creation
- Tool bugs: Fix source code bugs before continuing — don't work around them
- When stuck: Run underlying commands directly (e.g.,
```
terraform
```
  CLI) instead of calling problematic tools
Troubleshooting:
- Check
```
/adk-cheatsheet
```
  first — it covers most common patterns
- Search the installed ADK package with Glob/Grep/Read (find it with
```
python -c "import google.adk; print(google.adk.__path__[0])"
```
  — use
```
uv run python
```
  if using uv)
- For ADK docs, see
```
references/docs-index.md
```
  in the cheatsheet skill for WebFetch URLs
- For framework questions or GCP products, check official documentation
- When encountering persistent errors, a targeted Google Search often finds solutions faster

模型选择——至关重要：
- 除非明确要求，绝不要更改模型。如果代码使用
```
gemini-3-flash-preview
```
  ，请保持不变。不要“升级”或“修复”模型名称。
- 创建新Agent（而非修改现有Agent）时，请使用Gemini 3系列：
```
gemini-3-flash-preview
```
  、
```
gemini-3-pro-preview
```
  。
- 除非用户明确要求，否则不要使用旧版模型（如
```
gemini-2.0-flash
```
  、
```
gemini-1.5-flash
```
  等）。
位置比模型更重要：
- 如果模型返回404错误，几乎总是
```
GOOGLE_CLOUD_LOCATION
```
  的问题（例如，需要使用
```
global
```
  而非
```
us-central1
```
  ）。
- 通过更改模型名称来“修复”404错误属于违规——应改为修复位置设置。
- 部分模型（如
```
gemini-3-flash-preview
```
  ）需要特定位置。请查看错误消息获取提示。

ADK内置工具导入（需精准）：

python

# 正确——导入工具实例
from google.adk.tools.load_web_page import load_web_page

# 错误——导入的是模块而非工具
from google.adk.tools import load_web_page

将导入的工具直接传入

tools=[load_web_page]

，而非

tools=[load_web_page.load_web_page]

。

运行Python命令：
- 始终使用
```
uv
```
  执行Python命令（例如
```
uv run python script.py
```
  ）
- 在执行脚本前运行
```
make install
```
  （或
```
uv sync
```
  ）
- 请参考Makefile和
```
README.md
```
  获取可用命令（如果存在）
打破无限循环：
- 如果连续3次以上看到相同错误，请立即停止
- 不要重试失败的操作——先修复根本原因
- 危险信号：锁ID递增、名称从v5追加到v6再到v7、反复尝试“再试一次”
- 状态冲突（错误409：资源已存在）：使用
```
terraform import
```
  导入现有资源，而非重试创建
- 工具bug：先修复源代码bug再继续——不要绕过问题
- 遇到瓶颈时：直接运行底层命令（如
```
terraform
```
  CLI），而非调用有问题的工具
故障排查：
- 首先查看
```
/adk-cheatsheet
```
  ——它涵盖了大多数常见模式
- 使用Glob/Grep/Read搜索已安装的ADK包（通过
```
python -c "import google.adk; print(google.adk.__path__[0])"
```
  查找路径——如果使用uv，请用
```
uv run python
```
  ）
- 如需ADK文档，请查看cheatsheet技能中的
```
references/docs-index.md
```
  获取WebFetch链接
- 如需框架相关问题或GCP产品信息，请查看官方文档
- 遇到持续错误时，针对性的谷歌搜索通常能更快找到解决方案

Scaffold as Reference

脚手架作为参考

When you need specific infrastructure files but don't want to scaffold the current project directly, use the

/adk-scaffold

skill to create a temporary reference project in

/tmp/

and copy over what you need.

See

/adk-scaffold

for full CLI commands and options.

当你需要特定的基础设施文件但不想直接为当前项目搭建脚手架时，可以使用

/adk-scaffold

技能在

/tmp/

目录中创建一个临时参考项目，然后复制所需内容。

请查看

/adk-scaffold

获取完整的CLI命令和选项。

Development Commands

开发命令

Projects created via the Agent Starter Pack CLI include a Makefile with these commands. To create or enhance a project, see the

/adk-scaffold

skill for full instructions. For non-scaffolded projects, use the ADK CLI equivalents.

Make (scaffolded)	ADK CLI equivalent	Purpose
`make playground`	`adk web .`	Interactive local testing
`make test`	`pytest`	Run unit and integration tests
`make eval`	`adk eval <agent_dir> <evalset>`	Run evaluation against evalsets
`make lint`	`ruff check .`	Check code quality
`make setup-dev-env`	— (scaffolded only)	Set up dev infrastructure (Terraform)
`make deploy`	— (scaffolded only)	Deploy to dev (requires human approval)

通过Agent Starter Pack CLI创建的项目包含一个带有以下命令的Makefile。如需创建或增强项目，请查看

/adk-scaffold

技能获取完整说明。对于非脚手架创建的项目，请使用ADK CLI等效命令。

Make（脚手架项目）	ADK CLI等效命令	用途
`make playground`	`adk web .`	交互式本地测试
`make test`	`pytest`	运行单元与集成测试
`make eval`	`adk eval <agent_dir> <evalset>`	针对评估集运行评估
`make lint`	`ruff check .`	检查代码质量
`make setup-dev-env`	—（仅脚手架项目可用）	搭建开发基础设施（Terraform）
`make deploy`	—（仅脚手架项目可用）	部署到开发环境（需人工批准）

Skills Version

技能版本

Troubleshooting hint: If you encounter repeated errors, unexpected tool failures, or instructions in these skills that seem incomplete or reference features you can't find, the skills may be outdated. Run:
npx skills check -g
If it reports outdated skills, tell the user to update:
npx skills update -g
Do NOT run this check on every session — only when you suspect stale skills are causing problems.

故障排查提示：如果你遇到重复错误、工具意外失败，或者这些技能中的说明不完整、引用了你找不到的功能，可能是技能已过时。请运行：
npx skills check -g
如果报告技能已过时，请告知用户进行更新：
npx skills update -g
不要在每个会话都运行此检查——仅当你怀疑过时技能导致问题时才执行。