Working with AI Coding Agents — A Practitioner's Guide (2026)

How It Works

• Place an AGENTS.md at your project root — plain Markdown, no special schema.
• Agents read the nearest AGENTS.md in the directory tree (for monorepo support, nest them).
• User prompts always override the file contents.

# Claude Code
ln -s AGENTS.md CLAUDE.md

# Windsurf
ln -s AGENTS.md .windsurfrules

# GitHub Copilot
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md

# Cursor reads AGENTS.md natively (late 2025+)
# For older versions:
ln -s AGENTS.md .cursorrules

Tier 1: High Impact (Always Include)

Project Overview — Two or three sentences: what the project does, core tech stack, and purpose. This prevents the agent from exploring your codebase blindly.

Commands — Exact commands for build, test, lint, and deploy. Write them as the agent should run them, inside code blocks. Don't write "install dependencies" — write pnpm install.

Code Style & Conventions — Specific patterns: functional vs. class-based, naming conventions, error handling. Point to real files as examples rather than describing patterns abstractly. "Use functional components like Projects.tsx; avoid class-based patterns like Admin.tsx" beats a paragraph of explanation.

Logging Standards — The single most impactful rule for long-term maintainability (see Section 7).

Tier 2: Medium Impact

Architecture Pointers — Describe capabilities, not file paths. "Authentication logic is in the auth module" is better than "Auth is at src/modules/auth/handlers.ts" — paths change, capabilities don't. Stale paths actively poison the agent's context.

Dos and Don'ts — Explicit patterns to follow and avoid, with file references.

Testing Requirements — Framework, where tests live, whether to write tests first.

Tier 3: Diminishing Returns

PR/Commit Guidelines, Security Notes, Persona Instructions — Simple persona labels like "you are a senior engineer" have minimal measured impact. However, domain-framing context ("this is a regulated financial services codebase where auditability matters") can meaningfully shape output for domain-specific tasks.

Enforce — Hooks & CI Gates

Deterministic. Shell commands that run at lifecycle points. The agent cannot bypass these. Exit code 2 = blocked, no negotiation. Use for: formatting, linting, test execution, security scanning, blocking writes to sensitive files.

Advise — Config Files (AGENTS.md / CLAUDE.md)

Advisory. The agent reads these and follows them most of the time, but under context pressure or conflicting signals, it may deviate. Use for: code style, architecture guidance, logging patterns, naming conventions.

Suggest — In-Prompt Guidance

Ephemeral. Contextual instructions in your prompt. Highest priority for the current task but gone next session. Use for: one-off requirements, task-specific constraints.

The Five-Part Logging Pattern

When the agent writes code that processes collections (records, API calls, files, jobs — anything in a loop or batch), it should implement:

=======================================
RUN STARTED: 2026-02-14 09:30:15
Total items found: 150
Items matching filters: 42
Filters applied: status=pending, date ≥ 2026-01-01
Batch size: 10 | Estimated batches: 5
=======================================

--- Batch 1/5 (items 1-10 of 42) ----
--- Batch 2/5 (items 11-20 of 42) ----

>>>>>> ITEM START [14/42] id=ENV-2026-0042 at 2026-02-14 09:30:17 <<<<<<
    Validating envelope ENV-2026-0042 against schema v2.1
    Schema validation passed
    Sending to eKYC provider Evrotrust (attempt 1/3)
    eKYC response received: status=verified, confidence=0.94
    Updating database record: status → VERIFIED
<<<<<< ITEM END [14/42] id=ENV-2026-0042 result=SUCCESS duration=1.23s >>>>>>

[1/42]  Processing ENV-2026-0042... OK (1.23s)
[2/42]  Processing ENV-2026-0043... FAILED: Certificate expired
[3/42]  Processing ENV-2026-0044... SKIPPED: Already verified

=======================================
RUN COMPLETED: 2026-02-14 09:35:22
Total duration: 5m 7s
Processed: 42/42
  Successful: 38
  Failed: 3
  Skipped: 1
Failed items: ENV-2026-0042, ENV-2026-0051, ENV-2026-0089
=======================================

Log Message Quality

Since the code is LLM-generated, the person reading logs likely didn't write the code. Every message must be self-explanatory:

When to Use Structured JSON Logging Instead

The human-readable pattern above is ideal for scripts, batch jobs, and CLI tools. For production services feeding into observability stacks (ELK, Datadog, Grafana), consider specifying structured JSON logging in your config:

For production services, emit structured JSON logs:
{"ts":"...","level":"info","op":"ekyc_verify","item_id":"ENV-042","attempt":2,"max":3}

