Init Agents

Initialize or update

AGENTS.md

What AGENTS.md Is

A vendor-agnostic markdown file that provides persistent, project-specific guidance to AI coding agents. Codex, OpenCode, Cursor, and GitHub Copilot read it. Claude Code uses

CLAUDE.md

Contains:

• Clear dos and don'ts (tech stack, versions, patterns)
• Executable commands (file-scoped type-check, lint, format, test)
• Project structure hints and key file locations
• Safety and permission boundaries
• Code style examples (good vs bad)
• Git workflow and PR checklist

Does NOT contain:

• Business rules (that belongs in

  KNOWLEDGE.md

  )
• Product roadmap (not included in this document)

Tool Conventions

AGENTS.md

~/.codex/AGENTS.md

AGENTS.md

~/.config/opencode/AGENTS.md

AGENTS.md

.cursor/rules/

CLAUDE.md

AGENTS.md

.github/agents/*.md

Project root

AGENTS.md

CLAUDE.md

CLAUDE.md

AGENTS.md

Six Core Areas (Best Practice)

Effective agent files cover all six:

1. Commands — Executable commands with flags (put early in the file)
2. Testing — How to run tests, test-first expectations
3. Project structure — Key paths, where things live
4. Code style — Naming, formatting, patterns with examples
5. Git workflow — Commit format, PR checklist
6. Boundaries — Allowed / ask first / never

Format

# AGENTS.md

This file provides guidance to AI coding agents working in this repository.

## Project Overview
[1-2 sentences: what this project is, key stack]

## Commands
# Type-check single file
npm run tsc --noEmit path/to/file.ts

# Lint single file
npm run eslint --fix path/to/file.ts

# Format single file
npm run prettier --write path/to/file.ts

# Run tests (single file or suite)
npm test -- path/to/file.test.ts

## Project Structure
- `src/` — [purpose]
- `docs/` — [purpose]
- [key files that define architecture]

## Do
- [specific rule with versions/libraries]
- [specific rule]

## Don't
- [specific prohibition]
- [specific prohibition]

## Safety and Permissions
**Allowed without prompt:** [read files, run lint/format on single file, run single test]
**Ask first:** [package installs, git push, full build, schema changes]
**Never:** [commit secrets, edit vendor/, modify production configs]

## When Stuck
- Ask a clarifying question or propose a short plan
- Do not push large speculative changes without confirmation

Process

Step 1: Explore Project

Gather in parallel:

• Tech stack (package.json, composer.json, requirements.txt, go.mod, etc.) — versions matter
• Build/lint/test commands from scripts
• Project structure and key entry points
• Existing rules (

  .cursorrules

  ,

  .cursor/rules/

  ,

  .github/copilot-instructions.md

  ,

  CONTRIBUTING.md

  )

• KNOWLEDGE.md

  , if it exists — reference it, don't duplicate

Step 2: Extract Commands

Find file-scoped commands (prefer over full-project builds):

• Type-check:

  tsc --noEmit

  ,

  pyright

  , etc.
• Lint:

  eslint --fix

  ,

  ruff check --fix

  , etc.
• Format:

  prettier --write

  ,

  black

  , etc.
• Test:

  vitest run

  ,

  pytest

  ,

  jest

  , etc.

Include exact flags. Put commands early in the file.

Step 3: Define Boundaries

Three tiers:

• Always do — Run lint/test on changed files, follow style examples
• Ask first — Package installs, git push, full builds, schema changes
• Never — Commit secrets, edit vendor/node_modules, modify production configs

Step 4: Add Code Examples

Point to real files that demonstrate good patterns. Call out legacy code to avoid. Examples beat paragraphs of description.

Step 5: Write or Merge

If

AGENTS.md

CLAUDE.md

1. Read existing content
2. Merge new sections (don't duplicate)
3. Update outdated commands and structure
4. Preserve user customizations

If it doesn't exist:

1. Create from template above
2. Fill with discovered project context
3. Keep it concise — expand over time based on agent mistakes

Companion Documents

KNOWLEDGE.md

init-knowledge

When running init-agents, if companion docs exist, reference them in AGENTS.md (e.g. "See KNOWLEDGE.md for business context"). Don't duplicate their content.

Rules

• Just do it — no approval needed, write directly
• Be specific — "React 18 with TypeScript and Vite" not "React project"
• Commands first — put executable commands early, with flags
• Code examples over prose — one real snippet beats three paragraphs
• File-scoped commands — prefer single-file validation over full builds
• Never commit secrets — most common and valuable boundary
• Hierarchy — project

  AGENTS.md

  overrides global; nested

  AGENTS.override.md

  for subdirs (Codex)
• Iterate — start minimal, add detail when agents make mistakes