Ariadne Thread

Create codebases that AI agents can navigate efficiently through progressive disclosure — revealing only what's needed, when it's needed.

When to Use

Apply this skill when the user:

• - Starts a new project and wants AI-friendly structure
• Restructures or indexes an existing codebase
• Adds project navigation (AGENTS.md, INDEX.md, llms.txt)
• Designs module boundaries and dependencies
• Mentions: "AI-friendly project", "progressive disclosure", "project index", "codebase navigation", or "ariadne"

Language-agnostic: applies to any language. See language-adaptation.md for per-language mappings.

When NOT to apply: Minimal single-file projects, quick prototypes, or codebases where indexing overhead outweighs benefit. Skip full L1/L2 when the project has fewer than ~5 source files; a lightweight AGENTS.md may suffice.

Core Philosophy

Like Ariadne's thread through the labyrinth, a well-indexed codebase gives AI agents a clear path from project overview to implementation detail. An agent should understand your project structure, locate any function, and assess the impact of any modification — without reading the entire codebase.

Two optimization targets:

1. 1. Navigation efficiency — minimize tokens consumed to find the right code
2. Modification safety — maximize probability of correct changes via explicit contracts and dependency visibility

The 4-Level Index Architecture

CODEBLOCK0

AI agents start at L0 and drill down only as needed.

L0: Project Root Index

Create an AGENTS.md at the project root with:

1. 1. One-line project description
2. Directory map — ASCII tree with purpose annotations
3. Quick navigation table — key entry points by area
4. Build & test commands
5. Code conventions summary
6. Architectural constraints — illegal dependency directions, global invariants
7. Cross-cutting behavior patterns — error handling, logging, concurrency model
8. Agent Workflow — at the end of the file (Checklist-at-END format): mandatory steps before editing — locate module via Quick Navigation, open INDEX.md and check Dependents before modifying public API, confirm Modification Risk for breaking changes, run Tests before finishing
9. Index exclusions — Optional .cursorignore (same syntax as .gitignore) to exclude build artifacts, dependencies, generated code; common examples: node_modules/, dist/, vendor/, __pycache__/, target/, *.generated.* — adapt to your ecosystem

The cross-cutting patterns section is critical: it prevents the AI from reading 3-4 existing files just to infer "how do we handle errors here?". One 30-line declaration replaces ~1500 tokens of pattern inference.

All 9 sections are required — they are the difference between an AGENTS.md that actually guides AI behavior and one that merely documents the project for humans. The sections that get skipped most often (Architectural Constraints, Cross-Cutting Patterns, Agent Workflow checklist) are also the ones with the highest AI value.

Navigation priority: Prefer navigating via INDEX.md Dependents and Dependencies over semantic/keyword search. Structural dependency paths surface architecturally critical files that retrieval often misses. When modifying a module's public API, always consult its Dependents list first to assess blast radius.

Information placement (Lost in the Middle): LLMs attend more to context start and end. Place high-priority content (Build, Quick Navigation, Agent Workflow) at the beginning or end of AGENTS.md; keep secondary sections toward the middle.

CODEBLOCK1

For the full AGENTS.md template, see index-templates.md.

L1: Module Index

Every module directory gets an INDEX.md — any directory that has a public API, a barrel/__init__, or 3+ source files. This is the most information-dense layer — it must answer not just "what does this module do?" but also "who depends on it?", "what will break if I change it?", and "which file should I edit for task X?".

Example below uses domain auth; replace with your domain — billing, reporting, catalog, etc.

CODEBLOCK2

Voice Coding: L1 Task Routing supports "say task → get file path" — map natural-language tasks to specific files for hands-free navigation.

Common mistake — avoid narrative prose in INDEX.md: The structured sections (Dependents, Modification Risk, Task Routing) are what make an INDEX.md useful for AI navigation. A long prose description of each file ("This file is responsible for X, it does Y, here are some notes...") might look thorough but it fails to answer the core AI questions: who depends on this? what breaks if I change it? which file do I edit? Prefer the structured template even if it feels terse — density and scanability beat completeness.

Why each section matters for AI:

Section	AI Question It Answers	What it replaces
Dependents	"Who calls me? What breaks if I change?"	Full-project grep to discover callers
Interface Contract

"What invariants must I preserve?" | Re-reading caller files to infer constraints |
| Modification Risk | "Is this change safe? How many files to update?" | Underestimating blast radius and missing dependents |
| Task Routing | "Which file should I edit for task X?" | Reading wrong files before finding the right one |
| Tests | "What should I run to verify?" | Searching for test files across the project |

The actual token savings depend heavily on project size and how the AI handles uncertainty — they scale with the number of modules and files. The value is real but varies; don't treat any specific number as a guarantee.

For the full INDEX.md template, see index-templates.md.

L2: File-Level Intent + Contract

