Coding Agent Resources

The goal of this repository is to provide a quick reference and onboarding guide to help you quickly become proficient with AI coding agents.

Important

Tooling is quickly evolving and new research seems to come out every day. If you see a mistake in the doc or hear about something you think should be included, please make an issue

Introduction: What is an AI Coding Agent?
Core Fundamentals & Best Practices
Getting Started & Settings
The Concept of "Context"
- Working Context
- Starting Context
Skills, Subagents, and Workflows
- Skills
- Subagents
Resource Index

Introduction: What is an AI Coding Agent?

An AI coding agent is an advanced AI model integrated directly into your development environment (like your terminal or IDE). Unlike a standard chatbot that only answers questions, an agent can read your files, execute terminal commands, run tests, and autonomously write or modify code.

While this guide focuses primarily on Gemini CLI, the principles and best practices apply to other powerful agents like Claude Code and Codex. We use cross-compatible conventions, such as AGENTS.md for context files, to ensure these resources are useful regardless of your specific tool.

You can use agents to:

Investigate bugs by having them trace data flows and run reproduction scripts.
Plan features by asking them to draft architectural design documents before writing code.
Execute surgical refactors across multiple files.
Write exhaustive tests for complex modules.

Core Fundamentals & Best Practices

If you are a seasoned engineer but a beginner to AI agents, your instincts might betray you. You cannot interact with an agent the same way you interact with another seasoned engineer or a simple Google search. Working effectively requires a shift in how you communicate, review code, and set boundaries.

1. The Mindset (Philosophy)

You are the Pilot: Do not grant the agent the autonomy of a senior engineer. Treat it like an extremely eager, fast-typing intern. It is highly capable of writing code, but it does not see the big picture and lacks architectural intuition. If left to its own devices without strict direction, it will write a massive amount of code that might "work" but will be an unsustainable, unmaintainable mess. You must dictate the architecture, the workflow, and the boundaries.
- Keep in mind though, agents are extremely capable in any domain if you can keep the task narrow. If prompted to help make an architecture decision, it will still be able to provide constructive feedback that you can use to generate an implementation plan
Trust, but Verify (Avoid "Vibe Coding"): Agents will confidently hallucinate nonexistent APIs or subtly break logic. Don't blindly accept code just because it looks correct at a glance. Always require the agent to write tests, or manually run your build/test suite after it finishes a task.
Agents Are Always Guessing: The agent lacks the implicit team knowledge and years of context you have. Every decision is a statistical guess based on its immediate context window. It is your job to minimize the guessing by providing necessary background, enforcing strict guardrails, and forcing structured workflows.

2. Tactical Prompting (How to talk to it)

Break Tasks Down (Atomic Steps): Do not give the agent a massive prompt like "Build the new perception pipeline." Instead, break it down: "Draft a design doc for the perception pipeline," followed by "Implement the data ingestion node," followed by "Write unit tests." Small, verifiable steps prevent compounding errors.
The "Pink Elephant" Problem (Speak in the Affirmative): If you tell someone "Don't think of a pink elephant," they immediately think of one. LLMs work similarly. Instead of saying "Do not use var", say "Always use const or let". Provide positive instructions and clear examples of what you want, rather than a long list of what you don't want.
Directives vs. Inquiries: Understand the difference between asking a question and giving an order. An Inquiry (e.g., "Why is this function crashing?") is a request for text analysis. A Directive (e.g., "Fix the crash") is an order to execute a task. Enforce this boundary in your user_level.AGENTS.md so the agent waits for a Directive before taking action.
Provide Examples (Few-Shot Prompting): Agents perform significantly better when given a template or an existing code snippet to match your project's established style.
Leverage Its Tools: The agent is not just a text generator. It has access to your terminal. Instead of pasting code into the chat, tell the agent: "Find where the User class is defined and explain its dependencies." Let it use grep to do the legwork.
Model Selection: Whenever possible, prefer using larger, more capable models (like Gemini Pro) for complex tasks. They save time and reduce "churn" because they are smarter and make fewer mistakes. Switch to smaller models (like Flash) only for simple, repetitive tasks to save tokens.

3. Workflow Strategies (How to use it)

