Appendix G - Coding Agents

Overview

Coding Agents represent the evolution from simple code completion to a full human-AI augmented development team. The era of the lone coder with an AI autocomplete is giving way to developers who lead teams of specialized AI agents — each with a distinct role in the software development lifecycle.

This appendix presents two complementary paradigms:

1. Vibe Coding — using conversational LLM interaction for rapid ideation and prototyping
2. Human-Agent Teams — a structured framework for production software development with specialist agents playing defined roles

As Alphabet CEO Sundar Pichai noted in early 2025: "Over 30% of new code at Google is now assisted or generated by our Gemini models." Microsoft reported similar statistics. The question is no longer whether AI will assist software development, but how to organize that assistance effectively.

Core Principle: The human developer is the architect and final arbiter — agents are force multipliers that handle tactical execution while humans focus on strategic vision and creative problem-solving.

When This Skill Applies

Activate this pattern when:

• Starting a new feature and want to rapidly prototype before committing to architecture
• Need comprehensive test coverage for existing code without writing every test manually
• Generating technical documentation for complex APIs or modules
• Performing code review with AI-assisted critique and synthesis
• Building a repeatable, team-wide workflow for AI-assisted development
• Organizing multiple AI interactions into a coherent, auditable development process

Rule of thumb: Use Vibe Coding to explore. Use the Human-Agent Team framework to build for production.

Vibe Coding: Intuitive AI-Assisted Development

What Is Vibe Coding?

Vibe coding is a conversational approach to software development where you describe the desired outcome (the "vibe") rather than specifying every implementation detail. The AI generates initial code that serves as a creative catalyst for refinement.

Key characteristics:

• Conversational prompts: "Create a modern landing page with a hero section and pricing table"
• Iterative refinement: "That's good, but make the navigation sticky and add a dark mode toggle"
• Creative partnership: The AI suggests approaches the developer hadn't considered
• Focus on "what" not "how": Developer specifies outcome; AI handles implementation
• Optional memory banks: Store project style guides, preferences, or constraints across sessions

When to Use Vibe Coding

• Overcoming blank-page problem: Quickly get from concept to running code
• Exploring APIs: Test how a new library works without reading all docs first
• Rapid prototyping: Validate an architectural approach before investing in polish
• Creative exploration: Find innovative solutions by letting AI suggest directions

Vibe Coding Limitations

Vibe coding accelerates ideation but is not suitable for production on its own:

• Generated code often lacks error handling, security measures, and edge case coverage
• Without structured review, technical debt accumulates rapidly
• AI may not understand your specific performance requirements or team conventions

The transition from vibe coding to production requires the Human-Agent Team framework.

Human-Agent Team Framework

Three Foundational Principles

1. Human-Led Orchestration The developer is the team lead and project architect. They define tasks, provide context, and make all final decisions. Agents are powerful collaborators — not autonomous decision-makers. The human orchestrates which agent to engage, provides the necessary briefing, and validates all output.

2. The Primacy of Context An agent's performance is entirely dependent on the quality and completeness of its context. A powerful LLM with poor context is useless. The developer is responsible for assembling a complete "briefing" for each agent interaction, including:

• The Complete Codebase: All relevant source code so the agent understands existing patterns
• External Knowledge: API documentation, design specs, style guides
• The Human Brief: Clear goals, requirements, and acceptance criteria

3. Direct Model Access Use frontier models directly (Gemini 2.5 Pro, Claude Opus 4, GPT-4o) without intermediary platforms that truncate context or obscure the model's raw capability. The goal is the purest dialogue between human intent and model capability.

The Specialist Agent Team

The framework assigns specialized roles to focused AI agent "personas" — invoked through carefully crafted prompts rather than separate applications:

Human Developer (Orchestrator)
         │
    ┌────┼────────────────┐
    │    │                │
    ▼    ▼                ▼
Scaffolder  Test Engineer  Documenter
(Implementer) (Quality Guard)  (Scribe)
    │
    ▼
Optimizer   Process Agent
(Refactoring)  (Supervisor)
    │
    ▼
Human Developer (Final Review & Approval)
    │
    ▼
Project Codebase

DEFINE → PLAN → ACTION Workflow

DEFINE

Map the coding team requirements:

