Context is King (For your Code) - How a CONTEXT.md file can yield better AI coding results and maintain consistiency across multiple development sessions

[mojabbar]

---

Every time an AI coding assistant opens your repo, it starts from scratch. What if it didn't have to?

---

Software engineers have always written README files. They explain what a project does, how to install it, maybe how to contribute. But READMEs were written for humans scanning a page. They weren't designed for the way AI coding assistants consume a codebase — and that distinction matters more with every passing month.

When GitHub Copilot or another AI assistant helps you refactor a service layer on Monday, it does good work. By Wednesday, when you ask it to add a new endpoint, it has no memory of the patterns you established together. It re-reads files. It re-discovers conventions. It spends context window tokens rediscovering things it already knew.

There's a simple, practical way to reduce that overhead — and it starts with a single file at the root of your repository.

What is CONTEXT.md?

A CONTEXT.md file is a living document with two audiences:

1. Human developers who are new to the codebase and need to get up to speed.
2. AI coding assistants that need structured, durable context to work effectively across separate sessions.

Both matter. But the second is the reason this pattern is emerging now.

Think of it as a briefing document — not the full source code, not the full docs, but the distilled understanding that an experienced team member carries in their head: how the pieces fit together, what the conventions are, where the boundaries lie, and what to watch out for.

The problem: context is expensive

When GitHub Copilot is asked to make a change in a codebase, the first challenge is rarely writing the code. It's understanding the system well enough to write code that fits.

That means answering questions like:

• What kind of application is this?
• Where does business logic belong?
• What are the important domain entities and how do they relate?
• What conventions does this repository follow?
• What commands should be run to build, test, and validate changes?
• What gaps or constraints should the assistant avoid assuming away?

Without explicit answers, the assistant discovers them on the fly — reading files, searching for patterns, inferring architecture from implementation details. Sometimes that works. Sometimes it produces code that compiles but doesn't match the structure and conventions of the repository.

This is also where the context window matters. Even with strong retrieval and search, there's a cost to spending tokens on rediscovering the basics of the codebase in every new session. A concise, well-maintained context document lowers that cost directly.

Why a README is not enough

README files are useful, but they're usually optimized for project introduction, setup, and contribution. They answer: What does this repo do? How do I run it?

That's necessary, but insufficient for AI-assisted development.

A useful CONTEXT.md goes deeper:

• Architecture — not just the framework names, but the specific layers, the data flow, and how they connect.
• Domain model — entities, primary keys, foreign key relationships, cascade rules. This saves the assistant from parsing every migration file.
• Patterns and conventions — repository pattern? Thin controllers? Where does business logic live? If the assistant doesn't know, it will generate code that works but doesn't fit.
• File paths with purpose — not a raw directory listing, but annotated context. "Route handlers are thin controllers that delegate to repositories" tells the assistant how to structure new code.
• Exact commands — make test-api is more useful than "run the API tests." An assistant that knows the exact invocation can verify its own work.
• Known gaps — if there's no auth layer, or a library is intentionally outdated, say so. This prevents the assistant from building on assumptions that aren't true.

Put simply: a README introduces the project. A CONTEXT.md briefs the assistant before work begins.

What this looks like in practice

In the OctoCAT Supply Chain Management demo application, the CONTEXT.md opens with a tech-stack table, then covers the domain model with an ASCII ERD that both humans and AI parse well:

Supplier ──< Delivery ──< OrderDetailDelivery >── OrderDetail >── Product
                                                       │
                                                     Order
                                                       │
                                                     Branch
                                                       │
                                                  Headquarters

Below that, a table summarizes each entity with its primary key, key fields, and foreign key relationships — enough for an assistant to write a new repository method or migration without first reading every model file.

The conventions section is even more valuable. It states explicitly:

• Thin controllers: Route files validate input and delegate to repository methods. Business logic belongs in repositories.
• DB column naming is snake_case; TypeScript models use camelCase. The repository layer handles conversion.
• Always use parameterized queries — never string-interpolate user input into SQL.
• Use existing error classes (NotFoundError, ValidationError, ConflictError) for consistent HTTP responses.

An assistant that reads these four lines before generating code will produce output that is structurally aligned with the rest of the codebase. Without them, it has to infer all of this from scattered source files — or guess.

