ADK Development Workflow & Guidelines

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.

DESIGN_SPEC.md — Your Primary Reference

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.

Phase 1: Understand the Spec

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

Phase 2: Build and Implement

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

.

Phase 3: Evaluate

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.

Phase 4: Deploy

Once evaluation thresholds are met:

Deploy when ready — see

/adk-deploy-guide

for deployment options

IMPORTANT

Never deploy without explicit human approval. Operational Guidelines for Coding Agents Principle 1: Code Preservation & Isolation 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): 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): 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

) Principle 2: Execution Best Practices 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):

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 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. 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 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) 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.