Giving good context · for software engineers
Giving good context in software engineering
A model knows a great deal about programming in general. It knows nothing about your codebase unless you show it. It has not seen your error-handling pattern, your internal libraries, your framework version, or the reason a strange-looking function exists.
Giving good context means selecting what a new teammate would need before making this change. That usually means the relevant files, the interfaces they depend on, the versions in use, and the team’s conventions. It also means leaving out files that would mislead the model.
Where it comes up
Reading an unfamiliar module
Give the model the module, its entry points, and one or two of its callers. Ask for an explanation of the data flow.
A dependency upgrade
Supply the current and target versions, the library’s changelog or migration notes, and the files that import it. Without the changelog, the model may describe an API from a different version.
A change that follows house style
Paste an existing function the team considers a good example. Show how errors, logging, and tests are written. One real example teaches conventions faster than a paragraph describing them.
What it looks like at each band
E1 · Foundational
Pastes the failing function and a short description. Output often uses the wrong framework version, invents helper functions, or ignores house conventions. Does not yet see that missing context causes these errors.
E2 · Proficient
Includes the relevant files, the language and library versions, and the error output in full. Shows an example of the team’s style. Output compiles more often and needs less rework to match the codebase.
E3 · Distinguished
Chooses context deliberately for each task. Includes the interfaces a change touches, notes which code is deprecated, and says what the model should not assume. Keeps a short project brief with versions and conventions ready to paste or load.
E4 · Exceptional
Builds and maintains the shared context the team relies on, such as a project guide written for AI tools and a list of internal APIs with usage notes. Updates that material when the architecture changes, before stale guidance produces wrong code.
Common mistakes
Pasting the error but not the code path
A stack trace without the functions it names leaves the model to guess. Include the frames from your own code and the inputs that triggered the failure.
Trusting the model’s knowledge of a library
The model may know an older or newer version than the one you run. State the version and supply the documentation for any API the change relies on.
Loading the whole repository
More files do not always mean better answers. Unrelated or legacy code can pull the model toward patterns the team has abandoned. Select the files this change touches.
A worked example
Adding retry logic to a service that calls a third-party payments API.
Add retries to our payment API client.
The model does not know the language, the HTTP library, which errors are safe to retry, or whether the endpoint is idempotent. It may retry a charge that already succeeded.
Here is our payments client in TypeScript using our shared HTTP wrapper, which I have also pasted. The provider’s documentation, excerpted below, says create-charge requests accept an idempotency key and that 429 and 503 responses are safe to retry. Our convention for backoff is in the attached utility. Add retries only for those status codes, reuse one idempotency key across attempts, and log each retry with our existing logger.
The model now has the code, the wrapper, the provider’s retry rules, and the team’s backoff utility. The constraint about idempotency keys comes from the documentation, so the retry cannot double-charge a customer.
The full study guide for this skill, for every role, is Giving good context. The other five skills for software engineers are on the AI skills for software engineers page. A one-page summary is in the AI context checklist.
See where you stand
The free check grades giving good context and the other five skills in about fifteen minutes. Nobody sees the grade but you.
Then build the skills and prove it. The three steps for software engineers list the courses and templates that fit the work.