1. What is the development task? (New feature, bug fix, refactoring, documentation, testing)
2. Which specialist agent is appropriate? (Scaffolder for features, Test Engineer for coverage, etc.)
3. What context does the agent need? (Code files, specs, existing patterns)
4. What are the acceptance criteria? (What makes the agent's output "done"?)
5. How will output be validated? (Tests pass, code review, documentation review)

PLAN

Prepare the agent briefing (Context Staging Area):

1. Create a task-context/ directory with all relevant files for the task
2. Write a clear 01_BRIEF.md describing goals, requirements, and constraints
3. Assemble relevant source code in 02_CODE/
4. Include API docs, style guides, or external references as needed
5. Select the appropriate specialist agent persona and its invocation prompt

ACTION

Execute and validate:

1. Invoke the specialist agent with its role-specific prompt + briefing
2. Review the agent's output against acceptance criteria
3. If imperfect, iterate: provide corrective feedback, add context, re-prompt
4. Run tests to validate functional correctness
5. Human final review and approval before merging to main

Implementation: Specialist Agent Prompts

The Scaffolder Agent (Implementer)

from google import genai
from google.genai import types

SCAFFOLDER_PROMPT = """You are a senior software engineer.
Based on the requirements in 01_BRIEF.md and the existing patterns in 02_CODE/,
implement the feature described. Follow all existing conventions exactly.

Rules:
- Match the existing code style and patterns precisely
- Add type hints consistent with the codebase
- Include docstrings matching the project's documentation style
- Do NOT add features beyond what is specified
- Do NOT refactor surrounding code

Output: Complete, runnable implementation."""

def invoke_scaffolder(brief: str, existing_code: str) -> str:
    """Invoke the Scaffolder agent to implement a new feature."""
    client = genai.Client()
    prompt = f"""BRIEF:\n{brief}\n\nEXISTING CODE PATTERNS:\n{existing_code}"""
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=prompt,
        config=types.GenerateContentConfig(system_instruction=SCAFFOLDER_PROMPT)
    )
    return response.text

The Test Engineer Agent (Quality Guard)

TEST_ENGINEER_PROMPT = """You are a quality assurance engineer specializing in test design.
For the code provided, write a comprehensive test suite using the project's testing framework.

Requirements:
- Cover all happy paths with explicit assertions
- Cover edge cases: empty inputs, boundary values, error conditions
- Cover failure modes: exceptions, timeouts, invalid data
- Follow the existing test naming convention: test_<function>_<scenario>
- Use the project's fixtures and test utilities
- Include integration tests where the function interacts with external systems

Output: A complete test file that can be run immediately with no modifications."""

def invoke_test_engineer(code_to_test: str, existing_tests: str, framework: str = "pytest") -> str:
    """Invoke the Test Engineer agent to write comprehensive tests."""
    client = genai.Client()
    prompt = f"""Testing Framework: {framework}

CODE TO TEST:
{code_to_test}

EXISTING TESTS (for style reference):
{existing_tests}"""
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=prompt,
        config=types.GenerateContentConfig(system_instruction=TEST_ENGINEER_PROMPT)
    )
    return response.text

The Documenter Agent (Scribe)

DOCUMENTER_PROMPT = """You are a technical writer who specializes in developer documentation.
Generate clear, concise documentation for the code provided.

Requirements:
- Write for the intended audience (internal developers or external API consumers)
- Include: purpose, parameters with types, return values, exceptions raised
- Add at least one concrete usage example per function/class
- Use the project's documentation format (docstrings, JSDoc, TSDoc, etc.)
- Document edge cases and gotchas that aren't obvious from the signature

Output: Documentation that can be copied directly into the codebase."""

def invoke_documenter(code: str, audience: str = "internal developers") -> str:
    """Invoke the Documenter agent to generate technical documentation."""
    client = genai.Client()
    prompt = f"""Audience: {audience}\n\nCODE TO DOCUMENT:\n{code}"""
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=prompt,
        config=types.GenerateContentConfig(system_instruction=DOCUMENTER_PROMPT)
    )
    return response.text

The Process Agent (Code Supervisor — Critique + Reflection)

PROCESS_AGENT_PROMPT = """You are a principal engineer conducting a thorough code review.

Your process:
STEP 1 — CRITIQUE: Perform a detailed analysis of the code. Identify:
- Correctness issues: bugs, logic errors, off-by-one errors
- Security concerns: injection, auth bypass, data exposure
- Performance issues: N+1 queries, inefficient algorithms, memory leaks
- Maintainability: unclear naming, missing error handling, code duplication
- Style violations: deviations from conventions in the provided context

STEP 2 — REFLECTION: Synthesize your critique. Produce a concise, prioritized summary:
- Distinguish MUST-FIX (correctness/security) from SHOULD-FIX (quality) from NICE-TO-HAVE (style)
- Dismiss trivial or pedantic issues that add no real value
- Provide specific, actionable feedback with line references

Output format:
## Critique (detailed)
[Full analysis]

## Reflection (prioritized summary)
### Must Fix
### Should Fix
### Nice to Have"""

