An agent joins your project. You give it an AGENTS.md containing the essentials: how the project is organized, which conventions matter, and how to verify a change. It can start working without asking you to repeat the same instructions.
Then the project grows. One task implements a feature. Another reviews its compatibility. A later session needs to understand a decision made weeks earlier. You add more instructions, lessons, and procedures to the same file.
Eventually, a useful entrypoint becomes a mixture of shared rules, role-specific methods, and historical knowledge. The problem is deciding what belongs together and what each task actually needs to read.
BringAI's .AGENTS project offers a small organizational convention: keep the root AGENTS.md, and give each role its own instructions, memory, and skills. The current repository consists of Markdown templates. There is no tool to install or service to run.
Where one shared file starts to strain
A root AGENTS.md is a good home for facts and rules everyone needs: project context, working conventions, and instructions for finding relevant resources.
Role-specific guidance has a different audience. A developer needs to trace affected callers and implement a coherent change. A reviewer needs to examine failure conditions, distinguish defects from preferences, and report evidence. Both may work on the same files, but their responsibilities differ.
Directory-scoped instructions already help organize large projects. The project README explicitly recognizes that AGENTS.md supports this approach. The additional question is how to organize responsibilities that overlap within the same code directory.
History creates another pressure. A lesson from a difficult migration may help the next implementation task, but it should not become an unexplained permanent rule. Without an owner, source, or review condition, yesterday's workaround can outlive the problem it solved.
None of this means a single file cannot link to other material. .AGENTS makes that organization explicit and repeatable.
The structure is the product
The repository currently ships two roles, developer and reviewer, with this structure:
AGENTS.md
.AGENTS/
├── developer/
│ ├── AGENTS.md
│ ├── memory/
│ │ └── MEMORY.md
│ └── skills/
│ ├── focused-change/
│ │ └── SKILL.md
│ └── decision-record/
│ └── SKILL.md
└── reviewer/
├── AGENTS.md
├── memory/
│ └── MEMORY.md
└── skills/
└── change-review/
└── SKILL.mdThe root entrypoint tells an agent to select the relevant role, read that role's instructions and memory, then inspect skill descriptions and read applicable skill bodies.
Shared project context stays in the root file. Role knowledge stays with the role. There is no separate shared-context directory or collection of memory-record files in the current template.
A role describes responsibility, not a model identity. One agent can develop a change and then review it. Several agents can also work as developers on separate tasks. Selecting a role does not start another agent or establish an execution boundary.
Instructions, memory, and skills have different jobs
The role's AGENTS.md defines its responsibility. The developer instructions, for example, cover investigation, design, implementation, verification, and handoff. They assume no particular language or framework.
memory/MEMORY.md holds reusable knowledge established through work: a consequential decision, a recurring pitfall, or a verified workflow. The supplied files start without project-specific findings. They do not pretend to know your architecture before you begin.
Significant findings should include evidence, scope, and a date or review condition. Memory needs maintenance: check it against current project files, replace stale conclusions, and remove information that no longer helps. Git preserves history; the current file should remain concise.
A skill describes a reusable method. The included focused-change skill guides a bounded implementation through understanding the outcome, tracing consumers, making the change, and verifying it. decision-record helps preserve consequential design choices. The reviewer's change-review skill focuses on concrete defects and supporting evidence.
These are written workflows for an agent to follow. They are not executable automation, and the directory convention does not install them into a client.
Role-specific memory stores lessons; skills capture reusable methods.
A practical example: changing an API
Imagine an existing project needs to add pagination to a list endpoint while preserving current clients. This is an illustrative task, not a feature implemented by the .AGENTS repository.
Start with a prompt that makes the reading steps explicit:
Read AGENTS.md and work as developer.
Read .AGENTS/developer/AGENTS.md and
.AGENTS/developer/memory/MEMORY.md.
Use the focused-change skill where relevant.
Add pagination to the list endpoint while preserving existing clients.
Inspect current callers and tests before choosing the response format.
Report what changed and what you verified.The developer follows the project's actual evidence. It examines the endpoint and callers, chooses a compatible approach, updates affected files, and runs the appropriate available checks. The template does not supply a test command; the agent must discover one from the project.
Suppose the work establishes a compatibility constraint worth preserving. After verifying it, the developer could add a concise memory section like this:
## Pagination compatibility
- Status: active
- Scope: list endpoint and existing clients
- Evidence: link to the actual compatibility test and reviewed change
- Review after: the next API version change
Existing clients depend on the current top-level response shape.
Preserve it unless a versioned migration explicitly changes the contract.That is a hypothetical entry format, not a finding about this repository. In real work, replace the evidence description with concrete references.
For review, select reviewer, read its instructions and memory, and use change-review. The reviewer checks the intended outcome, affected consumers, and plausible regressions. Findings should identify where the problem occurs, what triggers it, and why it matters.
If two agents work concurrently, use separate worktrees or clear file ownership. Role folders do not lock files, and memory edits still need reconciliation.
Adopt it without building infrastructure
For a new project, clone the template and give your agent its first task:
git clone https://github.com/Bring-AI/.AGENTS.git my-project
cd my-projectFor an existing project, clone it elsewhere, copy .AGENTS/, and merge the README's entrypoint instructions into your root AGENTS.md. Preserve existing instructions and files rather than replacing them wholesale.
The root entrypoint and role directory work independently of the explanatory README. You can adapt role names and skills as real needs emerge. There is no need to fill the memory files before beginning.
Explicit reading matters. The custom .AGENTS/ path is not a universal tool standard or an official AGENTS.md extension. Client discovery and instruction precedence remain client-specific. If your client does not load the entrypoint automatically, ask it to read the files in your task prompt.
Keep the simpler option when it works
For a small project, one agent, and a few shared rules, AGENTS.md alone may be enough. Extra role directories bring maintenance work, and a role without a distinct responsibility adds little value.
Consider .AGENTS when repeated tasks need different methods, useful lessons disappear between sessions, or shared instructions accumulate unrelated history. The benefit is a clearer place to maintain that information—not a measured guarantee of faster or more accurate agents.
The current project provides the structure and instructions described here. It does not provide scheduling, automatic memory extraction, retrieval infrastructure, permission isolation, or conflict resolution. Those capabilities would require additional implementation; they are not promised future features.
Start with the repository and its README, keep the root rules short, and let role knowledge grow only when actual work produces something worth remembering.