NEWCloud agents are live.See how

Context

Agents file

Also called AGENTS.md, CLAUDE.md, rules file

A markdown file committed to a repository that tells any coding agent working there how the project works: its conventions, commands, architecture, and rules. AGENTS.md is the cross-tool convention; CLAUDE.md is Claude Code's filename for the same thing, and many repos symlink one to the other.

At a glance

Common names
AGENTS.md, CLAUDE.md
Lives in
The repository, committed
Loaded
At the start of every session
Nested files
Nearest file in the directory tree wins
Enforced?
No, it is context, not a hard limit

How it works

The harness reads the file from the repository when a session starts and puts its contents into the model's context. Claude Code reads CLAUDE.md and can import another file with @path syntax; Codex and a growing list of other tools read AGENTS.md. Nested copies are allowed: in a monorepo, a packages/api/AGENTS.md adds rules for that package, and agents use the nearest file in the directory tree.

Because the file loads every session, every line costs tokens on every task. That makes it closer to standing instructions than to documentation.

Why it matters

An agent starts each session knowing nothing about your project except what it reads. The agents file is where you put what it would otherwise get wrong: the exact build, lint and test commands, which package manager to use, files it must never edit, and the names of your domain concepts so it uses your vocabulary instead of inventing synonyms. Leave out what the agent can see by reading code and generic advice like "write clean code".

It also beats settings stored in a tool's UI because it is versioned. Changes go through code review, and every contributor and every agent sees the same rules.

Agents file vs. system prompt

The system prompt is written by the tool vendor and shapes the agent everywhere. The agents file is written by you and only applies inside your repository, layered on top of that prompt.

A skill is the other nearby idea: a packaged set of instructions the agent loads only when a task calls for it. Put rules that apply to every task in the agents file and move long, situational procedures into skills so they stop costing tokens on unrelated work.

Example

A short AGENTS.md
# AGENTS.md

## Commands
- `pnpm dev` runs the app on port 3000
- `pnpm test` must pass before you finish

## Rules
- Use pnpm, never npm or yarn.
- Do not edit files under `src/generated/`; run `pnpm codegen`.
- Every schema change needs a migration in `prisma/migrations/`.

Common mistakes

  1. Letting the file grow forever until the rules that matter are buried under ones that no longer apply.
  2. Stating rules the codebase visibly contradicts, so the agent sees conflicting evidence and picks one.
  3. Maintaining AGENTS.md and CLAUDE.md as two hand-edited copies that drift, instead of a symlink or an import.

In Fredrin

Fredrin keeps project context as files in the repo, starting with AGENTS.md. A Worker reads it in its ticket's worktree like any other agent would, and nothing is injected at runtime.

Writing project memory

Frequently asked questions

Is AGENTS.md the same as CLAUDE.md?

They serve the same purpose. AGENTS.md is the cross-tool convention, CLAUDE.md is the name Claude Code reads, and many repos symlink one to the other so both stay identical.

How long should an agents file be?

As short as it can be while still covering what agents get wrong. Claude Code's documentation suggests keeping each CLAUDE.md under 200 lines, since longer files cost context and reduce adherence.

Should I commit my agents file?

Yes. Committing it means every contributor and every agent sees the same rules, and changes to it are reviewed like code.

Sources

Know the words. Run the work.