Fix the Context, Not the Code: Two Rules for Faster AI Development

Executive overview

Developers working with AI tools commonly waste dozens of hours debugging AI-generated code by fixing symptoms rather than root causes. The core insight is that bad AI output is almost always a context problem, not a code problem. When AI writes bad code, stop and ask what caused the AI to write it that way — then fix the context, not the output. Two concrete rules — persistent context for complex tasks, and incrementally built rules — can reduce debugging time by 80% and create compounding productivity gains over time.

The compounding context mindset

• Traditional AI-assisted development resets context each session, producing linear productivity growth.
• Encoding lessons into the project's scaffolding creates exponential capability gains as the codebase grows.
• The goal is to build the "factory" (the context that guides AI) rather than just the widget the factory produces.
• Complex features should get easier to build over time, not harder — that's the signal you're doing this right.

Rule 1: Persistent context for complex tasks

• Most AI-assisted projects have three documents: a specification (what to build), a blueprint (how to build it), and a roadmap (to-do list).
• When a subtask is too large for the AI to complete in a single conversation, stop and treat it differently rather than retrying the same prompt.
• After several failed attempts, ask the AI to summarise what it tried, the errors encountered, and the root complexities.
• Feed that summary to a more capable model (e.g. Opus) and ask it to produce a detailed sub-task to-do list for the specific feature or bug.
• Bake lessons learned directly into the sub-task to-dos — one or two sentences per item — so future AI sessions can avoid the same mistakes.
• Once the feature or bug is resolved, delete the sub-task document and return to the main roadmap.

Rule 1 in practice: browser session hang bug

• A web-scraping project had browser sessions that hung and never closed, wasting time and money.
• Seven or eight in-conversation fix attempts all failed despite varied prompts.
• Lessons learned were passed to Opus to create a structured markdown sub-task file.
• Sonnet then executed against that file, resolved the bug, and the sub-task document was deleted.

Rule 2: Build rules incrementally, not upfront

• Importing other people's shared rule sets (GitHub, Twitter) produces bloated, irrelevant configuration.
• Start with an empty rule set and add rules only when a real recurring mistake is discovered.
• Once the AI has fixed a repeating error, ask it to write a rule capturing that fix in the project's rule file (CLAUDE.md, .cursor rules, etc.).
• AI-authored rules referencing prior lessons are more precise than hand-written ones.

Rule 2 examples from real projects

• Gemini SDK version mismatch: Three hours lost because the AI coded against an outdated SDK. After supplying correct documentation and fixing the issue, a rule was added instructing the AI to check SDK docs before writing any related code.
• Model naming cutoff: AI knowledge has a training cutoff; it kept referencing Gemini 1.5 when 2.5 was needed. A rule was added specifying the exact model identifiers to use throughout the project.
• CLI tool credentials: AI repeatedly failed using the Supabase CLI because it lacked credentials and attempted to create local instances. After resolving it, a rule was added with correct CLI usage patterns and a path to the credentials file.

Summary: what separates 10x AI engineers

• When AI writes broken code, average developers immediately try to patch the output.
• High-output AI engineers trace back to the context that caused the mistake and fix that instead.
• Persistent sub-task documents prevent re-learning the same lessons across sessions.
• Incrementally grown rule files encode project-specific knowledge that generic prompts cannot carry.
• The result: building complex features becomes progressively faster, not progressively harder.