Short answer
CLAUDE.md and AGENTS.md are the files coding agents read to learn how your repository works. A context engineering workshop teaches teams to write short, verifiable instructions, structure them by folder, test them against real tasks and maintain them like code, which improves every later agent session.
On this page
Why a whole workshop on two Markdown files
A coding agent that opens your repository knows nothing about your conventions. It does not know which command runs a single test, that the legacy folder must not be refactored, or that all API responses go through a shared error format. It guesses, and its guesses produce plausible code that reviewers then have to correct.
CLAUDE.md (read by Claude Code) and AGENTS.md (an open convention read by OpenAI Codex and several other agents) solve this. They are plain Markdown files in the repository with instructions for agents. Writing a good one is harder than it looks: too short and the agent still guesses, too long and important rules get lost. Context engineering, the practice of shaping what an agent knows when it starts working, is a skill teams can learn in a day. That is what our workshop at neooutput is for.
What belongs in the file
We start by sorting candidate content into three buckets:
| Include | Keep elsewhere | Leave out |
|---|---|---|
| Build, test and lint commands, including single-test runs | Long architecture documents (link them) | Things the linter or formatter already enforces |
| Conventions the tooling does not enforce | API reference (generated docs) | Generic advice like "write clean code" |
| Directory responsibilities and boundaries | Onboarding material for humans | Secrets, internal URLs that should not be shared |
| Known traps and "never do this" rules | Decision records (link the important ones) | Outdated rules nobody follows |
| Pull request and commit expectations | Team processes unrelated to code | Long examples that duplicate the codebase |
The guiding question: would a capable new colleague get this wrong on their first day without being told? If yes, it belongs in the file.
A compact example
Participants see a short example before writing their own:
Project notes for coding agents
## Commands
- Install: pnpm install
- All tests: pnpm test
- Single test: pnpm test -- path/to/file.test.ts
- Lint and types: pnpm lint && pnpm typecheck
## Conventions
- API handlers live in src/api and return results via lib/http/respond.ts
- Database access only through repositories in src/data, never from handlers
- Dates are stored in UTC and formatted only in the UI layer
## Boundaries
- Do not edit files in src/generated; run pnpm codegen instead
- The billing module requires review by the payments team
## Before opening a pull request
- Run lint, typecheck and the affected tests
- Describe risks and anything you could not verify
It is short on purpose. Every line is specific and checkable.
Structuring for larger repositories
Monorepos and large codebases need more than one file. We practise a layered structure:
- Root file with commands, global conventions and pointers
- Folder-level files for modules with their own rules, such as a mobile app, a legacy service or infrastructure code
- Linked documents for deep topics, referenced rather than copied
Agents typically load the root file and relevant nested files when working in a folder. The details differ between tools, so we test how the team's chosen agents actually behave. Teams using both Claude Code and Codex often keep AGENTS.md as the shared source and point CLAUDE.md to it, or the other way round, to avoid maintaining two diverging files.
Testing context files
A context file is only good if it changes agent behaviour. We use a simple evaluation loop:
- Pick five real tasks from the backlog, varied in size and area
- Run each with the agent without the context file and note mistakes
- Write or improve the file to address those mistakes
- Run the same tasks again and compare
Typical improvements: the agent uses the right test command, respects module boundaries, follows the error-handling pattern and writes better pull request descriptions. Where it still fails, the rule is either missing, ambiguous or buried.
Writing style that works for agents
- Imperative and concrete. "Use the repository classes in src/data" beats "we generally prefer a repository pattern".
- One rule per line. Easy to scan, easy to update.
- Explain the why for surprising rules. Agents follow rules better, and humans maintain them better, when the reason is clear.
- Prioritize. Put the most important rules near the top.
- Avoid contradictions. Two conflicting rules in different files make behaviour unpredictable.
Maintaining the files
Context files rot like any documentation. We set up a maintenance routine during the workshop:
- A named owner per file
- Recurring review comments become rules within a week
- Rules that are no longer true are removed, not commented out
- Changes to the files go through normal pull request review
- A quarterly check against a fixed set of evaluation tasks
Beyond a single repository
Organizations with many repositories benefit from a template: a standard structure with common sections, filled in per project. Platform teams can provide shared snippets for security rules, commit conventions and CI expectations. For teams connecting agents to internal systems, context files can also explain which MCP servers exist and when to use them; our MCP workshop covers that integration side.
Context engineering is also what makes outsourced or blended delivery work. When external AI Code Engineers join a codebase, a good AGENTS.md gives their agents the same conventions as yours. OnlineAppCreator relies on this when taking over defined work packages for clients under SLAs.
Format
neooutput runs this as a half-day or full-day workshop on the team's own repositories, in English or German. It works well as a follow-up to tool-specific training such as the Claude Code workshop or the OpenAI Codex workshop, and as a standalone session for teams already using agents.
FAQ
What is the difference between CLAUDE.md and AGENTS.md?
CLAUDE.md is the file Claude Code reads for project instructions. AGENTS.md is an open convention used by OpenAI Codex and other agents. The content is similar; many teams keep one as the main file and reference it from the other.
How long should a CLAUDE.md or AGENTS.md be?
As short as possible while covering what an agent would otherwise get wrong. Many effective root files fit on one or two screens, with detail in folder-level files or linked documents.
Should context files be committed to the repository?
Yes, for shared team instructions. That way they are versioned, reviewed and available to everyone, including agents running in CI or cloud environments.
How do we know if our context file works?
Run a fixed set of real tasks with and without it and compare the results. If the same mistakes keep happening, the file needs a clearer or more prominent rule.