What to include in your own CONTEXT.md

You don't need to follow a rigid template, but these sections tend to carry the most value:

1. Project overview

What the application is, who it's for, and the major technologies. A table works well — AI assistants parse structured data efficiently.

2. Repository layout

An annotated directory tree — not every file, but the structural landmarks with brief descriptions of what each directory contains and why.

3. Domain model

Entities, primary keys, key fields, and foreign key relationships. If the codebase has one, an ASCII ERD packs a surprising amount of information into a few lines.

4. API surface or application boundaries

Route prefixes, HTTP methods, request/response conventions. This saves the assistant from reading every route file to understand the API shape.

5. Architectural patterns and conventions

This is consistently the highest-value section for AI assistants. Be explicit about where business logic lives, how data access works, how errors are handled, what naming conventions exist, and what patterns must be preserved.

6. Build, run, and test commands

Include the actual commands, not descriptions of commands. Assistants can use these to validate their own changes.

7. Environment variables

A table of variables, defaults, and descriptions. AI assistants frequently need to generate configuration-aware code.

8. Testing strategy

Which tools, where test files live, and what patterns they follow — mocking strategies, test database setup, fixture conventions.

9. Known gaps and constraints

One of the most underrated sections. If authentication is mocked, if a service layer doesn't exist yet, or if a library is intentionally pinned to an older version, say so. This prevents the assistant from generating code that assumes infrastructure that isn't there.

How CONTEXT.md fits with GitHub Copilot configuration

If you're already using GitHub Copilot, you might have a .github/copilot-instructions.md file, path-scoped instruction files, or custom skills. CONTEXT.md doesn't replace any of these. It complements them.

A useful way to think about the split:

File	Purpose
CONTEXT.md	What the codebase is — architecture, domain model, patterns, commands
copilot-instructions.md	How the assistant should behave — review style, priorities, tone
instructions/*.instructions.md	Scoped rules for specific file paths (API conventions, frontend patterns)
skills/*/SKILL.md	Reusable workflows for specific tasks (generating endpoints, writing tests)

CONTEXT.md is the foundational layer. A repository instruction that says "use the repository pattern" is more effective when the assistant already knows what your repository pattern looks like from CONTEXT.md.

Treat it as a living document

The value of CONTEXT.md comes from staying current. This is not a one-time onboarding artifact. It should be updated when:

• New entities or services are added
• Architectural patterns or boundaries change
• Build or test workflows change
• New environment variables are introduced
• New conventions are established

One practical pattern: update CONTEXT.md in the same pull request that changes the architecture. Another is to ask the assistant to update the file as the final step after a substantial change. The assistant that just made the change is the best author for documenting it — and the next session benefits immediately.

Some teams add a Last updated timestamp at the top and include CONTEXT.md updates in their PR checklist for architectural changes.

Getting started

The easiest way to start is to ask GitHub Copilot to draft the first version for you:

Create a CONTEXT.md document that provides info for new developers and persistent context for AI coding assistants, reducing the need to re-read the codebase each session.

From that prompt, the assistant will explore the codebase and produce a structured document covering architecture, domain model, API surface, patterns, commands, and known gaps. It won't be perfect — you'll catch nuances it missed, unwritten conventions, historical context — but it gives you something concrete to iterate on instead of a blank page.

Then:

1. Review and correct anything imprecise.
2. Add the sections only your team can supply — especially constraints, conventions, and assumptions.
3. Keep refining it as the codebase evolves.

The first version doesn't need to be perfect. It just needs to be useful.

The bigger picture

AI coding assistants are becoming genuine collaborators in the development process. But collaboration requires shared context.

A human pair programmer who joins your team spends weeks absorbing the codebase — sitting in meetings, reading code, asking questions, building a mental model. We invest in onboarding because we know that shared context is what makes a teammate effective.

An AI assistant doesn't need weeks. It needs a well-structured file that gives it the map before it starts navigating. That investment is small — a single document, maintained over time — but the return compounds with every session.

CONTEXT.md is that file. It's simple, it's practical, and it makes your AI assistant better at its job from the first prompt.

---

Add a CONTEXT.md to one of your repositories this week. Ask GitHub Copilot to draft it, review the output, and see how it changes the quality of your next coding session. The file is small. The difference is not.