Intent Nodes

What Intent Nodes Are

An Intent Node is a structured file — typically AGENTS.md or CLAUDE.md — placed in a directory of your codebase. It declares what that area of the code is for, what patterns to follow, and what boundaries exist.

Intent Nodes are the building blocks of the Intent Layer. Together, they form a hierarchical map that AI agents traverse to understand your system.

What Goes in an Intent Node

A well-written Intent Node answers the questions an experienced teammate would answer if you asked them about a part of the codebase:

• Purpose — What is this module/service/component for? What problem does it solve?
• Patterns — What conventions are followed here? How should new code look?
• Boundaries — What does this module own? What should it not do?
• Key files — Which files are most important to understand this area?
• Downlinks — Pointers to child Intent Nodes in subdirectories

Example

Here's a minimal Intent Node for a payment processing service:

# Payment Service

## Purpose
Handles all payment processing — charges, refunds, subscription billing.
Integrates with Stripe as the sole payment provider.

## Patterns
- All monetary values stored as integers (cents), never floats
- Every charge must create an audit log entry
- Stripe webhook handlers live in `webhooks/` — one file per event type

## Boundaries
- Does NOT handle user authentication (that's `auth-service`)
- Does NOT send customer emails (emits events, `notification-service` handles delivery)

## Key Files
- `charge.ts` — Core charging logic
- `webhooks/` — Stripe webhook handlers
- `types.ts` — Shared types for monetary operations

Why They Work

Intent Nodes work because they're:

1. Co-located with code — They live next to the code they describe, so they're easy to maintain and hard to forget
2. Agent-readable — Tools like Cursor, Claude Code, and Copilot automatically read AGENTS.md files when working in a directory
3. Hierarchical — They can link to child nodes, creating a progressively detailed map
4. Lightweight — A useful Intent Node can be 10-20 lines. They're not documentation novels.

Intent Nodes vs. README Files

READMEs tell you how to use or set up a project. Intent Nodes tell you how to work on it. The audience is different — Intent Nodes are written for AI agents and new contributors who need to make changes, not for users who need to run the software.

In practice, many teams keep both: a README for setup/usage and an AGENTS.md for development context.

File Naming

Different AI tools look for different filenames:

You can use symlinks to serve the same content to multiple tools: CLAUDE.md → AGENTS.md.