📝 Instruction Files for AI Coding Assistants: An Overview

AI coding assistants such as Codex CLI, Claude Code, Cursor, Continue, and others increasingly rely on instruction files - special Markdown documents placed inside your repo to give these agents persistent project-specific context. If you've used tools like codex-cli or claude code, you may have seen files such as:

• AGENTS.md
• CLAUDE.md
• CODEX.md

At first glance they look like glorified READMEs. But they're not. These files act as agent-facing operational guides - a persistent memory layer that modern LLM-powered coding agents load before they start generating or editing code.

This blog explains:

• what these instruction files do
• what belongs inside them
• when task-specific instructions are appropriate
• best practices supported by docs, blog posts, and community usage patterns

📋 1) What AGENTS.md / CLAUDE.md Actually Do

Modern agentic coding systems read these files automatically when working inside your project.

They act as:

• persistent onboarding guides
• coding conventions repositories
• operational workflow documents
• architecture summaries

Factory's AGENTS.md documentation describes it as:

"A simple, open format for guiding coding agents... used by many open-source projects" [1]

Claude Code similarly loads CLAUDE.md automatically from the repo root, parent directories, and relevant child directories:

"Claude Code reads CLAUDE.md files recursively from parent directories and the project root." [2]

Codex CLI historically used INSTRUCTIONS.md or CODEX.md, and has now aligned toward AGENTS.md.

Reddit discussions confirm the transition:

"Codex used CODEX.md previously; AGENTS.md is now the unified format." [3]

These files are loaded before the model produces any output. They act like a role definition, architectural map, and workflow guide for the agent.

📝 2) What Typically Goes Into These Files

Across public examples and in production usage, the contents usually include:

2.1 Build, Test & Lint Commands

npm install
npm run build
npm run lint
npm test

2.2 Project Structure & Architecture

• What lives in src/, components/, api/, etc.
• Where tests live
• Which directories contain legacy code

2.3 Coding Style & Conventions

• folder structure
• naming conventions
• React/Angular/Flask coding style
• language-specific preferences (TypeScript strictness, Python PEP8, etc.)

2.4 Environment Setup

• pyenv/node version
• required tooling
• common scripts

2.5 Git / PR Workflows

Many teams include PR workflows:

PR Workflow:
1. Create a feature branch.
2. Run lint & tests.
3. Write a summary using PR_SUMMARY.md template.
4. Do not commit generated files.

This matches the findings from the empirical study on real-world agent manifests:

"Manifests are dominated by operational commands, architectural notes, and workflow conventions." [4]

🎯 3) Are Task-Specific Instructions Allowed?

Yes — but with guardrails.

This is a point of confusion for many users.

Allowed (and common)

When the "task" is a repeatable workflow:

Examples:

• PR generation steps
• Component creation workflow
• Rules for adding a new model/schema
• Data-cleaning rules for a particular domain
• API versioning workflow
• UI theming conventions

These "tasks" are actually stable workflows, and many teams encode them into AGENTS.md so the AI executes them consistently.

Not recommended

One-off tasks, like a single ticket or bugfix.

Fix issue #166 by replacing foo() with bar()

🗂️ 4) How Instruction Hierarchy Works

Instruction files can exist at several layers:

4.1 Global (User-Level)

~/.claude/CLAUDE.md
~/.codex/AGENTS.md

Used for your personal workflow rules:

• indentation preferences
• editor conventions
• global safety rules

4.2 Project-Root Level

AGENTS.md or CLAUDE.md in repo root.

This is the primary place to store:

• build instructions
• code conventions
• repo architecture
• PR workflows

4.3 Folder-Level (Nested Files)

Claude explicitly supports nested hierarchy:

"You can place CLAUDE.md files in parent directories or child directories related to the file being edited." [2]

Factory's AGENTS.md supports similar hierarchical overrides:

"The closest AGENTS.md file wins." [5]

This is perfect for monorepos or multi-surface codebases.

💡 5) What Goes in Files vs. Prompts

Across production repositories and community practices, a clear pattern emerges for what belongs in instruction files versus prompts:

This separation ensures that instruction files remain focused on persistent, reusable knowledge while keeping prompts flexible for immediate, contextual needs. The distinction helps maintain clean project documentation that stays relevant over time.

📁 6) Recommended Structure

/
  AGENTS.md
  src/
    frontend/
      AGENTS.md   ← local overrides
    backend/
      AGENTS.md
~/.claude/
  CLAUDE.local.md ← personal, not committed

This hierarchical layout is documented in multiple sources [6] [7] and commonly used in production monorepos. The pattern allows for:

• Root-level guidance that applies across the entire project
• Package-specific overrides where subdirectories have unique requirements
• Personal preferences kept in home directory configuration files

Agents automatically read the nearest AGENTS.md file in the directory tree, with closer files taking precedence. For example, the OpenAI repository itself uses 88 nested AGENTS.md files [1].

🎓 7) Conclusion

Instruction files like AGENTS.md, CLAUDE.md, and CODEX.md are not documentation for humans - they're documentation for your AI teammate. They act as the agent's onboarding manual, the place where you define the rules, workflows, and architectural knowledge it needs to operate effectively.

When used well, these files dramatically improve:

• consistency
• correctness
• architectural alignment
• workflow reliability

The key is knowing where each type of instruction belongs.

• Global rules go into the root file.
• Workflow rules belong there too.
• Migration rules get their own temporary file.
• One-off tasks stay in the prompt.

Master this structure, and your AI coding assistant will behave like a real teammate, not a hallucinating intern.

References

1. Factory AI. "AGENTS.md - Open Format for Guiding Coding Agents." Available: https://agents.md/
2. Anthropic Engineering Team. "Claude Code: Best Practices." Anthropic Technical Blog, 2025. Available: https://www.anthropic.com/engineering/claude-code-best-practices
3. Reddit Community. "AGENTS.md, CODEX.md, INSTRUCTIONS.md, CLAUDE.md." r/OpenAI, 2025. Available: https://www.reddit.com/r/OpenAI/comments/1n8r8tp/
4. "On the Use of Agentic Coding Manifests - Empirical Study." ArXiv, 2025. Available: https://arxiv.org/abs/2509.14744
5. Factory AI. "AGENTS.md Configuration Documentation." Factory AI CLI Docs, 2025. Available: https://docs.factory.ai/cli/configuration/agents-md/
6. Medium. "AGENTS.md: The New README for AI Coding Agents." 2025. Available: https://medium.com/@algorythmos/agents-md-the-new-readme-for-ai-coding-agents-713828c5c63b
7. Dev.to. "Steering AI Agents in Monorepos with AGENTS.md." Datadog Frontend Engineering, 2025. Available: https://dev.to/datadog-frontend-dev/steering-ai-agents-in-monorepos-with-agentsmd-13g0