For scripts and CLI tools, use the human-readable
ITEM START/END delimiter pattern described above.

Useful Commands for Log Analysis

# Find all failures
grep "ITEM END.*FAILED" run.log

# Extract failed item IDs
grep "ITEM END.*FAILED" run.log | grep -oP 'id=\K[^ ]+'

# Show everything for a specific item
sed -n '/ITEM START.*id=ENV-2026-0042/,/ITEM END.*id=ENV-2026-0042/p' run.log

# Count results by type
grep -c "result=SUCCESS" run.log
grep -c "result=FAILED" run.log

Example: Auto-Format After Every Edit

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

Example: Block Writes to Sensitive Files

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | grep -qE '\\.(env|pem|key)$' && exit 2 ||"
          }
        ]
      }
    ]
  }
}

Genuinely Works

Has Caveats

Overhyped

Step 1: Create Your AGENTS.md30 min

# AGENTS.md

## Project
[Project name] is a [brief description]. Built with [tech stack].

## Commands
```
[package-manager] install     # Install dependencies
[package-manager] run dev     # Start dev server (port [N])
[package-manager] run test    # Run all tests
[package-manager] run lint    # Lint and auto-fix
```

## Code Style
- [Your conventions: functional vs OOP, naming, etc.]
- Good example: see `[path/to/exemplary/file]`
- Avoid patterns in: `[path/to/legacy/file]`

## Logging Standards
When writing batch processing or pipeline code, implement
dual logging (file + stdout) with these requirements:
- Run header: total count, filtered count, filters, batch size
- Batch progress: "Batch N/Total (items X-Y of Z)"
- File log delimiters:
  ">>>>>> ITEM START [N/Total] id=ID at TIMESTAMP <<<<<<"
  "<<<<<< ITEM END [N/Total] id=ID result=STATUS duration=Xs >>>>>>"
- Console: one line per item "[N/Total] Processing ID... STATUS"
- Run summary: duration, success/fail/skip counts, failed IDs
All log messages must name the operation, include the item ID,
and be self-explanatory without reading source code.

For production services, use structured JSON logging instead.

## Do / Don't
- DO: [specific instruction with file reference]
- DON'T: [specific antipattern with file reference]

## Testing
- Framework: [Jest/pytest/etc.]
- Run single test: `[command]`
- Tests live in: `[directory]`

Step 2: Set Up Symlinks5 min

# From project root:
ln -s AGENTS.md CLAUDE.md
ln -s AGENTS.md .windsurfrules
mkdir -p .github
ln -s ../AGENTS.md .github/copilot-instructions.md

Step 3: Add Hooks for Critical Rules15 min

Use the interactive /hooks command in Claude Code, or create .claude/settings.json:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write 2>/dev/null ||"
        }]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "jq -r '.tool_input.file_path' | grep -qE '\\.(env|pem|key)$' && exit 2 ||"
        }]
      }
    ]
  }
}

Step 4: Add Cursor Glob Rules (Optional)15 min

If your team uses Cursor and wants context-aware rule activation, create .cursor/rules/logging-standards.mdc:

---
description: Logging standards for batch processing and data pipelines.
globs: "**/*.{py,js,ts,cs,java,go,rb,php}"
alwaysApply: false
---

[Paste logging standards from your AGENTS.md here]

Step 5: Treat It Like CodeOngoing

• Update AGENTS.md in the same PR when conventions change.
• Add a rule the second time you see the agent make the same mistake (not the first — one-off mistakes aren't worth a permanent rule).
• Delete anything that's no longer true. Stale rules are worse than missing rules.
• Review quarterly. Delete more than you add.
• Ask the agent to audit: "Review this AGENTS.md against the current codebase and flag anything stale."

Do These Six Things

1. Create an `AGENTS.md` at the root of every active project. Keep it under 150 lines. Focus on commands, code style, and logging.
2. Set up symlinks to CLAUDE.md, .windsurfrules, etc. so every tool reads the same source.
3. Add logging standards from Section 7. This is the highest-ROI advisory rule you can write.
4. Add hooks for anything that must be deterministic: formatting, security boundaries, test execution.
5. Defer to existing tooling. Instead of describing formatting rules in your config, tell the agent to run the linter. Single source of truth.
6. Treat `AGENTS.md` as code: version it, review it, prune it quarterly. Stale rules cause more harm than missing rules.

Skip for Now

• Complex multi-file rule hierarchies — start simple, add complexity when you hit specific problems.
• Agent observability platforms — unless you're building LLM-powered production systems.
• Simple persona labels — concrete rules beat "you are a senior engineer" every time.
• Detailed file path documentation — it goes stale and actively misleads.