The "Sensory Deprivation" Debugging Loop: When a change doesn't work, never just say "that didn't work." The agent cannot see the physical world or run your hardware tests. You must act as the agent's eyes and sensors. Explicitly provide:
1. What you commanded (e.g., "I ran the drive_forward script").
2. What you observed (e.g., "The robot jerked to the left and the motor controller reported an overcurrent fault on the serial monitor").
3. What you expected (e.g., "It should have driven straight for 2 meters smoothly").
The "Closed Loop" Verification: Left to its own devices, an agent will make a single attempt at a task and immediately declare success, even if the code is broken. To force the agent to iterate, you must give it a way to check its own work. Always include a verification mechanism in your prompt so the agent won't stop until it actually succeeds.
- Software Example: "Fix the parser bug and run pytest test_parser.py until the suite passes."
- Hardware Example: "Update the motor logic, push the build to the robot, and verify in the syslog that the overcurrent warning no longer appears on boot."
The "Dry Run" Methodology (Mocking Hardware): Testing every logic change on a physical robot is slow and tedious. Because agents can write code instantly, you can ask them to generate lightweight "mocks" to test logic in isolation before integrating it into your complex stack. This perfectly pairs with the "Closed Loop" method above.
- Example: "Before we integrate this into the main ROS node, write a standalone python script that mocks a temperature sensor. Have the script feed fake temperature spikes into our new safety function and verify the function triggers a shutdown. Once that script passes, we will move the logic into the main C++ node."
Code Reviews & Explainability: Never blindly accept code you cannot understand. Treat the agent as both the author and the reviewer.
- Explain It Back: If the agent writes a complex math function, ask it to explain the logic line-by-line before integrating it.
- Devil's Advocate Review: Before opening a PR, ask the agent to "act as a senior reviewer and find edge cases or race conditions in the code you just wrote."
Session Management & Context Refreshes: Agents build up "context" (memory) as a conversation progresses. If a session gets too long, the agent becomes confused, hallucinates, and becomes significantly more expensive to run.
- Fresh Eyes for Review: Never use the same chat session to write code and review it. Always open a completely new chat for code review to ensure the agent evaluates the actual file state, rather than relying on its potentially flawed memory of what it thinks it wrote.
- When to Reset: Clear the chat or start a new session whenever you complete a specific goal or switch tasks (e.g., finishing the PR draft, moving from debugging to feature implementation). Keeping context small not only improves the agent's accuracy but drastically reduces your token usage and costs.

Getting Started & Settings

To get the most out of your agent, you need to configure it correctly for your environment. Settings can typically be applied at both the user and workspace level.

Settings & Configuration

User vs Workspace Settings: Most agents allow you to define settings globally (in your home directory, e.g., ~/.gemini/config.json) or locally per-workspace. Workspace settings generally override user settings, allowing you to tailor behavior for specific projects.
Trusting Directories: Agents like Gemini CLI operate within a security boundary. You may need to explicitly "trust" a directory before the agent can execute commands or modify files within it.
Command Policies: To protect your system, configure command policies. You can permanently allow safe, read-only commands (like git status, ls, grep) so the agent doesn't pause to ask for permission during its research phase. Destructive commands (like rm or git push) should always require explicit confirmation.
Recommended Settings: We recommend starting with strict command policies and a robust .geminiignore (or equivalent) to hide compiled assets, dependency folders (node_modules/, venv/), and sensitive credentials (.env, .ssh/).

Opinionated setup recommendations are below if you are interested.

Gemini Setup

Installation

Installation information and prerequisites can be found in the official Gemini CLI documentation.

Tool Conservatism & The Policy Engine

By default, Gemini is quite conservative with its tool use to protect your system. It will ask for permission before running most bash tools or modifying files. You can even force it into a strict read-only mode by default if you desire. It generally only executes its own internal codebase exploration tools without asking.

To make the agent more autonomous without sacrificing safety, Gemini utilizes a Policy Engine configured via .toml files. These policies define exactly which commands the agent is allowed to run autonomously (allow), which require confirmation (ask_user), and which are strictly blocked (deny).

We have provided an example policy file in settings/gemini_security_policy.toml. The majority of the rules in this config file allow the agent to use more system tools as long as they are read-only (like grep, cat, git diff, and safe docker commands). This means the agent will ask for permission less often during its research phase, while still explicitly blocking dangerous, mutating, or exfiltration commands. We recommend you review this document and ensure you are comfortable with the tools that have been given permission.

High-Level Policy Guide: For complete details, please refer to the official Gemini CLI Policy Engine documentation.