def invoke_process_agent(code_diff: str, project_context: str = "") -> str:
    """Invoke the Process Agent to critique and synthesize code review feedback."""
    client = genai.Client()
    prompt = f"""PROJECT CONTEXT:
{project_context}

CODE CHANGES TO REVIEW:
{code_diff}"""
    response = client.models.generate_content(
        model='gemini-2.5-flash',
        contents=prompt,
        config=types.GenerateContentConfig(system_instruction=PROCESS_AGENT_PROMPT)
    )
    return response.text

Git Hook Integration

#!/bin/bash
# .git/hooks/pre-commit
# Automatically trigger Process Agent code review on staged changes

# Get staged diff
DIFF=$(git diff --cached)

if [ -z "$DIFF" ]; then
    echo "No staged changes to review"
    exit 0
fi

echo "Running AI code review on staged changes..."

# Invoke Process Agent (replace with your actual invocation method)
python3 -c "
from your_agent_module import invoke_process_agent
import sys

diff = '''$DIFF'''
review = invoke_process_agent(diff)
print(review)

# Check for Must Fix items
if 'Must Fix' in review and review.split('Must Fix')[1].strip().startswith('-'):
    print('\n⚠️  Must-Fix issues detected. Review before committing.')
    sys.exit(1)
"

echo "Review complete. Proceed with commit? (y/n)"
read -r response
if [[ "$response" != "y" ]]; then
    exit 1
fi

Practical Setup Checklist

1. Provision Frontier Model Access: Secure API keys for Gemini 2.5 Pro AND Claude Opus 4 — dual-provider hedges against downtime
2. Context Staging Area: Create task-context/ in project root with 01_BRIEF.md, 02_CODE/, 03_DOCS/
3. Version-Controlled Prompt Library: Create /prompts/ directory with scaffolder.md, tester.md, documenter.md, reviewer.md as Git-tracked files
4. Git Hook Integration: Configure pre-commit hook to trigger Process Agent on staged changes
5. Feedback Loop: After each agent interaction, note what worked and refine the invocation prompts

Principles for Leading the Augmented Team

• Maintain Architectural Ownership: You define the "what" and "why" — agents handle the "how". You are the final arbiter of design quality
• Master the Art of the Brief: An agent's output quality is a direct reflection of the briefing quality — invest time in clear, complete context
• Act as the Ultimate Quality Gate: Agent output is always a proposal, never a command — validate everything before it reaches the codebase
• Engage in Iterative Dialogue: If initial output is imperfect, don't discard it — refine with corrective feedback and additional context

Key Takeaways

• Vibe coding is for exploration: Use it to overcome the blank-page problem and rapidly prototype — not for production code
• Specialists outperform generalists: A focused Test Engineer prompt produces better tests than asking a generic agent to "add tests"
• Context is the foundation: Without a complete briefing (code, docs, goals), even the best model produces generic output
• Human orchestration is non-negotiable: Agent output must pass human review — the human is always the final quality gate
• Prompts are code: Store them in Git, version them, and refine them like production code

Anti-Patterns to Avoid

• Autonomous agents without review: Never commit AI-generated code without human validation — agents can introduce subtle bugs
• Context-free invocation: Calling an agent without relevant code files produces generic, convention-violating output
• One agent for all tasks: Using a generic "write good code" prompt for implementation, testing, AND review produces mediocre results for all
• Discarding imperfect output: Iterative dialogue almost always beats starting over — provide corrective feedback rather than re-prompting from scratch
• Skipping tests: Always run the full test suite after agent-generated changes — agents don't know what they broke

Related Skills

Combine this skill with others for common scenarios:

References

• AI generating 30%+ of code at Google: https://www.reddit.com/r/singularity/comments/1k7rxo0/
• AI generating 30%+ of code at Microsoft: https://www.businesstoday.in/tech-today/news/story/30-of-microsofts-code-is-now-ai-generated-says-ceo-satya-nadella-474167-2025-04-30
• Claude Code: https://docs.anthropic.com/en/docs/claude-code/
• Gemini CLI: https://github.com/google-gemini/gemini-cli
• Aider: https://aider.chat/