agent-setup.astro
// agent-setup.astro

Agent setup guide

Every AI coding tool has a configuration file that gives the agent persistent context about your project. Without it, the agent starts cold every session. With it, it knows your stack, your conventions, and what not to do.

This page covers Claude Code, Codex CLI, Cursor, and Kiro — file structures, what each setting does, and best practices. Everything here is sourced from official documentation.

Claude Code

by Anthropic

A markdown file Claude reads at the start of every session. It gives Claude persistent context it cannot infer from your code alone — build commands, style rules, workflow conventions, architectural decisions.

// config file

CLAUDE.md

~/.claude/CLAUDE.md  (global)
./CLAUDE.md          (project, shared via git)
./CLAUDE.local.md    (project, personal — gitignore this)

// example structure

CLAUDE.md 
# Build & test commands
- Build: npm run build
- Test: npm test -- --run
- Lint: npm run lint

# Code style
- Use ES modules (import/export), not CommonJS
- Prefer named exports over default exports
- TypeScript strict mode — no `any`

# Workflow rules
- Always run lint after editing
- Write tests before marking a task done
- Never commit directly to main

# Architecture
- API routes live in src/routes/
- Shared types in src/types/
- No business logic in route handlers — use services/

✓ include

  • + Build and test commands Claude cannot guess
  • + Style rules that differ from language defaults
  • + Architectural boundaries specific to your project
  • + Non-obvious gotchas or environment quirks
  • + Branch naming and PR conventions

✗ skip

  • − Standard conventions Claude already knows
  • − Detailed API documentation (link to docs instead)
  • − Information that changes frequently
  • − Long explanations or tutorials
  • − File-by-file descriptions of the codebase
  • − Self-evident practices like "write clean code"

// best practices

  • → Keep it under 100 lines. Bloated files cause Claude to ignore your actual instructions.
  • → Use @path/to/file syntax to import other files: See @README.md for project overview.
  • → Add CLAUDE.local.md to .gitignore for personal overrides that shouldn't be shared.
  • → Run /init inside Claude Code to auto-generate a starter CLAUDE.md from your codebase.
  • → For domain-specific workflows, use Skills (.claude/skills/) instead — they load on demand without bloating every session.
  • → Treat it like code: prune it when things go wrong, test changes by watching whether Claude's behavior shifts.

// advanced config

Skills .claude/skills/[name]/SKILL.md

Reusable workflows and domain knowledge Claude loads on demand. Invoke with /skill-name.

Subagents .claude/agents/[name].md

Agents that run in their own context with their own tool access. Good for security reviews, testing, or any focused task.

Hooks .claude/settings.json

Scripts that run automatically at specific points — after file edits, before commits, etc. Unlike CLAUDE.md instructions, hooks are deterministic.

Permissions .claude/settings.json

Allowlist specific tools and commands so Claude doesn't ask for approval on every action.

Source: Anthropic — Claude Code Best Practices ↗

Codex CLI

by OpenAI

AGENTS.md is Codex's equivalent of CLAUDE.md. It's a markdown file loaded before any task that tells Codex how to navigate your codebase, which commands to run, and how to follow your conventions. Files closer to the working directory take priority.

// config file

AGENTS.md

~/.codex/AGENTS.md          (global)
./AGENTS.md                 (project root)
./AGENTS.override.md        (subsystem override — takes priority)

// example structure

AGENTS.md 
## Architecture
- Frontend: Next.js + TypeScript
- API: FastAPI (Python 3.12)
- DB: PostgreSQL via SQLAlchemy

## Conventions
- Use snake_case for Python, camelCase for TypeScript
- New endpoints need a corresponding integration test
- Use pnpm, not npm or yarn

## Working agreements
- Always run `pnpm test` after modifying source files
- Follow the ESLint config; do not disable rules inline
- Prefer `pnpm` when installing dependencies

✓ include

  • + Tech stack and language versions
  • + Package manager preference (pnpm vs npm vs yarn)
  • + Naming conventions per language
  • + Test requirements for new code
  • + Working agreements your team follows

✗ skip

  • − Secrets or API keys — never in any config file
  • − Instructions that conflict with each other
  • − Content that exceeds the 32 KiB default limit (project_doc_max_bytes)
  • − Vague preferences — be specific and use negative instructions

// best practices

  • → Run /init inside a Codex session to generate an AGENTS.md scaffold automatically.
  • → Use AGENTS.override.md in a subdirectory to apply stricter rules to that area only.
  • → The global config lives at ~/.codex/config.toml — set your default model, approval policy, and sandbox mode there.
  • → Named profiles in config.toml let you switch between configs per-project: codex --profile ci.
  • → AGENTS.md is also read by GitHub Copilot, Cursor, Windsurf, and others — it's becoming a cross-tool standard.

// advanced config

config.toml ~/.codex/config.toml

Global config: default model, approval policy (untrusted / on-request / never), sandbox mode (read-only / workspace-write / danger-full-access), web search, named profiles.

Approval policy config.toml → approval_policy

Controls when Codex pauses for permission. untrusted = every action. on-request = risky operations only. never = fully autonomous.

Sandbox mode config.toml → sandbox_mode

Controls filesystem access. read-only is the safe default. workspace-write allows edits within your working directory. danger-full-access is unrestricted.

MCP servers config.toml → [mcp_servers.*]

Extend Codex with external tools via Model Context Protocol. Configure command, env vars, and timeout per server.

Source: Shipyard — Codex CLI Cheatsheet ↗

Cursor

by Anysphere

Rules give Cursor's AI consistent guidance for every interaction in a project. They're injected into the system prompt for Composer, Agent mode, inline completions, and chat. The new .cursor/rules/ directory supports individual rule files with front matter for scoping.

