AGENTS.md: The Briefing Note Your AI Agent Needs

An article ToThePoint. No extras. Just what you need to know.

TL;DR: Your AGENTS.md should tell an AI agent what the company does, what products matter, where the important folders are, which rules must never be forgotten, and how progress is tracked.

What `AGENTS.md` is

AGENTS.md is the file an AI agent reads before working in your folder.

Put it at the root of your company vault. Keep it short. Update it when the company changes.

Not a full wiki, just the briefing note.

The job is simple:

Tell the agent what the company is about
Point it to the right files.
Tell it what is important.
Remind it how work gets done here.

Guessing is where expensive mistakes live - it’s a living document, update it as needed but do not bloat it.

The template

One shape. One map. No policy manual, no encyclopedia.

# [Company]

## What is [Company]?
## Products
## Repository structure
## Source code locations
## How this repo works
## Tooling
## How progress is tracked
## Key context for AI agents
## Non-negotiable rules

In practice, it looks like this. Adapt it to your needs.

# [Company]

## What is [Company]?

**[Company]** builds [product/service] for [target users].
Its mission is to [plain-language mission].

**Website:** [https://example.com]
**Contact:** [[email protected]]

---

## Products

### [Product 1] (Current)

A [short product type] for [target user].

**Status:** [alpha / beta / launched / maintenance].
**Features:** [feature 1], [feature 2], [feature 3].
**Pricing:** [if useful].
**Key differentiator:** [why this product exists / why it wins].

### [Product 2] (Legacy / Research / Internal)

A [short description].

**Why it still matters:** [IP, customers, data, research, brand history, support].

---

## Repository structure

| Folder | Contents |
|--------|----------|
| `01-Products/` | Product specs, roadmaps, feedback, product policies |
| `02-Relationships/` | CRM notes, people, companies, interactions |
| `03-Marketing/` | Brand, campaigns, testimonials, website copy |
| `04-Research/` | Market, technical, scientific, or customer research |
| `05-Operations/` | SOPs, templates, meeting notes, internal processes |

---

## Source code locations

| Project | Path |
|---------|------|
| **Website** | `Website/astro/` |
| **Main App** | `apps/main-app/` |
| **Docs Site** | `docs-site/` |

Some of these folders may be linked workspaces (symlinks). A linked workspace appears inside this vault but lives somewhere else. Treat it as live product work, not just notes.

Before editing a linked workspace:

- Read its own `AGENTS.md` or `README.md`.
- Use its own commands.
- Keep product-code changes separate from vault/documentation changes.

---

## How this repo works

- This repo is the company's AI-ready knowledge base.
- Markdown files are the source of truth for plans, notes, and operating context.
- Use Git history when recent changes matter.
- Link important new files from a parent document.
- Documents use `PascalCase_With_Underscores.md`; assets use `snake_case`.

---

## Tooling

- Use `bun` for JavaScript package management.
- Use **Marp** for slide decks.
- Use **Pandoc** for PDF, DOCX, and presentation exports.
- Lint before claiming work is done: `npx markdownlint-cli "**/*.md"`.
- Run the relevant build, test, or lint command before saying work is finished.

---

## How progress is tracked

Pick one method. Name it. Point to the file.

- **[OKR / phases / roadmap]** is the source of truth: `[Project_Plan.md]`.
- Every task maps to a [phase / key result / milestone].
- Mark progress with `[x]` done and `[ ]` pending.

If a task is not in the plan, it does not exist. Add it first.

---

## Key context for AI agents

- **Current business phase:** [launch / migration / growth / fundraising / maintenance].
- **Current priority:** [one sentence].
- **Founder / owner:** [name and role].
- **Main market:** [market / geography / segment].
- **Main constraint:** [time, budget, technical risk, legal risk, team capacity].
- **Voice:** [authoritative / pragmatic / humble — name the tone].

---

## Non-negotiable rules

- Check the plan before starting strategic work.
- Do not invent company facts. Search first.
- Do not change pricing, legal text, or positioning without asking.
- Never commit API keys or customer data. Use placeholders.
- Keep edits small. Prefer edits over rewrites.
- Preserve the existing folder logic.
- Keep public claims verifiable.
- Use the company tone guide for public content.
- Always use relevant skills before specialized work.

I repeat:
**ALWAYS USE SKILLS.**

Vault too small for all this? Keep only Company, Products, Repository structure and Non-negotiable rules. Everything else is scale.

Two questions before adding any section

Before you add a block, ask:

Can the agent infer this easily? (If yes — Marketing/ holds marketing — cut it.)
Will the agent guess wrong without it? (If yes — keep it.)

An agent can infer that Marketing/ holds marketing files. It cannot infer that pricing is sensitive, that every blog post needs a specific tone, or that it should always use a skill.

Write down the rules you are tired of repeating. Update often.

The real test

Open a fresh AI session.

Ask it:

Tell me what this company does, what the active products are, where the website lives, where the app lives, and what rules you must follow before editing. Do not read any file at all.

If it answers correctly, your AGENTS.md works.

If it rambles, your file is probably too vague.

If it misses the important rules, your file is probably too polite.

Make it short. Make it direct. Make it useful.

What’s next

Starting fresh? → Markdown Essentials — the writing format your team will use every day. Then Git Essentials and Train Your Team.
Migrating? → Migration Plan Template Walkthrough — start executing your migration.

Markdown your next move. By Charles Henri Gayot.