CLAUDE.md and AGENTS.md Files

A CLAUDE.md file holds instructions for Claude. Claude Code reads it automatically when it works in the folder that contains it, so each folder can carry its own context and conventions. An AGENTS.md file does the same job for other AI tools, which look for that name instead. In an AI Business OS workspace, every AGENTS.md is a pointer to the CLAUDE.md beside it or to the master instructions, so there is only ever one set of instructions to maintain.

Three Levels of CLAUDE.md

Level	Location	What it holds	Who writes it
Master	.claude/CLAUDE.md	The workspace identity, your business context, where files go and how to work with git	Ships with placeholders, which /setup fills in
Domain	Domains/NN Domain/CLAUDE.md	What the domain is for, what each subfolder holds and the conventions for that function	Ships with defaults, which you configure the first time you work in the domain
Project	Inside each project folder	The project’s purpose and any rules, skills and conventions for that project only	/newproject

The master instructions apply everywhere in the workspace. A domain or project CLAUDE.md adds the context for its own folder on top of them.

All three levels belong to you. Engine updates never overwrite the master file or any domain file, and project files are not engine files at all, so /update leaves them alone too.

The Master CLAUDE.md

Claude Code loads .claude/CLAUDE.md at the start of every session in your workspace, and the file has the sections below.

Section	Contents
Workspace Identity	Company name, workspace ID, repository and workspace type, used to check that pushes go to the right repository
Business Context	Your organisation, industry and main uses, and an instruction to consult the company context files before writing anything
Workspace Structure	A map of the folders
File Organisation Rules	Where each kind of file goes, and the rule that nothing is created at the workspace root
Cloud Storage Integration	The path to your cloud storage folder for large files
Communication Standards	How Claude communicates with you
Git Workflow	Pull before you start, commit and push when you finish, and what never to commit
Session Continuity	How to continue earlier sessions
Getting Help	What happens when Claude needs more information
Customisation Log	A table where you record changes you make to the workspace

Edit this file when something about the whole workspace changes, such as your cloud storage path. Ask Claude to make the change, or open the file in VS Code and edit it yourself. Record the change in the Customisation Log at the end of the file, so anyone working in the workspace later can see what changed and why.

Domain CLAUDE.md Files

Each of the seventeen domains has its own CLAUDE.md. A new one opens with a SETUP REQUIRED notice and a Configuration section that shows the status “Unconfigured”. The first time you work in a domain, Claude asks you how you use it and updates the file with your answers. The Domains page explains what each domain holds.

When you add or remove a reference subfolder, Claude updates the subfolder table in that domain’s CLAUDE.md, so the file always matches the folders on disk.

Project CLAUDE.md Files

/newproject writes a CLAUDE.md in every new project folder with these sections.

• Project Overview, with the project ID, category, status, creation date and a purpose statement from your answers.
• Project Reference, which points to the project’s PRD.md.
• Rules, which lists any rule files that apply to this project only, or says that the standard rules apply.
• Skills, which lists any skills the project uses.
• Conventions, for naming, formatting or terminology that applies to this project.

Add to the file as the project develops. For example, record that design files live on cloud storage and are referenced by path, or that every page of copy is checked against your brand guidelines before it goes out. Claude reads these instructions whenever it works in the project folder.

Note

The project CLAUDE.md that /newproject writes opens with a line saying that master rules take precedence in a conflict, unless you approve an override. The root AGENTS.md, read by other AI tools, says the more specific file governs work in its folder. If a project needs to depart from a master rule, say so in the project CLAUDE.md and confirm the override with Claude, so both readings lead to the same result.

Client folders created with /newclient carry a README.md with the client’s details and no CLAUDE.md. The CLAUDE.md in Domains/01 Clients/ covers all of them.

AGENTS.md Files

Claude Code reads CLAUDE.md. Most other AI agents, such as Codex, OpenCode, Cursor, Gemini CLI and the GitHub Copilot coding agent, read AGENTS.md instead. The AGENTS.md files exist so that you can bring the agent you prefer into the workspace. AI Business OS keeps one body of instructions with two entry points, so a different agent finds the same rules.

Caution

AI Business OS is built and tested with Claude Code, and these pages describe a Claude Code installation. Another agent can work in the workspace through its AGENTS.md files, although some commands, hooks and skills may behave differently with it. If you use one, tell GenAI Skills Academy what works and what does not through Getting Help, because that feedback is valued.

File	Location	What it does
Root AGENTS.md	The workspace root	Tells any tool to read .claude/CLAUDE.md, the company files, the folder’s own CLAUDE.md and the relevant rules before it acts, and sets out how to write the project register safely
Stub AGENTS.md	Every domain folder, every sample project and every project /newproject creates	Points the tool to the CLAUDE.md in the same folder and to the root AGENTS.md

A stub carries no content of its own. Every stub follows this pattern, with the folder name in the heading.

# AGENTS.md — P012 Spring Workshop

Before any action in this folder:

1. Read `CLAUDE.md` in this folder — canonical project context and rules.
2. Read the project's entry in `.claude/state/` (workspace root) before changing
   project status, tasks, or history.
3. Follow the workspace `AGENTS.md` at the workspace root, including the state-write
   discipline (bash + jq only, backup before write, validate after).

CLAUDE.md is always the file that holds the instructions. Never put instructions in an AGENTS.md stub, because two copies of the same rule drift apart over time.

Adding Missing Stubs

A project folder can end up with a CLAUDE.md and no AGENTS.md, for example when you create the folder yourself. A script adds the missing stubs. Run it from the workspace root, first with --dry-run to see what it would create.

bash Infrastructure/Scripts/backfill-project-agents-stubs.sh --dry-run
bash Infrastructure/Scripts/backfill-project-agents-stubs.sh

The script looks for every folder that holds a CLAUDE.md and no AGENTS.md, and writes a stub in each one. It skips .claude/ and Archive/, and it never changes a stub that already exists.

Related Pages

• Folder Structure
• Domains
• Company Context Files
• How Rules Work
• /newproject