Adk Dev Guide

# 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:
1. Read `DESIGN_SPEC.md` thoroughly
2. Identify the core capabilities required
3. Note any constraints or things the agent should NOT do
4. Understand success criteria for evaluation

## Phase 2: Build and Implement

Implement the agent logic:

1. Write/modify code in the agent directory (check the agent guidance file, e.g. GEMINI.md or CLAUDE.md, for directory name)
2. Use `make playground` (or `adk web .`) for interactive testing during development
3. 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`.

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

**Expect 5-10+ iterations here.**

## Phase 4: Deploy

Once evaluation thresholds are met:

1. 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:

1.  **Target Identification:** Clearly define the exact lines or expressions to be changed, based *solely* on the user's explicit instructions.
2.  **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