Installation & Organization: Policies are currently applied at the user level. You must place your .toml files in ~/.gemini/policies/. You can organize your rules into as many files as you desire; the engine will parse any .toml file it finds in that directory. Workspace-level policies (inside your project directory) are not currently supported, so you will have to use the user-level directory to grant permissions for any repo-specific tooling.
Granting Permissions (Shell Commands): To allow a new tool, you create a [[rule]] block. For the common use case of allowing specific shell scripts or terminal commands, you can use the commandPrefix option (e.g., commandPrefix = ["npm run test"]) with decision = "allow".
Prefix vs. Regex (The Regex Caveat): The commandPrefix option is a convenience tool specifically for shell commands that makes simple matching easy. However, if you need more complex matching and choose to use the commandRegex or argsPattern options, there is a catch. The regex options match against a JSON payload string representing the tool's arguments (e.g., {"command": "your command"}), not the raw command string itself. Therefore, do not use strict start (^) or end ($) anchors as if matching a simple text string, because they will fail to match the surrounding JSON syntax. This caveat only applies to the regex configuration lines.

Opinionated Settings

We highly recommend reviewing the official Gemini Settings Documentation to see all available customizations. You can modify these settings globally at ~/.gemini/settings.json or locally per-project at your-project/.gemini/settings.json.

Below are opinionated snippets from a recommended settings.json file. Each section is described independently. (Note: The ... indicates that other settings may exist in these blocks).

Security

{
  "security": {
    "enablePermanentToolApproval": true,
    ...
  }
}

enablePermanentToolApproval: Set this to true if you want the ability to permanently allow safe, read-only tools (like grep, ls, cat) when prompted to "approve" them in the CLI.

General & Model Routing

{
  "general": {
    "plan": {
      "modelRouting": false
    },
    ...
  }
}

modelRouting: Turn this false if you don't want the agent to automatically fall back from a larger Pro model to a smaller Flash model when it exits Plan Mode. If left true, you may experience bugs where the agent jumps to a significantly less capable model and struggles to complete complex tasks.

UI

{
  "ui": {
    "footer": {
      "hideContextPercentage": false
    },
    "showMemoryUsage": true,
    "showModelInfoInChat": true,
    ...
  }
}

hideContextPercentage: Set to false to permanently show how much of your current context window you are using in the footer. It is critical to keep a close eye on this to maintain agent performance.
showModelInfoInChat: Set to true to show exactly which model is being used for every single turn in the chat. This is crucial for verifying that the agent hasn't quietly downgraded to a smaller model.

Model Selection

{
  "model": {
    "name": "gemini-X.Y-pro-preview"
  }
}

name: Lock your model to always use the latest "Pro" (or "Pro Preview") model. While you can switch to "automatic" or a "Flash" model to save tokens during small tasks, the Pro models are significantly better at debugging and making complex architectural changes.

Experimental Features

{
  "experimental": {
    "plan": true,
    "modelSteering": true,
    ...
  }
}

plan: Set to true to allow read-only plan mode. This lets you bounce ideas off the AI and generate a plan before it jumps into building. It will explore your code and give feedback based on your ideas.
modelSteering: Set to true to enable injecting commands while the agent is in a chain of thought. If you see the agent start heading down the wrong path, you don't have to kill the process; you can simply type a comment to nudge it ("Look out for this pitfall", or "I prefer to use this build command").

The Superpowers Extension

If you want to immediately supercharge Gemini's methodical workflows, you can install the Superpowers extension (see our detailed breakdown below). However, we recommend starting without it for your first few projects so you understand how the vanilla agent behaves before manipulating it.

gemini extensions install https://github.com/obra/superpowers

Context Files

Do not create a user-level ~/.gemini/GEMINI.md file immediately. Wait until you have a solid understanding of how the model behaves and know exactly what you want to change globally.

Sandbox Mode (Docker)

If you are concerned about the security of running an agent on your system, it's possible to start Gemini in an isolated Sandbox mode by passing the --sandbox flag (gemini --sandbox). This runs the agent inside a Docker container (or some other sandbox environment of your choosing).

The downside is the container will not have your local system tools installed, forcing the agent to start fresh. The upside is you can specify exactly which Docker container it enters, meaning if you have a predefined Docker build environment, Gemini can work safely inside it without touching your host machine. For full details on passing Docker arguments and configuring environments, see the Gemini Sandbox Documentation.

The Concept of "Context"

To get the most out of your coding agent, you must understand how it perceives the world through Context. Setting up and managing context effectively is a critical skill for maintaining an agent's performance and accuracy. There are two distinct types of context you need to manage: Working Context (the agent's short-term memory during a session) and Starting Context (your configuration files).

1. Working Context (Session Memory)

The "Working Context" is the temporary memory the agent builds dynamically as you chat with it. Every file it reads, every command output it sees, and every message you type fills up its "context window."