Every source file starts with an intent header. For public API files (called by other modules), extend the header with contract annotations:

C++ (public header with contract):
CODEBLOCK3

TypeScript (public API with contract):
CODEBLOCK4

Internal files (not called across module boundaries) keep the simple 3-5 line header. Only public API files need full contracts.

Contract annotation reference:

Annotation	Purpose	When to Use
INLINECODE15	What must be true before calling	Input validation assumptions
INLINECODE16

What is guaranteed after return | Return value constraints |
| @throws | What errors can be thrown | All error conditions |
| @sideeffect | What state changes beyond return value | DB writes, events, cache invalidation |
| @threadsafe | Concurrency guarantee | Multi-threaded systems |
| @performance | Latency/throughput constraints | Hot-path functions |
| @lines / @range | Key line ranges for large files | When file exceeds ~300 LOC; e.g. @lines 45-89 main logic |

Path convention: In L1, use repo-root-relative paths (e.g. src/auth/authenticate.ts) — avoid ./, ../ for clarity and Voice Coding compatibility.

See index-templates.md for all language templates.

L3: Inline Annotations

Comment ONLY non-obvious logic:

CODEBLOCK5

Never comment obvious code. AI reads code natively — comments that restate the code are pure noise.

Module Design Principles

Single Responsibility

• - One module = one clear purpose (stated in INDEX.md)
• One file = one concept, under 300 lines (or ~500 for verbose languages)
• If you cannot name it clearly, split it

CODEBLOCK6

Clear Dependency Direction

Typical layering (example; adapt names to your project — e.g. app/, packages/, layers/):

CODEBLOCK7

• - Depend inward (presentation → domain → infrastructure), never outward
• Document the actual direction in AGENTS.md Architectural Constraints

Small, Focused Files

Metric	Target	Reason
Lines per file	< 300 (< 500 for verbose languages)	AI reads full files; smaller = less wasted context
Public symbols per file

1-5 | Clear public surface | | Dependencies per file | < 5-8 imports/includes | Limits blast radius |

Library vs Application Projects

The index structure works for both, but libraries differ in several key areas:

Aspect	Application	Library
Build & Test	Has build + run commands	May have no build step (header-only); tests often in separate projects
Public API

Internal modules calling each other | Consumers are external; public API = exported headers / package interface |
| Dependents (Fan-in) | Other modules in the same project | Primarily external consumers (note "External: N/A — library" in Dependents) |
| Dependency direction | presentation → domain → infra (example) | Libraries: typically flat or layered by abstraction (e.g., core ← filtering ← testing) |
| File size targets | Strict (you control the code) | Guideline only for upstream/third-party code you do not own |

Header-only libraries (C++): no include/ + src/ split — all code is in headers. The entry header (e.g., library.hpp) acts as the barrel/__init__. There is no independent build step; document how consumers include and link.

Upstream / third-party code: When indexing a library you do not maintain (e.g., a vendored dependency), create indexes (L0 + L1) for navigation but do NOT modify source files (no L2 header changes, no refactoring oversized files). Flag issues in indexes with ⚠ UPSTREAM instead of ⚠ needs split.

Intent-Oriented Code

Write code that expresses what it accomplishes, not how.

Naming Principles (Universal)

Layer	Principle	C++ Example	TypeScript Example	Python Example
Files	descriptive, one concept	INLINECODE36	INLINECODE37	INLINECODE38
Dirs

group by domain | billing/, auth/ | billing/, auth/ | billing/, auth/ | | Functions | verb-first, outcome | calculate_total() | calculateTotal() | calculate_total() | | Classes | PascalCase noun | InvoiceCalculator | InvoiceCalculator | InvoiceCalculator | | Constants | SCREAMING_SNAKE | MAX_RETRY_COUNT | MAX_RETRY_COUNT | MAX_RETRY_COUNT | | Booleans | is/has/should | is_authenticated | isAuthenticated | is_authenticated |

Function Signatures — Express Intent

CODEBLOCK8

API Design

Applies to any external interface (REST, gRPC, library headers, CLI):

• - Name by resource/concept, not implementation
• Consistent input/output contracts
• Version your API (URL path, header, or namespace)
• Document error conditions explicitly

For detailed conventions, see naming-api-conventions.md.

Documentation Tiers

Not all documentation serves the same audience or requires the same update frequency. This skill distinguishes two tiers:

Tier	Files	Audience	Update Timing	Staleness Impact
A — AI Runtime Index	INLINECODE57, INDEX.md, file headers (L2), inline comments (L3)	AI agents	Real-time — atomic with code changes	Critical: stale → wrong navigation, missed dependencies, broken contracts
B — Human Communication

README.md, architecture.md, ADRs, API docs, guides, changelogs | Human developers | Batch — at iteration end | Moderate: stale → human confusion, but AI unaffected |

