ADR-006: Task files + cascading context for AI agents
Context
Aucert uses AI agents extensively for development. Agents need structured context to work effectively — knowing which files to read, what conventions to follow, and what constraints apply. Without a system, agents either load too much context (wasting tokens) or too little (making uninformed decisions).
The codebase is polyglot and spans backend, frontend, ML, infrastructure, and documentation. An agent working on a React component doesn't need Terraform details. An agent working on database migrations doesn't need frontend conventions.
Decision
Implement a three-level cascading context system combined with task files for work orchestration:
Cascading context:
- L1 (
.context/): 6 small files (~3000 tokens total) loaded for every task — architecture, conventions, glossary, tech stack, AI rules, cloud summary - L2 (
{platform}/.context/): Platform-specific files loaded only when working in that platform - L3 (
{feature}/spec/): Feature/module specs loaded only for the specific work
Task files:
.tasks/backlog/→.tasks/drafts/→.tasks/active/→.tasks/done/- Each task file specifies
context_load:listing which L2/L3 files the agent should load - Spec-driven development: plan first, then build
Alternatives considered
| Option | Pros | Cons |
|---|---|---|
| Cascading context + task files (chosen) | Minimal token usage, agents load only relevant context, structured workflow | More files to maintain, overhead for small tasks |
| Single large context file | Simple, one file to read | Too many tokens for every task, agents get confused by irrelevant context |
| No context files (rely on code reading) | Zero maintenance | Agents spend tokens reading code to derive context that could be stated upfront |
| Wiki/Notion-based context | Rich editing, collaborative | Not co-located with code, stale quickly, requires API integration for agents |
Consequences
What becomes easier
- Agents work efficiently: load 3000 tokens of L1, plus only the L2/L3 files they need
- Context files are version-controlled alongside code — never stale if CI enforces updates
- Task files provide a clear audit trail of what work was planned and executed
- New team members (human or agent) can onboard by reading L1 → L2 → L3
What becomes harder
- Context files must be maintained — CI drift check (
.github/workflows/context-drift-check.yml) enforces this - Task file workflow adds ceremony for small changes (mitigated by allowing plan-in-conversation for sub-1h tasks)
- Risk of context files diverging from reality if CI checks are bypassed