The Crucial Limitation: The agent has a finite amount of context it can hold. As this window fills up, the agent becomes slower, more expensive to run, and most importantly, it loses performance and "forgets" earlier details. The model performs at its absolute best when it only holds the strictly relevant content in its context window.

Managing Your Working Context

To mitigate this limitation and maintain high performance, you must proactively manage your session context:

1. Prevent Premature Filling (The First Line of Defense) Before you even think about clearing your context, you should try to protect it from filling up with irrelevant information:

Stay On Topic: Do not ask the agent to perform tasks or answer questions that are not relevant to the current objective. Keep sessions focused on a single feature or bug.
Guardrail Exploration: Protect the model from exploring massive, irrelevant directories or files. Use tools like .geminiignore (or equivalent) to hide compiled assets, dependency folders, and other noise.
Beware of High-Output Tools: Be cautious when asking the agent to run commands that produce extremely long terminal outputs. Suggest it uses grep, head/tail, or pagination instead.

2. Prune the Context Once the context inevitably starts to fill up, you have two primary commands to clean it:

Compressing/Compacting: This command tells the agent to summarize the older parts of the conversation, dropping massive file reads or lengthy command outputs, while keeping the high-level state of what you are working on.
Clearing: This command completely wipes the session history, effectively giving the agent amnesia about everything you've done so far. Use this when switching to an entirely new feature.

2. Starting Context (Context Files)

If you have to clear your session frequently to maintain performance, how do you prevent the agent from forgetting how your project works every time? The answer is Starting Context.

Starting Context is the permanent baseline knowledge you provide the agent when you start a new session. It is defined by markdown files—typically named AGENTS.md (or CLAUDE.md, .cursorrules, etc.)—which act as the "landmine detector" for the agent.

The Golden Rule: A recent study by ETH Zurich found that standard, auto-generated context files actually make coding agents worse. Human-curated files are the only ones that boost performance, and only when they are concise.

Why Auto-Generated Files Fail:

Attention Dilution: Large, verbose files distract the agent with irrelevant information.
Inference Costs: They increase token costs while reducing task success rates.
Reality Gap: Agents "anchor" to aspirational rules that don't match the reality of the existing code.
Maintenance Burden: Auto-generated files frequently include too much information, becoming quickly outdated.

To be effective, your context file must be human-curated and hyper-minimal. It is NOT an onboarding manual for the project—that is what your README.md is for. Instead, it is a list of "gotchas" that prevent the agent from making mistakes due to unique aspects of your specific codebase. In general, you should not include any information in your context files that the agent already knows, or can infer from your codebase without your input. Despite the recommendations of most of the agentic toolchains, you should not use the /init command to auto-generate a context file.

Best Practices for Your Context File:

The "Landmines-Only" Method: Only include non-obvious quirks of your codebase, strict architectural constraints, or specific CLI commands the agent frequently messes up.
Focus on the Invisible: If the information can be inferred by reading the code or the README.md, leave it out. Only document what the code cannot tell the agent.
Institutional Memory: Use the file to capture "lessons learned."

What NOT to include:

Standard CLI Commands: Don't include npm install or npm run dev if they do exactly what you'd expect.
High-Level Architecture: If your folder structure is standard, the agent will find it.
Boilerplate Documentation: Avoid copy-pasting your project's history or basic setup guides from the README.
General Language Rules: The agent already knows how to write clean code.
Avoid Aspirational Rules: Do not document "theoretical best practices" that aren't actually enforced.

This context is divided into two levels: System-wide (User) Context and Workspace (Project) Context. Both should be treated as living documents.

System-Wide (User) Context

Installed in your user home directory, this file defines your agent's persona and general behavior across all projects.

Workspace (Project) Context

Located in the root directory of your repository, this tells the agent how to operate specifically within that project. It should be committed to version control.

Skills, Subagents, and Workflows

To elevate your agent's capabilities beyond simple prompt-and-response, you should leverage Skills and Subagents. These tools enable complex, multi-step workflows with high reliability.

Skills

What are Skills?

Skills are modular, self-contained packages that extend an agent's capabilities by providing specialized knowledge, strict procedural workflows, and bundled resources. They transform the agent from a general-purpose AI into an expert with procedural memory for a specific task.

How do they work?

Dynamic Loading: Instead of dumping a massive prompt into your session every time (which eats up your token limit), a Skill uses Progressive Disclosure. The agent only loads the skill's instructions into context after it decides the skill is relevant or you explicitly activate it.
User vs Workspace Scoping: Skills can be installed globally for a user (available in all projects) or locally to a specific workspace. Workspace skills are excellent for standardizing team workflows.

Ideas for Custom Skills

