By Vicente Arteaga Gomez
MisLinux · Last updated: April 4, 2026
This is a standalone MisLinux article about how I work with AI coding agents such as GitHub Copilot, Claude, and OpenAI Codex. It reflects my own workflow and opinions only; I am not affiliated with, sponsored by, or endorsed by Microsoft, Anthropic, or OpenAI.
The most useful change I have made for AI-assisted development is not a newer model or a longer prompt. It is documenting Context, Intent, and Rationale close to the work itself.
I usually shorten that to CIR:
- Context: what environment, system state, history, or constraint already exists
- Intent: what I am trying to achieve right now
- Rationale: why this approach was chosen instead of another one
That sounds simple, but it closes one of the biggest gaps in AI-generated code: the model often sees what the code does without clearly seeing why it was shaped that way.
Why tools like Copilot, Claude, and Codex still miss important things
Modern coding agents are genuinely useful. They can trace files, suggest patches, explain APIs, and move through a repository faster than a human can when the work is mechanical.
But they still struggle in a few recurring situations:
- a configuration looks strange for a good historical reason
- a seemingly redundant check exists because production failed without it
- an unpopular dependency was chosen to match another system
- a simple-looking refactor would quietly break deployment, compliance, or recovery workflows
When that reasoning only lives in a developer's head, an AI agent has to guess. Sometimes it guesses well. Sometimes it confidently "improves" the exact thing that was protecting the system.
The missing piece is rarely context alone
Many teams already write some context down. They might have a README, a ticket, or a comment saying what a script is for.
That helps, but it is incomplete.
The missing piece is usually the combination of:
- what already exists
- what change is intended
- why that change was implemented that way
Without the third point, AI tooling tends to optimize for local neatness instead of system truth.
A guard clause looks ugly, so it gets removed. A duplicate-looking config path seems unnecessary, so it gets unified. A staging-only publish flow seems too specialized, so it gets generalized and breaks production.
Rationale is what tells the agent, "This is not an accident. Preserve the tradeoff unless you are deliberately changing it."
Why I layer CIR instead of keeping it in one place
I have found that AI agents work best when CIR exists in more than one layer.
1. Repo-level guidance
At the repository level, I like a file such as .github/copilot-instructions.md or another top-level instructions document.
That is where I keep things like:
- the big-picture architecture
- expected deployment paths
- important external systems
- how changes are normally validated
- repo-wide CIR notes for recent design decisions
This helps the agent avoid making changes that are technically tidy but operationally wrong.
2. Directory-level AGENTS.md
Inside important directories, I like an AGENTS.md that narrows the scope.
That file is where I describe:
- what this directory is responsible for
- what kinds of changes are normal or risky here
- local naming rules and workflow expectations
- the Context / Intent / Rationale behind the current shape of that area
This is the layer that helps an agent stop treating every folder like generic code. A Blogger-content directory, a Terraform directory, and a Docker build directory may all be in the same repo, but they need different instincts.
3. CIR near the code itself
For important scripts, modules, classes, or tests, I like a short CIR block close to the code.
That is where the most specific reasoning belongs:
- why this function exists
- which edge case it protects against
- why a weird branch is intentional
- which operational failure led to this implementation
This is often the difference between an AI agent preserving a critical safeguard and deleting it because it looks redundant.
What this looks like in practice
If I only write one top-level instruction file, the agent gets broad awareness but misses local tradeoffs.
If I only write comments in code, the agent may understand a function but miss the system around it.
If I only write an AGENTS.md in one folder, the agent may still miss the repo-wide deployment or compliance model.
Layering the guidance works better because each level answers a different question:
- repo instructions explain the operating environment
- directory `AGENTS.md` explains local expectations
- code-level CIR explains why this implementation looks the way it does
That combination reduces accidental "helpful" changes.
The benefit is not only for AI
The nice side effect is that humans benefit too.
A future maintainer can skim the repo-level notes, move into the directory-level guidance, and then understand the code-level tradeoff without hunting through chat logs or old tickets.
That matters because AI-assisted work creates a new failure mode: important design reasoning can end up trapped in one-off conversations with the tool instead of becoming part of the project memory.
If the reasoning does not land in the repository, it might as well not exist.
How CIR changes the quality of AI edits
When I work this way, the output from coding agents improves in very practical ways:
- they are less likely to remove deliberate safety checks
- they make fewer wrong assumptions about deployment or publishing flow
- they can explain their own changes in terms of the existing system
- they are more likely to preserve edge-case handling
- they require less corrective prompting from me afterward
In other words, CIR turns the agent from a fast code generator into a better repository participant.
My rule of thumb
If a future engineer or AI agent could reasonably ask, "Why on earth is it done this way?", I try to record the answer where the question will naturally arise.
That usually means:
- repo-wide context near the repo root
- local intent in the relevant directory
- implementation rationale in or near the code itself
I do not try to document everything. I try to document the decisions that would otherwise be silently lost.
Final thought
Copilot, Claude, and Codex are all more useful when they are not forced to reverse-engineer intent from raw files alone. The better I capture Context, Intent, and Rationale in the repository, the more often the agent makes a change that is not only syntactically correct, but operationally correct too.
For me, that is the real productivity gain: not just faster edits, but fewer wrong edits.
