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).
Task docs feed directly into GitHub issue bodies for Pilot. Before dispatch, the
issue spec guard requires at
least one recognized H2 header (Context, Acceptance, Implementation, …) and
dependencies written inline as Depends on: #N / Blocked by: #N — see
Issue Format.
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 when a task is archived. You can also
record one manually by adding a memory entry under .agent/ — it will be indexed into
the knowledge 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, write a
checkpoint file to .agent/.context-markers/ (format:
YYYY-MM-DD-HHMM_description.md) summarizing the current state and intent.
The next session resumes from it if the change goes wrong. Pilot creates
these automatically at execution checkpoints.
Compact After Each Task
After completing a task, clear the conversation context and start the next task in a fresh session. This preserves knowledge in the graph while freeing context window tokens. Without compaction, context accumulates and efficiency drops. Pilot does this by design — every autonomous execution starts clean and loads only the index plus the task at hand.
Loop Phases for Multi-Step Work
For tasks requiring iteration (implement → test → fix → test), Pilot engages the Navigator loop contract automatically: phases run Research → Implement → Verify with structured completion signals. It prevents premature task completion — see the execution pipeline.
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 a task doc in tasks/ before implementation |
| 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; start the next one in a fresh session |
| 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 |
| Free-form context markers | Inconsistent format, missed metadata | Follow the YYYY-MM-DD-HHMM_description.md marker format with state + intent |
| 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.