AI Code Generation, Smarter and More Cost-Efficient with Context Engineering

We’ve all hit that wall: endless tweaks to prompts, fixing AI-generated bugs, and wondering why such powerful tech feels so hit-or-miss. It often feels like working with a brilliant but forgetful junior developer who hasn’t been onboarded to your project.

The problem isn’t the model’s power; it’s the context we give it. Or rather, the context we don’t give it.

This post is for you if you’ve ever been frustrated by an AI assistant that just doesn’t “get” your project. We’ll explore how a well-crafted DETAILS.md can save you time, reduce costs, and dramatically improve the quality of your AI-generated code.

Research shows models hallucinate packages; The average percentage of hallucinated packages is at least 5.2% for commercial models and 21.7% for open-source models.

The High Cost of Runtime Research

When an AI assistant lacks a high-level overview of your project, it’s forced to build one on the fly. It skims through your files, trying to piece together the architecture, dependencies, and coding conventions. This “runtime research” is not only slow, but it’s also incredibly expensive. Every file it reads, every line it analyzes, adds to the token count of your API call. This translates directly to higher costs.

More importantly, the results are often suboptimal. The AI might generate code that works in isolation but clashes with your existing patterns, ignores crucial utility functions, or re-invents a wheel you already have spinning smoothly in another module. It’s a frustrating cycle of generating, correcting, and re-generating that kills productivity.

Your Solution: The DETAILS.md File

A DETAILS.md file acts as a concise, high-level “cheat sheet” for your AI assistant. It’s not meant to replace your full documentation, but to provide an essential, distilled overview of the project. Think of it as the onboarding document you’d give a new human developer.

A great DETAILS.md file typically includes:

• Project Overview: What does the project do? What problem does it solve? Who are the target users?
• Architecture: A high-level description of the project’s structure (e.g., microservices, monolithic, MVC). A link to an architecture diagram is a huge plus.
• Key Components: A list of the most important files, directories, modules, or classes and their purpose. This helps the AI know where to look for relevant code.
• Coding Conventions & Stack: The programming languages and versions (Python 3.11), frameworks (Express v4), and any specific patterns, libraries, or style guides (PEP 8) to follow.
• “How-To” Guides: Simple instructions for common tasks like running tests, setting up the local environment, or interacting with the database.

By providing this information upfront, you stop treating your AI like a black box and start treating it like a team member. It no longer needs to guess or reverse-engineer your project’s context.

🤔 Why This Matters

Adopting this practice isn’t just a theoretical exercise. It delivers massive, measurable improvements in efficiency, cost, and reliability.

Automating Your Context: Human-Focused vs. Agent-Focused Tools

Manually creating and maintaining a DETAILS.md file is a great start, but it can become a chore. This is where automated tools come in, but it’s crucial to distinguish between tools designed for humans and tools designed for AI agents.

A great example of a human-oriented tool is Devin’s DeepWiki. It excels at indexing a repository to produce a searchable, human-readable wiki with architecture diagrams and documentation. It’s fantastic for helping a human developer get up to speed on an unfamiliar codebase.

However, when you need to provide context to an AI agent to perform a specific task, you need a different approach. This is where agent-oriented tools shine.

For instance, some tools are now being built specifically for this purpose. A good friend of mine developed one called Detailer that connects to a GitHub repository and automatically generates a DETAILS.md file tailored for AI agents. It’s a neat approach that creates a standardized starting point that can be used across different platforms.

One Context to Rule Them All: Symlinking for Different Agents

Instead of maintaining separate CLAUDE.md – for Claude Code, GEMINI.md – for Gemini CLI, or AGENTS.md – for OpenAI Codex files, you can use a tool like Detailer to generate a single, canonical DETAILS.md. You can then use symbolic links to point different agent configurations to this one source of truth.

For example, you can set up your project like this:

# Symlink it for various AI coding tools
ln -s DETAILS.md CLAUDE.md      # For Claude Code
ln -s DETAILS.md GEMINI.md      # For Gemini CLI
ln -s DETAILS.md AGENTS.md      # For OpenAI Codex

If you’re using an IDE like Cursor or Windsurf, you can add a rule to use the DETAILS.md file as the context for the agent.

ALWAYS read @DETAILS.md before taking any action to get context.

This elegant approach ensures that every agent-be it OpenAI Codex, Gemini CLI, Claude, or an IDE like Cursor-gets the same, up-to-date context without any duplication of effort. It’s the ultimate “write once, inform everywhere” strategy for context engineering.

The Biggest Pitfall: LLMs Don’t Read Like You (Understanding Context Rot)

Here’s a critical insight from AI research that explains why a focused DETAILS.md is so important: LLMs don’t read like humans do.

We assume that if we paste a bunch of files into the prompt, the model will read and understand all of it equally. But that’s not what happens. Multiple studies have confirmed that models pay the most attention to the very beginning and very end of the context window. Information stuck in the middle has a much higher chance of being ignored or forgotten-a phenomenon explained by the “lost-in-the-middle” problem. The research demonstrates that LLMs have a strong “U-shaped” attention bias, paying the most attention to the start and end of the context window, regardless of where the most relevant information is.

This phenomenon is known as “Context Rot.” The longer and more unfocused your context is, the more likely the AI is to get lost. A huge, million-token context window is useless if it’s mostly filled with irrelevant “noise” that drowns out the “signal.” This is why a concise DETAILS.md is often more effective than naively dumping your entire codebase into a prompt. The goal isn’t to provide more information, but more relevant information, placed strategically where the model will see it.

The Takeaway: Context is Everything

If you’re frustrated with your AI coding tools, don’t blame the model. The biggest gains in code quality, speed, and cost-efficiency don’t come from switching to the “latest and greatest” LLM. They come from mastering the art and science of providing high-quality context.

Start small. Create a DETAILS.md for your current project. Be explicit about your architecture and standards. And watch as your AI assistant transforms from a clumsy, unpredictable intern into a valuable, reliable member of your team.

Want to Dig Deeper?

If you want to explore more about this stuff, here are some of the excellent resources I used to inform this post:

• Overviews and Mindset:

• Academic and Research Papers:

• Best Practices:

• Cost Optimization:

What are your biggest frustrations with AI code generation? Have you tried any of these techniques, or do you have others that work well? I’d love to hear about it! 🤘