The fair objection: why another markdown file?
Any disciplined engineer should meet a new repository file with suspicion. You already have README.md, AGENTS.md, CLAUDE.md, SOUL.md, DESIGN.md and your editor's rules files. Every extra file costs context tokens and competes for the model's attention.
If NORTH.md were just another vision doc or a list of tips, it would deserve deletion. It exists for one situation that neither rules nor vision statements address: choosing between valid paths that compete.
The Dilemma
An agent receives an ambiguous refactoring task. Three paths all pass CI, obey AGENTS.md and respect CONSTITUTION.md:
1. The timid patch that leaves the root cause in place.
2. The sprawling rewrite that adds dependencies and work nobody asked for.
3. The calibrated move that removes the failure mode without over-engineering commodity code.
Which does the agent choose? Our hypothesis: with nothing stating the project's direction, it drifts to 1 or 2. NORTH.md is designed to make 3 the obvious choice.
Who answers what
Each file answers a different question:
| File | Core question | Read by | Boundary with NORTH.md |
|---|---|---|---|
| README.md | What is this project? | People: users, contributors, evaluators. | README describes what exists today; NORTH.md declares where it is going and how far to push. |
| AGENTS.md / CLAUDE.md | How do we work here? | Coding agents. AGENTS.md is read by many tools (see agents.md); CLAUDE.md by Claude Code. | AGENTS.md tells an agent how to run the tests; NORTH.md tells it what quality counts as shipped. |
| SOUL.md | Who is the agent? | The agent itself: its persona, values, and tone. | SOUL.md shapes how the agent speaks and behaves; NORTH.md shapes what the project optimises for. |
| DESIGN.md | What should the interface look like, and why? | Coding agents that generate UI. | DESIGN.md defines the tokens; NORTH.md says whether visual polish is a 10x bet or a 1.1x surface. |
| VISION.md | What future are we pursuing? | Founders and planners. No formal convention exists. | A vision describes the destination; NORTH.md adds the defaults that decide today's pull request. |
| CONSTITUTION.md | Which principles and boundaries are non-negotiable? | Coding agents and the people who review their work. | A constitution sets the limits; NORTH.md sets direction, ambition and trade-off defaults inside them. |
| NORTH.md | Where are we going, and how far do we push? | People and coding agents making non-trivial decisions. | The proposed direction layer: judgment for when every rule is satisfied and more than one path is still valid. |
Where the lines blur
1. NORTH.md vs. VISION.md
VISION.md has no formal convention. Where it exists, it usually describes the world the project hopes to create, and it is written to inspire. An agent working on a pull request on a Tuesday afternoon cannot derive from it whether to build or buy a webhook queue.
NORTH.md is operational. It declares concrete asymmetric bets (“Go 10x on e-invoicing correctness; accept 1.1x on the settings UI”), specific refusals (“We do not build a CRM”) and precomputed trade-off defaults (“Safety over speed on fiscal code; speed over safety on internal admin”).
2. NORTH.md vs. CONSTITUTION.md
CONSTITUTION.md sets non-negotiable principles and boundaries. There is no single standard: agentconstitution.dev proposes a project-level format, and GitHub Spec Kit keeps a project constitution of principles and governance. Some formats also record “tension pairs” (X over Y).
NORTH.md sets direction. Knowing what you must never do does not tell you what calibre of work is expected, or where to be ambitious and where to stop. If your constitution already records trade-offs, link to it from NORTH.md instead of repeating them.
3. NORTH.md vs. AGENTS.md / CLAUDE.md
AGENTS.md covers the mechanics of execution: how to build, which linter to run, which conventions to follow. It keeps the agent from breaking the repository.
NORTH.md covers the judgment of the increment: is a feature done when the unit tests pass, or does The Bar also demand documentation, a public API and an audit trail?
4. NORTH.md vs. DESIGN.md
DESIGN.md is a format from Google Labs for describing a visual identity to coding agents: machine-readable design tokens in YAML front matter, with the rationale in markdown. It is in alpha.
NORTH.md sets the priority of visual craft: whether pixel-perfect micro-animations are a 10x bet (a landing page, say) or an over-engineered distraction (an internal admin table).
A proposed five-layer model
Instead of one long instruction file, we propose five small files, each answering one question. It is a model, not an established standard, and most repositories will use only some of the layers.
Layer 1: Limits
CONSTITUTION.md
Non-negotiable principles and boundaries.
Community · agentconstitution.dev
Layer 2: Execution
AGENTS.md
How to build, test and work in the repository.
agents.md · Linux Foundation
Layer 3: Look
DESIGN.md
Design tokens and the rationale behind them.
Google Labs
Layer 4: Persona
SOUL.md
The agent's persona, values and tone.
soul.md
Layer 5: Direction
NORTH.md
Purpose, ambition and precomputed trade-offs.
This spec · MIT