Repo Setup: A skill that automatically checks dependencies, runs initialization scripts, and verifies the environment is ready for development.
PR Workflows: A skill that runs linters, generates a comprehensive PR description based on git diffs, and submits the PR via the GitHub CLI.
Deployment: A skill that builds the project, runs deployment scripts, and verifies the deployment succeeded.

Recommended Skills List

Superpowers

Superpowers is an open-source framework that forces AI coding agents (like Claude Code and Gemini CLI) to follow strict software engineering methodologies, overriding their default behavior of jumping straight into writing code.

When to use it: Superpowers is excellent for "vibe coding" new repositories, architecting large features, and learning how to properly constrain an agent. However, it can be overkill and token-heavy for day-to-day operations. While its initial brainstorming phase is incredibly helpful for vetting ideas and generating detailed plans, the subsequent execution phases automate much of the workflow. This is powerful, but it takes control out of your hands and requires careful monitoring to ensure the project doesn't drift.

Core Mechanics:

Mandatory Planning: The agent must ask clarifying questions and draft a PLAN.md specification before writing any implementation code.
Isolated Git Worktrees: Tasks execute in safe, isolated worktrees to protect your main branch.
Forced TDD: Enforces a Red-Green-Refactor cycle. The agent must write a failing test before writing feature code.
Systematic Debugging: Replaces AI "guess-and-check" fixes with a structured, multi-phase root-cause investigation.

Note: Skills can sometimes be tricky to trigger reliably. For Superpowers, the most consistent way to initiate the workflow is to explicitly ask the agent to "brainstorm" a new feature with you.

Subagents

What are Subagents?

Subagents are specialized, independent instances of the agent that can be delegated specific tasks. Instead of the main agent doing all the work (and bloating its context window), it can spawn a subagent to handle a focused job and report back the results.

How to trigger them

Subagents are typically exposed as tools to the main agent. You can explicitly ask your agent to "delegate this task to the codebase_investigator subagent" or "use the generalist subagent to run these tests." The main agent will then orchestrate the execution and incorporate the subagent's summary into your session.

Making your own subagents

TODO: Describe how to make your own sub-agents for the different tools. explain when it makes sense to make your own sub-agents. In GemIIni, for instance, you can specify which model specific agents should use. So you could have a junior generalist and a generalist, where the junior generalist uses the smaller model for simpler tasks.

Day-to-Day Workflows

TODO: this doesn't belong here. this is more like recommendations for how to use it. the section should be more about tools/features of the agents. This is where a section on / commands would go. Consider if this section belongs somewhere else or should be removed. I don't really even think the content is good or correct. skills and agents should be triggered more organically if activated correctly. We shouldn't directly address specific skills.

By combining Skills and Subagents, you can establish powerful day-to-day workflows:

Planning: Activate a planning skill (like writing-plans) to draft a comprehensive design document before writing code.
Implementation: Use a subagent-driven workflow (like the subagent-driven-development skill) to delegate independent components to parallel subagents.
Debugging: When a test fails, activate a debugging skill (like systematic-debugging) or delegate to a specialized investigator subagent to find the root cause without polluting your main session context.
Review: Before merging, use a review skill (like requesting-code-review) to ensure your changes meet all project standards and conventions.

Resource Index

Below is an index of the resources available in this repository. These are samples and templates you can use to configure your own agents.

Example Agent Contexts

User Level Context File: An example template for your system-wide user context.
Workspace Level Context File: An example template for your workspace/project context.

Example Prompts

TODO: Remove prompts in favor of a skill or a slash command, or understand how the superpowers skill is actually better positioned for most of these tasks

Codebase Tour Guide: Map out and explain an unfamiliar subsystem.
Deep Bug Investigation: Perform methodical root-cause analysis.
Devil's Advocate PR Review: Find edge cases before opening a PR.
Generate Exhaustive Tests: List boundary conditions before writing test code.
Plan New Feature: Draft a design document before implementing a feature.
Review an Existing AGENTS.md File: Analyze an existing context file and suggest improvements.

Example Skills

These skills can be found in the skills/ directory. Each skill contains a SKILL.md file defining its behavior. WARNING: These skills are untested so far and still under development. TODO: Test and refine the skills. Remove skills that are not actually helpful or recommended

Name		Name	Last commit message	Last commit date
Latest commit History 13 Commits
context_files		context_files
prompts		prompts
settings		settings
skills		skills
AGENTS.md		AGENTS.md
GEMINI.md		GEMINI.md
README.md		README.md
ideas.md		ideas.md

Folders and files

Latest commit

History

Repository files navigation