Best Practices
Proven patterns for getting the most out of context intelligence with Pilot. These practices are derived from real-world usage across 500+ autonomous task executions.
Index Document Design
The index document (DEVELOPMENT-README.md) is loaded every session. Its size directly
impacts token budget for the rest of the conversation.
Keep It Under 500 Words
# Project — Development Context
## Quick Navigation
| Document | When to Read |
|----------|-------------|
| This file | Every session |
| system/ARCHITECTURE.md | System design |
| tasks/TASK-XX.md | Active task |
## Current State
Version: v2.1.0
[Brief component status table]
## Project Structure
[Compact tree, 10-15 lines max]Link, Don’t Inline
Reference detailed docs instead of embedding them in the index:
## Authentication
See [system/auth.md](system/auth.md) for the full auth flow.
Key decision: JWT over sessions (see memories/decisions.md).Not:
## Authentication
[300 lines of auth documentation that loads every single session...]Every word in the index costs tokens on every task. A 2,000-word index wastes ~8,000 tokens per session compared to a 500-word version.
Lazy Loading Strategy
Tier Your Documentation
Organize docs by access frequency:
| Tier | Files | Access Pattern |
|---|---|---|
| Hot | Index, active task doc | Every session |
| Warm | Architecture, feature matrix | Referenced tasks |
| Cold | SOPs, archived tasks | Specific workflows |
| Frozen | Old task archives | Never loaded |
Write Self-Contained Task Docs
Each task document should include everything needed for that task:
# TASK-42: Add Rate Limiting
## Context
API currently has no rate limiting. See ARCHITECTURE.md for endpoint list.
## Implementation
1. Add middleware in `src/api/middleware/`
2. Configure limits in `config.yaml`
3. Add Redis counter (or in-memory for dev)
## Affected Files
- src/api/middleware/rate-limit.ts (new)
- src/api/server.ts (wire middleware)
- config/default.yaml (add limits section)
## Test Plan
- Unit: middleware returns 429 after limit
- Integration: concurrent requests hit limitThis way, the context engine loads the index + one task doc and has full context (~5k tokens total).
Knowledge Graph Usage
Capture Decisions When They’re Made
Non-obvious technical decisions should be recorded immediately:
- Why a specific library was chosen over alternatives
- Why an approach was rejected
- Trade-offs that were consciously accepted
The context engine captures these automatically during /nav-task archive, but you can also
trigger manual capture via /nav-graph.
Document Pitfalls After Every Bug
When you hit an unexpected issue, record it. Future tasks in the same area will surface the pitfall automatically:
Pitfall: macOS tar adds ._* resource forks
Context: Release packaging
Fix: COPYFILE_DISABLE=1 in MakefileReview the Graph Periodically
The knowledge graph grows over time. Periodically review entries to:
- Remove outdated decisions (superseded by later work)
- Merge duplicate patterns
- Verify pitfalls are still relevant
Session Management
Create Markers Before Risky Changes
Before refactors, dependency upgrades, or architectural changes:
/nav-marker "Before auth system refactor"This creates a checkpoint in .context-markers/ that you can resume from
if the change goes wrong.
Compact After Each Task
After completing a task, clear the conversation context:
/nav-compactThis preserves knowledge in the graph while freeing context window tokens for the next task. Without compaction, context accumulates and efficiency drops.
Use Loop Mode for Multi-Step Work
For tasks requiring iteration (implement → test → fix → test), use loop mode:
/nav-loop "Implement and verify rate limiting"Loop mode runs in phases (Research → Implement → Verify) with automatic completion detection. It prevents premature task completion.
Documentation Loading Budget
Target these token budgets per session type:
| Session Type | Target Budget | What to Load |
|---|---|---|
| Simple fix | ~4,000 tokens | Index + task doc |
| Feature work | ~8,000 tokens | Index + task + feature matrix |
| Architecture change | ~12,000 tokens | Index + task + architecture + SOPs |
| Full exploration | ~15,000 tokens | Index + multiple system docs |
If you consistently exceed 15k tokens in documentation, your index is too large or your docs need restructuring.
Anti-Patterns
| Anti-Pattern | Problem | Correct Approach |
|---|---|---|
| Inline everything in index | 150k tokens per session, exhausted in 5 exchanges | Link to detailed docs, keep index under 500 words |
| Skip task documentation | No context for future tasks, repeated discovery | Always create task docs with /nav-task |
| Ignore knowledge graph | Known pitfalls rediscovered, decisions forgotten | Let the context engine capture automatically, review monthly |
| Let context grow unbounded | Token efficiency drops below 50% after 10+ exchanges | Compact after each task with /nav-compact |
| Load all docs at session start | Wastes 40k+ tokens before any work begins | Use lazy loading — load on demand only |
| Large code blocks in docs | Each block costs 100-500 tokens every load | Reference file paths instead: see src/api/auth.ts:45 |
| Manual context markers | Inconsistent format, missed metadata | Use /nav-marker — auto-formats with timestamp and state |
| No architecture docs | Every task requires full codebase exploration | Write ARCHITECTURE.md once, update incrementally |
| Monolithic task docs | Single 2000-word task doc loaded for unrelated tasks | One file per task, archive when done |
| Skipping workflow check | Tasks jump to implementation without planning | The context engine enforces this — don’t override |
Project-Specific Tips
For Pilot Itself
Pilot’s own .agent/ directory follows these practices:
- Index (
DEVELOPMENT-README.md): ~520 words, includes component status table - System docs: Architecture, feature matrix, PR checklist — loaded on demand
- Task docs: One per GitHub issue, archived after merge
- Context markers: Created before major refactors (e.g.,
2026-01-26-1405_navigator-deep-integration-complete.md) - Loading budget: ~12k tokens including index + one task doc + feature matrix
This keeps Pilot’s autonomous execution under 12k tokens per session while maintaining full project awareness across 87+ implemented features.