Optimizing AI Agent Instructions for Better Coding Productivity

Rethinking Agent Instructions as Trigger-Based Systems

Instead of treating agents.md or claude.md files as static documentation, the author treats them as dynamic configuration files that control agent behavior. The core insight is that the 'description' field of a skill should not be a verbose explanation of what the tool does, but rather a set of trigger keywords that tell the model exactly when to pull that skill into its context. By refining these triggers, the author ensures that agents only access relevant tools, reducing hallucinations and unnecessary sub-agent spawning.

Eliminating 'AI Slop' Through Explicit Constraints

To combat the tendency of models (like Claude 3.5 Sonnet or GPT-4o) to be overly proactive or verbose, the author implemented strict behavioral guardrails. This includes:

• Tone Matching: Explicitly defining a persona and writing style in the system prompt to force the model to mirror the user's preferred communication style.
• Constraint Injection: Adding specific instructions to avoid 'any' types in TypeScript, preventing the creation of draft PRs, and requiring agents to verify PRs against local diffs before submission.
• Contextual Awareness: Forcing the agent to include the model slug and harness name in PR descriptions to track which models are performing well on specific tasks.

The 'Babysit' and 'File' PR Workflow

Rather than relying on generic agent capabilities, the author created specialized skills for PR management. The 'Babysit PR' skill focuses on monitoring CI/CD feedback, rebasing, and distinguishing between infrastructure flakes and actual code issues. The 'File PR' skill enforces a specific communication structure: a concise problem statement followed by a solution, explicitly forbidding 'implementation inventories' that clutter PR descriptions. By providing the agent with 'good' vs. 'bad' examples of PR titles and descriptions, the author significantly improved the readability and utility of automated contributions.

Iterative Tuning via Historical Analysis

Instead of manually writing every instruction, the author uses the AI to audit its own past performance. By asking the model to analyze chat histories and identify common failure modes across different models (e.g., Opus, Sonnet, GPT-4o), the author identifies recurring patterns of 'slop' and writes targeted instructions to steer the models away from those specific behaviors. This creates a feedback loop where the system instructions evolve based on actual, observed friction points in the development workflow.