Working with modern AI coding agents (such as Claude Code, OpenCode, Codex, and Antigravity) is less about typing magic prompts and more about engineering clear constraints, maintaining clean context, and building reusable workflows.

When developers struggle with coding agents hallucinating or breaking existing features, the culprit is almost always unbounded scope, noisy context windows, or missing project instructions. Here are the core habits and tools to get consistent, reliable results from your agent.

Two Core Habits for Working with Agents

1. Scope the Work

AI models perform best when solving well-defined, modular problems. Giving an agent an open-ended goal like "refactor our auth system and fix all bugs" invites assumptions and unneeded churn.

• Break tasks into small, clear steps: Divide features into discrete chunks—such as writing a schema first, implementing the backend handler next, and adding client wiring last.
• Use Plan Mode: It’s there for a reason :) Plan mode forces the agent to research files, verify assumptions, and propose a concrete step-by-step roadmap before making destructive edits.
• Review and update the plan: Don’t passively let the model assume architecture decisions. Inspect the generated plan, adjust steps, correct constraints, and sign off before code is written.

# Example: Scoping a feature request with clear checkpoints
Step 1: Inspect `src/auth/jwt.ts` and verify token expiration handling.
Step 2: Add refresh token rotation function in `src/auth/service.ts`.
Step 3: Update unit tests in `test/auth.test.ts` and verify with `npm test`.

2. Steer the Model & Maintain Context Hygiene

The quality of an LLM’s output is directly tied to the cleanliness of its context window. A cluttered context containing multiple failed attempts confuses the model and degrades reasoning.

• Use compaction wisely: Compaction and summarization help reduce context size, but they can also strip away crucial edge-case details or file paths. Compact intentionally when moving between major milestones.
• Add clear, proactive instructions: Provide explicit guardrails upfront to prevent the model from drifting into unwanted refactors or library additions.
• The Undo / Rewind Rule: If the model makes a mistake or heads in the wrong direction, undo/rewind instead of asking it to fix its own mistake. Asking a model to debug its hallucination in the same thread pollutes context with bad code. Rewind to before the mistake, refine your prompt with the missing instruction, and rerun.

Persistent Project Instructions: AGENTS.md

Rather than re-typing coding guidelines in every conversation, use a persistent instruction file placed at the root of your repository. This file serves as the single source of truth for agent behavior across your project.

Different coding agents look for specific filenames, but the underlying concept is identical:

• Claude Code → CLAUDE.md
• Codex / OpenCode / Antigravity → AGENTS.md

These instruction files help the model instantly understand your project structure, conventions, build/test commands, and overall technical direction without guessing.

Modularizing Large Instruction Files

If your instruction file gets too long, split the instructions into dedicated sub-files—such as styling.md, architecture.md, or api-rules.md—and reference them from the main instruction file. You can name these files whatever makes sense for your team.

You can also reuse these modular files across future projects—for instance, standard rules for a specific framework, package manager workflow, or coding convention.

Be Specific with Actionable Rules

Avoid vague phrases like “write clean code” or “follow best practices”—the model cannot read your mind. Instead, provide concrete, enforceable rules:

• Specific naming conventions: e.g., “Use snake_case for Python helper functions and PascalCase for React components.”
• Function length: e.g., “Keep functions small and focused (< 40 lines where feasible).”
• Prohibited patterns: e.g., “Never use `any` in TypeScript; do not introduce external styling libraries.”
• Style constraints: e.g., “Don’t use emojis in code comments or log statements.”
• Commit conventions: e.g., “Write meaningful conventional commit messages (e.g., `feat(auth): ...`).”

# Example AGENTS.md / CLAUDE.md snippet

## Project Conventions
- Framework: Vanilla HTML5 / CSS / ES6 JavaScript (No React, no build steps).
- State: Single source of truth is `data.json`. Always update `data.json`, never hardcoded constants.
- Code Style: Small focused functions, semantic HTML5 tags, 2-space indentation.
- Anti-patterns: Do not add external npm packages unless explicitly approved.
- Verification: Always verify layout across dark and light modes before completing tasks.

Keep instructions up to date: As your codebase evolves, prune rules that are no longer relevant. If you notice the model repeatedly making the same mistake, immediately codify a clear rule to prevent it in the future.

Scaling Workflows with Skills

If you find yourself guiding an agent through the same multi-step workflow over and over, Skills make those tasks faster, more deterministic, and consistent.

You can build custom skills tailored to your repository or leverage pre-made community skills for standard operations (such as database migrations, API testing, or documentation audits).

The Verification Skill

A verification skill is particularly powerful. It guides the model through a disciplined checklist—running linters, checking edge cases, executing test suites, and confirming output criteria—before marking any task as complete.

Context Optimization: `reference.md` alongside `SKILL.md`

To keep your primary skill file lean, place a reference.md next to SKILL.md. Instruct the model to read the reference file only when it encounters specific complex scenarios. This keeps the active context compact and avoids token bloat during routine execution.

Executable Scripts in Skills

You can package executable scripts (such as Python validation scripts or shell helpers) inside a skill. When an agent needs to perform a complex transformation or check schema integrity, executing a script guarantees 100% deterministic accuracy without LLM calculation errors.

# Skill Directory Structure
.skills/
  deploy-verifier/
    SKILL.md          # Core workflow instructions and checklist
    reference.md      # Detailed deployment edge cases and error codes (read on-demand)
    scripts/
      check_health.py # Executable health check script run by the agent

Summary Checklist

1. Plan First: Scope tasks into bite-sized units; review the plan before execution.
2. Keep Context Clean: Rewind and re-prompt on mistakes rather than chaining error fixes.
3. Codify Rules: Maintain an active AGENTS.md / CLAUDE.md with concrete, specific constraints.
4. Automate with Skills: Turn repetitive workflows and verification checklists into reusable skills.