Giving the assistant useful context
A developer opens a new coding session and explains the project again: which command runs the tests, which files are generated, and which module owns retries. Another developer supplies a slightly different explanation. Both assistants can produce reasonable code while working from different assumptions about the same repository.
The team needs a shared starting point for AI-assisted work. Repository knowledge becomes part of the code review process: stored with the project, loaded through a known mechanism, and updated when the workflow changes. The task prompt can then concentrate on the change being requested.
Repeated setup #
The adapter in the previous article needed to forward an idempotency key. An engineer directing that task also knew that notification tests imported compiled JavaScript from dist/.
That detail can determine whether a test result means anything. Consider this package script in a TypeScript project:
{
"scripts": {
"build": "tsc -p tsconfig.json",
"check": "tsc -p tsconfig.json --noEmit",
"test:notifications": "node --test test/notifications/*.test.mjs"
}
}
Here tsconfig.json emits the application into dist/, and the tests import that output. If a developer or assistant edits src/notifications/email-adapter.ts and runs only the test command, the tests can exercise the previous build. A passing result can describe code that no longer matches the working copy.
The engineer could explain the build dependency in every conversation. The team can also encode it in the command:
- "test:notifications": "node --test test/notifications/*.test.mjs"
+ "test:notifications": "npm run build && node --test test/notifications/*.test.mjs"
Now the targeted test command rebuilds first and stops if the build fails. This example assumes an installed toolchain and a build that covers the files under test. The workflow no longer relies on each participant remembering that prerequisite.
That is the first distinction in preparing context: some repeated explanations belong in executable project behaviour. Guidance can point to the resulting command.
Repository instructions #
The remaining knowledge includes decisions that a command cannot express: where responsibilities sit, which tests need external services, and which files are maintained by generators. A small root-level instruction file can make those facts available at the start of work.
The example repository now has this structure:
AGENTS.md
package.json
package-lock.json
tsconfig.json
docs/notifications.md
src/notifications/
submit-notification.ts
email-adapter.ts
test/notifications/
email-adapter.test.mjs
Its AGENTS.md could contain:
# Repository guidance
## Checks
Run commands from the repository root after dependency installation.
- npm run check: type-check the application without emitting files.
- npm run test:notifications: rebuild and run notification tests.
Notification tests use a fake provider client and need no credentials.
Generated application output lives in dist/; edit the source in src/.
## Notification code
The submission layer owns notification identity and retry scheduling.
The provider adapter maps requests and receipts and propagates rejections.
For notification changes, read docs/notifications.md for the processing
path and retry assumptions, then inspect the affected caller and tests.
Each item affects an implementation decision. The file tells the assistant which checks apply, where edits belong, and where a deeper explanation can be found. The command definitions remain in package.json; the instruction file describes when to use them.
The current task still needs its own requirements. “Forward the caller's idempotency key unchanged and preserve rejection behaviour” belongs in the issue or task prompt. It should not become a permanent repository rule requiring every future change to preserve today's adapter design.
Instruction loading #
AGENTS.md has a defined discovery mechanism. At startup, agent assembles project instructions along the path from the repository root to the current working directory. Global guidance can also contribute. Override files and configured fallback names affect which files are selected. The exact rules are documented in Custom instructions with AGENTS.md.
For this example, starting a fresh session at the repository root makes the root file part of that discovery path. A link to docs/notifications.md gives the assistant a reading instruction; it does not automatically insert that document, every source file, and every test into the initial context.
The distinction determines what the team has actually configured. The small instruction file supplies orientation. Repository searches and file reads supply the implementation details for the task. The System Prompt & Context Engineering explains how those different inputs become part of the agent's working context.
After changing instruction files, a fresh session rebuilds the instruction chain. A simple discovery probe from the repository root is:
"Without editing files or running project checks, identify the applicable instruction files and explain which command checks a notification change."
The response should identify the repository guidance and the rebuild-and-test command. This is a useful discovery check, but a correct summary alone does not show that the assistant will use the command during implementation. That needs observation during a task.
A repeatable check #
The team can revisit the adapter fix in a disposable branch or worktree. Start with a working adapter and its regression test, build once, then remove the key forwarding in source without rebuilding. The old output is now deliberately stale.
An illustrative task prompt for a fresh session is short:
Investigate the omitted idempotency key in the notification adapter. Add or use regression coverage at the provider-client boundary, fix the forwarding, and report which checks ran. Keep the existing request mapping and rejection behaviour.
The useful observations are concrete. Did the session identify the project instructions? Did it inspect the caller and boundary test? Did its test invocation rebuild the changed source? If it ran the existing regression before fixing the adapter, did that regression fail at the missing key?
The revised package script makes that failure visible even when old compiled output would have passed. After the fix, the same command should rebuild and pass. The command output and diff show which code was exercised; the assistant's final explanation can be compared with that record.
This is a proposed local experiment, not a measured improvement in assistant reliability. Its purpose is to expose a specific setup mistake and establish whether the team's chosen integration avoids it. If the session misses the guidance, instruction discovery needs attention. If it reads the guidance but tests stale output through another command, the execution path needs examination.
The comparison is with the team's previous process: an engineer had to remember the build dependency and correct the session when it was missed. Now the prerequisite is executable, the expected command is discoverable, and another developer can repeat the check from a fresh session.
Team ownership #
The new artifact is a shared working agreement. Changes to build commands, generated output, or module responsibilities can update AGENTS.md in the same pull request as the implementation. Reviewers can assess whether the instructions still describe how the project works.
Keeping the file short makes that review practical. Detailed retry semantics can stay beside the notification design; temporary task decisions can stay in the issue. A personal preference that is necessary for the whole team belongs in the shared file rather than only in one developer's local configuration.
The change in daily work is specific: developers stop rebuilding the same setup explanation in each conversation. They maintain a common entry point, give the assistant a task, and inspect whether the session uses the project's workflow. That provides a workable foundation for coding assistance across the team, beyond the developer who already knows every prerequisite.