Agent instructions

How the repository instructs coding agents (Claude Code, Codex), and how to maintain those instructions. Shared procedures stay in the topic guides that developers read; this page covers only the agent layer around them.

Where agent instructions live

Layer	Location	Loaded
Scoped rules and invariants	AGENTS.md in a directory, with a sibling CLAUDE.md symlink	By the host, from the root down to the working directory
Skills (agent orchestration)	.agents/skills/<name>/SKILL.md	On trigger. Codex reads .agents/skills; .claude/skills is a directory symlink to it
Subagents and slash commands	.agents/agents/, .agents/commands/, linked from .claude/agents/ and .claude/commands/	On request
Repo overlays for bento skills	.agents/bento/<skill>.md	By the matching bento-* skill
Factory run instructions	.agents/rose-factory/run_instructions.md	By the Factory for each run
Edit hook	.claude/hooks/check.sh, wired in .claude/settings.json	After each edit (mypy, Biome)

Add a skill with /create-skill; never add a per-skill link under .claude/skills.

Maintaining AGENTS.md and shared procedures

Use claude-md-improver when creating, auditing, or editing an AGENTS.md or CLAUDE.md. Use /bento-learn to decide where a session learning belongs. Both workflows should preserve one maintained procedure for developers and agents.

Instruction discovery versus procedure links

Directory scope and automatic loading are different. Codex builds its instruction chain at startup from the project root down to the starting directory; this does not recursively preload every child directory. See the official discovery rules.

Before editing a target file, check its ancestor directories for applicable instructions and read any the host has not already supplied, respecting its overrides. A Markdown link or shell cd is not proof of loading. Procedure guides are read on their task trigger; they are not automatically imported into the instruction chain.

Choose the home before writing

Content	Home
Essential safety rule or invariant that applies throughout a scope	That scope's AGENTS.md
Short install, dev, or verification command	AGENTS.md, with a link for options and troubleshooting
Setup, testing, migration, or debugging procedure usable by developers and agents	Existing topic guide under docs/src/ or the package README
Agent-specific orchestration, tool selection, or review protocol	Existing skill; link its shared procedures instead of copying them
Detailed rationale or architecture	Existing topic guide or ADR
Fact already explained by code or a code comment	Keep it there; add a pointer only if needed before opening that code
One-off incident detail with no recurring trigger	Do not add to standing instructions

Update the documentation

1. Read the applicable root and nested instructions. Edit the AGENTS.md source; preserve its sibling CLAUDE.md symlink. Check existing links before creating files.
2. Search the existing docs, package READMEs, and skills for the procedure. Read the candidate guide and verify its commands against the current code or justfile. Trace invoked wrappers for target selection and side effects; an old instruction is not evidence that its claim is still true. Distinguish source-verified behavior from historical measurements or live service state that has not been checked.
3. Improve that guide in place. Include prerequisites, working directory and target, steps, expected results, verification, and relevant pitfalls. Keep long examples and incident reasoning there. Create a new topic guide only if no existing home fits.
4. Replace the inline procedure with an explicit trigger and a relative Markdown link to the relevant section. A bare bibliography does not tell an agent when to read it. Put that link in the nearest applicable AGENTS.md and add the task to the Procedures index. The root index supports discovery; scoped instructions should still link directly to the guide they need.
5. Keep critical safeguards inline: permissions, production data boundaries, tenant isolation, and prohibited actions must remain visible before a procedure is opened.
6. Check moved details against the original, resolve contradictory instructions, and verify links and anchors. Build docs when changing published pages. Record which instructions were retained, moved, or deliberately corrected.

For example, a Supabase instruction file can route setup work directly to the shared guide:

- Before creating or reconnecting a preview database, read
  [Preview branch setup](../docs/src/backoffice/supabase-preview-branches.md#create-a-preview-branch).

Use the narrowest directory that owns a rule. Root instructions apply across the repository; nested instructions add scope-specific guidance. Do not repeat the full parent rule set in every child. Review a file for extraction around 150–200 lines, but also check words and scope: wrapping a long paragraph onto one line saves no context.

Do not create a skill just to hold a procedure already suitable for the docs. A skill should add agent behavior; it can direct the agent to the same guide a developer reads.

Session retrospectives

Session learning is a deliberate step, not a hook. Bento's bento-learn skill (Reflect → Route → Propose) routes each learning to its home, using this repo's AGENTS.md rules for Rose-specific sinks.

• At PR time: bento-ship runs it on every Claude/Codex session of the branch and git diff origin/develop...HEAD. Approved learnings land as their own commit and are reviewed with the code in that PR.
• Manually: /bento-learn (Claude) or $bento-learn (Codex) for sessions that end without a PR.