Instructions
This guide teaches you how to write instructions for AI coding assistants using the canonical AGLOOM.md format.
What Are Instructions
Instructions are AGLOOM.md files placed in your project root or any subdirectory. They contain project-level guidance for AI coding assistants — your stack, conventions, boundaries, and workflow preferences.
When you run agloom transpile, Agloom discovers all AGLOOM.md files and transforms each one into agent-specific instruction files (CLAUDE.md, AGENTS.md, GEMINI.md, etc.) at the same relative path, based on your configured adapters.
Basic Instructions
Start by creating a simple AGLOOM.md with content that applies to all agents:
# My Project
## Stack
TypeScript, React, PostgreSQL.
## Conventions
- Use functional components with hooks.
- All API calls go through the `api/` directory.
- Write unit tests for business logic.
## Boundaries
- Never modify database migrations directly — use the migration generator.
- Never commit `.env` files.
Everything in this file (outside of agent-specific blocks) is included in the output for every adapter.
Agent-Specific Blocks
Sometimes you need instructions that apply only to a particular tool. Use HTML comment tags to define agent-specific sections:
# My Project
All agents see this content.
<!-- agent:claude -->
Use the `Grep` and `Glob` tools for code search instead of shelling out to `grep`/`find`. Run shell commands only when no dedicated tool exists.
<!-- /agent:claude -->
<!-- agent:agentsmd -->
Use the file search and read tools provided by your environment. Always read a file before editing it.
<!-- /agent:agentsmd -->
This content is also visible to all agents.
When transpiling for Claude, the agentsmd block is removed and the claude block content is included (without the comment tags). When transpiling for AGENTS.md, the reverse happens.
Valid Agent IDs
Only agents that have their own instruction file format can be used in agent-specific blocks:
| Agent ID | Instruction file | Can use in blocks |
|---|---|---|
claude | CLAUDE.md | Yes |
agentsmd | AGENTS.md | Yes |
gemini | GEMINI.md | Yes |
opencode | (none) | No |
kilocode | (none) | No |
codex | (none) | No |
opencode, kilocode, and codex do not have their own instruction file format — they use AGENTS.md (generated by the agentsmd adapter). To write content specific to these tools, use <!-- agent:agentsmd --> blocks.
Using an invalid agent ID in a block (e.g., <!-- agent:opencode -->) will cause a transpilation error.
Multiple Instruction Files
Agloom supports instruction files in subdirectories. If you place an AGLOOM.md in a subdirectory (e.g., src/AGLOOM.md), it will be transpiled to the corresponding location (e.g., src/CLAUDE.md for the Claude adapter).
This lets you provide directory-level instructions that agents pick up when working in specific parts of your codebase.
Example
Here is a complete AGLOOM.md with shared and agent-specific sections.
---
description: Main project instructions
---
# My Web App
## Stack
TypeScript, Next.js 14, Prisma, PostgreSQL.
## Commands
- Build: `pnpm run build`
- Test: `pnpm run test`
- Lint: `pnpm run lint`
## Conventions
- Use server components by default.
- Client components must have the `"use client"` directive.
- All database queries go through Prisma — never write raw SQL.
- Tests live next to source as `*.spec.ts`, not in a separate `__tests__` tree.
<!-- agent:claude -->
## Claude Code workflow
- For non-trivial features, draft a plan with the `ExitPlanMode` tool before writing code. The plan must list the files you intend to touch.
- Track multi-step work with `TaskCreate` / `TaskUpdate`. Mark each task completed as you finish it, not in batches at the end.
- For independent investigations (e.g. "is X used anywhere?"), spawn the`Explore` subagent in parallel rather than running searches sequentially in the main thread.
- Prefer dedicated tools over Bash: `Read` over `cat`, `Grep` over `grep`, `Glob` over `find`, `Edit` over `sed`.
<!-- /agent:claude -->
<!-- agent:agentsmd -->
## AGENTS.md workflow
- Read the relevant file fully before editing it; do not patch based on a partial view.
- After every meaningful change, run `pnpm run test` and address failures before moving on.
- For multi-file changes, write a short outline of the planned edits at the top of your response so the user can interrupt early if the direction is wrong.
<!-- /agent:agentsmd -->
## Boundaries
- Never modify files in `generated/` — they are produced by `prisma generate`.
- Never skip TypeScript strict mode or use `// @ts-ignore`.
- Never commit `.env*` files; use `.env.example` for documenting variables.
The YAML frontmatter is optional. If present, it can contain an override block for adapter-specific frontmatter fields. See reference/transpilers for details on frontmatter overrides.