An AI can open a repository, find files, and produce code in minutes. Even so, it may choose the wrong architecture, repeat a known bug, or change a workflow the team wanted to preserve. Often, the problem is not the model’s ability; it is the context available when it makes decisions.
A well-contextualized project explains what is being built, which rules matter, how the team organizes code, and how to verify a change. This does not require a massive prompt. It requires reliable information that is easy to find and kept up to date with the software.
Context is more than a good instruction
An instruction tells the AI what to do for a specific task. Context also includes what it needs to know to decide how to do it: the product goal, domain vocabulary, technical boundaries, established patterns, verification commands, and previous decisions.
The Anthropic team describes context engineering as curating the information an agent receives throughout a task, including instructions, tools, examples, and data retrieved when needed. Their article Effective context engineering for AI agents also highlights the limits of attention: adding more material does not always improve the answer.
In practice, a repository with short instructions and references to specific documents is often more useful than one enormous file combining product details, architecture, commands, and every historical exception.
Keep sources of truth separate
Before creating new files, decide where each kind of information belongs:
- Code and configuration show the actual state.
- Dependencies, scripts, routes, schemas, and tests reveal what the project implements. Documentation should not contradict those files.
- Documents explain the reasons and the business.
- Product goals, constraints, domain terms, and architectural decisions are rarely clear from code alone.
- Instructions guide the agent’s work.
- They say what to read, how to follow local patterns, and how to verify changes. They should not replace the specification or duplicate all the documentation.
When these sources disagree, the project needs an explicit rule for resolving the conflict. To understand the current implementation, inspect code and tests; to understand business intent, consult the responsible documentation and confirm that it still reflects what the team wants.
A small structure that makes context easy to find
There is no ideal directory tree for every project. One possible starting point is:
project/
├── AGENTS.md
├── README.md
├── docs/
│ ├── product/
│ │ ├── PRODUCT.md
│ │ └── glossary.md
│ ├── architecture/
│ │ ├── overview.md
│ │ └── decisions/
│ ├── quality/
│ │ └── testing.md
│ └── specs/
├── src/
│ ├── features/
│ └── shared/
└── tests/The README helps someone install and run the project. PRODUCT.md explains who it is for, what it needs to solve, and what is out of scope. A glossary defines terms that should not be used vaguely. The overview summarizes the main technical boundaries. Decision records—often called ADRs—preserve the problem, the options considered, and the reason for an important choice.
In a smaller product, some of this may fit into fewer files. In a larger product, documentation by area may be more useful. The structure should make information easy to find and update; adding folders does not create good architecture by itself.
Use AGENTS.md as a work map
For Codex, AGENTS.md can hold persistent project instructions. It should tell the agent about the technology stack, important boundaries, actual commands, and documents to consult for certain tasks. OpenAI’s official guide explains how to organize instructions by scope: general rules at the root and more specific instructions in the directories where they apply.
A short example might look like this:
# Project guidance
- Read docs/product/PRODUCT.md before changing product workflows.
- Consult docs/architecture/overview.md before changing boundaries between modules.
- Follow the patterns used near the area you are changing.
- Before finishing, run only the documented verification commands.
- Do not invent business rules; flag ambiguity and use existing examples.For truly local rules, an instruction file inside a specific area can reduce clutter in the root document. It also keeps unrelated details out of every task. Tool support for filenames and rules varies; check the documentation for the agent your team uses and confirm which files it recognizes.
GitHub also documents shared and path-specific instructions for Copilot in its guide to repository instructions. If the team uses different tools, prefer a shared set of rules when supported and keep separate only the settings that are truly tool-specific.
Organize code around changes that need to stay isolated
The file tree is context too. Names like utils, common, and misc may be convenient at first, but they become places without clear boundaries when unrelated code accumulates there. For larger features, organizing by product capability can keep code and tests close together:
src/
└── features/
├── orders/
│ ├── ui/
│ ├── application/
│ ├── domain/
│ ├── data/
│ └── tests/
└── customers/
├── ui/
├── application/
├── domain/
├── data/
└── tests/These names are an example, not a requirement. A simple CRUD feature may not need four layers; a product with distinct domains may benefit from feature boundaries. The practical test is whether the team can find where a rule lives, change one area without spreading unrelated edits, and locate the tests that verify that behavior.
Ask the AI to inspect the existing organization before adding folders. Creating a second, parallel architecture may be worse than following an imperfect but consistent pattern. If the structure needs to change, document the goal and migrate incrementally.
Useful context combines stable instructions with on-demand lookup
Rules that apply to almost every task belong in persistent instructions: the stack, commands, conventions, and boundaries. Rules that apply to only part of the product should live near that area. Older decisions should be referenced where people can find them, instead of copied in several places.
The AI does not need every document in every task. It needs to know where to look. OpenAI’s documentation on context and model instructions explains how additional context can keep work focused on relevant resources; Anthropic recommends lightweight pointers and progressively loading information when an agent needs it.
A short index in docs/README.md can answer “Where are the product rules?”, “Which document explains the architecture?”, and “How do I run the tests?” For a specific task, the agent consults only the documents connected to the change.
Describe tasks with a goal and acceptance criteria
“Improve the orders module” leaves many decisions open. A better-scoped request says:
- Outcome: what should change from the user’s point of view.
- Context: which rule or problem motivated the task and which files or documents explain the behavior.
- Boundaries: what must keep working and which areas should not change.
- Acceptance: observable examples of correct behavior, including relevant errors and edge cases.
- Verification: which tests, checks, or inspections should happen before the task is complete.
For example: “Let a request under review be resumed by the responsible team. Check the status flow in docs/product/PRODUCT.md and the module’s current tests. Do not change approval rules; add coverage for a user without permission and for a request that is already closed. At the end, run the checks used by this area.” This reduces guesswork without prescribing every implementation detail.
Validation keeps the agent connected to the real project
A clear plan does not prove that the result works. The cycle needs to return to the repository: the AI inspects existing patterns, proposes or implements a change, runs the available checks, and reports anything it could not validate. Tests, linting, type checks, and human review cover different risks; none replaces all the others in every project.
This matters especially for authentication, permissions, personal data, payments, and changes that affect many areas. In these places, a review should check more than the happy path: did the agent broaden access, ignore invalid states, or fail to preserve a business rule?
If the same mistake keeps coming back, find the cause before adding another instruction. The project may be missing an example, a test, a rule description, or a clear code boundary. Fixing the source is usually more useful than expanding a prompt that is already difficult to maintain.
A well-contextualized project keeps evolving
Context gets stale. A dependency changes, a decision stops applying, a workflow is simplified, and an instruction may begin to contradict the code. Review documentation alongside important changes and remove duplicated or ownerless guidance.
Start with the minimum: explain the product, point out the main boundaries, record decisions that still affect the work, list commands that really exist, and show where to find more specific rules. Then watch for interpretation errors and improve the context where that information belongs.
A good foundation for AI is also a good foundation for the team: visible intent, clear boundaries, and information that can be checked in the project itself.