// config file

.cursorrules

./.cursorrules              (project root — legacy, still works)
.cursor/rules/[name].mdc   (new format — per-rule files with metadata)

// example structure

.cursorrules 
# Project: My App
# Stack: Next.js 15, TypeScript 5.4, Tailwind CSS, Drizzle ORM
# Auth: Clerk (not NextAuth)
# State: Zustand (no Redux, no Context API)

## Do Not Use
- `var` — always `const` or `let`
- `React.FC` type — use explicit return types
- Default exports from components — named exports only
- `any` type — use `unknown` and narrow it
- `axios` — use native fetch with lib/api.ts wrapper
- `console.log` — use lib/logger.ts

## File Conventions
- Components: PascalCase.tsx in components/ by feature
- Hooks: use-kebab-case.ts in hooks/
- Utilities: kebab-case.ts in lib/

## Architecture
- app/ — Next.js App Router pages and layouts
- components/ — UI only, no business logic
- features/ — feature modules with components/hooks/types
- lib/ — utilities, API clients, DB access
- server/ — server actions and server-only code

✓ include

  • + Banned patterns section — highest ROI, prevents most correction loops
  • + Tech stack with specific versions and chosen libraries
  • + File naming and directory conventions
  • + Architecture map for Agent mode (it plans before it writes)
  • + Testing framework and approach

✗ skip

  • − Vague preferences ("prefer clean code") — they get ignored
  • − Conflicting rules — the AI will pick one arbitrarily
  • − Rules that are already default behavior — they add noise
  • − Long explanations — state constraints, not rationale

// best practices

  • → The banned patterns section has the highest ROI. Negative instructions ("do not use X") outperform positive style guidance.
  • → Verify it's working: open Cursor Chat and ask "What are the banned patterns in this project?" — it should list exactly what you wrote.
  • → For user-level rules that apply across all projects, go to Cursor Settings → Rules for AI. Project rules always take precedence.
  • → The new .cursor/rules/ format supports scoping rules to specific file types using front matter globs.
  • → Keep rules declarative and terse. The AI needs constraints, not explanations.

// advanced config

.cursor/rules/ (new format) .cursor/rules/[name].mdc

Individual rule files with YAML front matter. Supports scoping rules to specific file patterns, making them load only when relevant.

User-level rules Cursor Settings → Rules for AI

Rules that apply across all your projects. Project-level .cursorrules always override these for that project.

MCP servers Cursor Settings → MCP

Connect external tools via Model Context Protocol. Cursor supports MCP for database access, design tools, issue trackers, and more.

Source: Markaicode — Cursor .cursorrules Guide ↗

Kiro

by AWS / Amazon

Kiro uses steering files — markdown files in .kiro/steering/ — to give the agent persistent knowledge about your workspace. Unlike a single config file, you create multiple focused steering files, each covering one domain. Kiro also supports AGENTS.md at the workspace root for cross-tool compatibility.

// config file

Steering files

~/.kiro/steering/           (global — applies to all workspaces)
.kiro/steering/            (workspace — applies to this project only)

// example structure

Steering files 
---
inclusion: always
---

# Technology Stack

- Framework: Astro 5 with TypeScript strict mode
- Styling: Tailwind CSS v4 via Vite plugin
- Content: MDX with @astrojs/mdx
- Deployment: Vercel (static output)

## Conventions
- Use named exports, not default exports
- All pages use BaseLayout from src/layouts/
- Content lives in src/content/ with Zod schemas in content.config.ts

✓ include

  • + One domain per file — API design, testing, deployment, code style
  • + Include context: explain why decisions were made, not just what they are
  • + Use code snippets and before/after examples
  • + Use file references (#[[file:path]]) to link to live workspace files
  • + Generate the three foundation files (product.md, tech.md, structure.md) first

✗ skip

  • − Never include API keys, passwords, or sensitive data
  • − Don't put everything in one file — focused files load more efficiently
  • − Don't use vague filenames — api-rest-conventions.md beats notes.md

// best practices

  • → Generate foundation files first: Kiro panel → Steering → Generate Steering Docs. Creates product.md, tech.md, and structure.md automatically.
  • → Use inclusion: fileMatch with a glob pattern to load a steering file only when working with matching files.
  • → Use inclusion: manual for heavy reference docs you only need occasionally. Reference with #filename in chat.
  • → Use inclusion: auto with a name and description — Kiro will include the file automatically when your request matches.
  • → Workspace steering overrides global steering when there's a conflict.
  • → Steering files support #[[file:path]] references to pull in live workspace files like openapi.yaml or .env.example.

// advanced config

product.md .kiro/steering/product.md

Foundation file. Defines your product's purpose, target users, key features, and business objectives.

tech.md .kiro/steering/tech.md

Foundation file. Documents your chosen frameworks, libraries, tools, and technical constraints.

structure.md .kiro/steering/structure.md

Foundation file. Outlines file organization, naming conventions, import patterns, and architectural decisions.

Specs .kiro/specs/[feature]/

Spec-driven development: requirements.md, design.md, tasks.md. Kiro treats specs as source of truth and code as a build artifact.

Hooks .kiro/hooks/[name].json

Automate agent actions based on IDE events: file edits, prompt submissions, task completions, tool use.

Agent Skills .kiro/skills/

On-demand modular instruction packages for specialized workflows. Invoked manually or automatically based on context.

Source: Kiro Docs — Steering ↗

// last verified May 2026 — these tools update frequently, always check official docs

Something out of date or missing? The log is where I document what I'm actually using.

main
rss