Key insight: Tier A indexes are the AI's "working memory" — they must be updated in the same operation as the code change. Tier B documents are "reports" derived from Tier A — they can be regenerated at iteration boundaries.

During active development: AI agents only maintain Tier A files. Tier B documents are transparent to the AI — they are neither read nor written until the iteration-end sync.

Token economics: This separation reduces per-change AI overhead by ~60%, while actually improving Tier B document quality (batch updates are more coherent than incremental patches).

Project Documentation (Tier B)

Human-facing documentation follows the same progressive disclosure structure, but is maintained at iteration boundaries rather than in real-time. Common structure (adapt to project; ADR is optional — omit adr/ if you don't use ADRs):

CODEBLOCK9

Rules:

1. 1. One doc = one purpose
2. INDEX.md in every doc directory
3. Link, don't inline — reference Tier A indexes (INDEX.md) as source of truth
4. Max 500 lines per doc
5. Updated at iteration end — not on every code change

For doc templates and ADR format, see doc-standards.md.

Language Adaptation

The 4-level index and design principles are universal. Per-language conventions (C++, TypeScript, Python, Go, Rust, Java/Kotlin) — directory layout, file naming, L2 contract annotations, build commands — are in language-adaptation.md. Load that file when indexing a project in a specific language.

Workflow: New Project

1. 1. Identify language ecosystem — see language-adaptation.md
2. Design the directory map before writing code
3. Create AGENTS.md — project table of contents + cross-cutting patterns + AI Agent Instructions
4. Create module INDEX.md as you create each directory (include all sections)
5. Add file intent headers — simple for internal files, full contract for public API
6. Follow naming conventions from day one
7. Defer Tier B docs — create docs/ directory structure but fill content only at first iteration end

Workflow: Retrofit Existing Project

Principle: Document first, refactor later. Create indexes for the codebase AS-IS. Flag issues (oversized files, violations) in the indexes but do not block on fixing them.

Monorepo / sub-project: If the target is a sub-directory within a larger repo, place AGENTS.md at the sub-project root (e.g., lib/AGENTS.md). Build commands should cover this sub-project only (or note the parent command). See the monorepo variant in templates.

Priority: Start with the highest Fan-in module (most depended-on) — it yields the most navigation savings.

Partial migration: If migrating a single module (not the whole project), start at L1 — create INDEX.md for the target module directly. Skip L0; assume the parent AGENTS.md will be created later or already exists.

Library projects: If the target is a library (not an application), see Library vs Application Projects for differences in Build & Test, Public API, and Dependents. For header-only C++ libraries, the entry header acts as the barrel — document it in AGENTS.md and treat the main header directory as a single module.

Upstream / third-party code: If you do not own the source code (vendored dependency, upstream library), create L0 + L1 indexes for navigation but skip L2 (do not modify source file headers) and L3 (do not modify inline comments). Flag oversized files with ⚠ UPSTREAM instead of suggesting splits.

1. 1. Create L0: Write AGENTS.md with directory map, navigation table, cross-cutting patterns, and AI Agent Instructions. Mark any discovered architectural violations as ⚠ KNOWN VIOLATION in Architectural Constraints
2. Add L1: Create INDEX.md in each major module — start with Public API + Dependencies + Dependents. Use grep -rn "from [module]" . or IDE search to discover Dependents. For flat directories with many files, use section headers within INDEX.md to organize logical groups (see L1 Retrofit Tips)
3. Enrich L1: Add Interface Contract, Task Routing, Modification Risk, Tests. In Files table, flag oversized files (e.g., ⚠ 1066 lines, needs split or ⚠ UPSTREAM for code you do not own). Also flag files with forbidden names — utils.*, helpers.*, types.*, common.* — with ⚠ needs split/rename and add a rename task to Task Routing. These names indicate unclear responsibility and should be resolved over time
4. Verify L2: Ensure public API files have contract headers; internal files have intent headers (skip for upstream code)
5. Audit L3: Remove obvious comments, add explanations for tricky logic (skip for upstream code)
6. Validate per module: After each module's INDEX.md, test: ask an AI to locate a function and assess change impact. If it reads > 5 files or misses a dependent, improve that index before moving on
7. Sync Tier B: Once all Tier A indexes are complete, run an iteration-end sync to generate/update all human-facing docs from Tier A content

Index Maintenance

Directive: Every code change MUST include atomic updates to relevant Tier A indexes. See index-maintenance.md for the full trigger→action table, anti-patterns, and Tier B sync workflow. When the user says "documentation sync" or "iteration end", execute the Tier B batch process.

Detailed References

• - Index templates (L0/L1/L2): index-templates.md
• Naming + API conventions: naming-api-conventions.md
• Documentation standards + ADR format: doc-standards.md
• Language adaptation (C++, TS, Python, Go, Rust, Java): language-adaptation.md
• Index maintenance (Tier A/B triggers): index-maintenance.md