Specialist Context Ally

A context management agent that helps you maintain and leverage project context across development sessions, ensuring that relevant files, patterns, and decisions are always available when you need them.

When to Use This Agent

Choose Specialist Context Ally when:

• Setting up context files (CLAUDE.md, .context, .cursorrules) for a project
• Curating which files and patterns should be loaded into agent context windows
• Managing context across multiple related repositories or workspaces
• Optimizing context window usage by prioritizing the most relevant information
• Building project-specific knowledge bases for development agents

Consider alternatives when:

• Exploring a new codebase for the first time (use a codebase explorer agent)
• Writing specific features (use a development agent with context already loaded)
• Creating documentation for external users (use a documentation agent)

Quick Start

Copy
# .claude/agents/specialist-context-ally.yml
name: Specialist Context Ally
description: Manage and optimize project context for development agents
model: claude-sonnet
tools:
  - Read
  - Write
  - Edit
  - Glob
  - Grep

Example invocation:

claude "Create a CLAUDE.md context file for this project that captures the architecture, key patterns, and development conventions"

Core Concepts

Context Hierarchy

Level	File	Scope	Contents
Global	~/.claude/CLAUDE.md	All projects	User preferences, global conventions
Project	./CLAUDE.md	This project	Architecture, patterns, key files
Directory	./src/CLAUDE.md	This directory tree	Module-specific conventions
Agent	.claude/agents/*.yml	Per-agent	Agent-specific instructions

Context File Template

Copy
# Project Context: E-Commerce Platform

## Architecture
- Next.js 14 App Router with server components
- PostgreSQL via Drizzle ORM
- Redis for caching and sessions
- BullMQ for background jobs

## Key Files
- `src/lib/db/schema.ts` — Database schema (source of truth)
- `src/lib/auth/config.ts` — Auth configuration
- `src/server/actions/` — All mutations go here
- `src/components/ui/` — Shared UI primitives

## Conventions
- Server components by default, 'use client' only when needed
- Zod validation on all API inputs
- Error handling via Result<T, E> pattern (src/lib/result.ts)
- Tests colocated: `foo.ts` → `foo.test.ts`

## Current Work
- Migrating from Pages Router to App Router (70% complete)
- Do not modify files in src/pages/ — they are being deprecated

## Common Mistakes
- Do not import server-only modules in client components
- Always use `db.transaction()` for multi-table writes
- Cache invalidation must happen in the same server action as the mutation

Context Optimization Strategy

Copy
// Context budget allocation for a typical agent session
interface ContextBudget {
  systemPrompt: number;    // ~2,000 tokens — agent instructions
  projectContext: number;  // ~3,000 tokens — CLAUDE.md + conventions
  relevantFiles: number;   // ~15,000 tokens — files being modified
  referenceCode: number;   // ~5,000 tokens — patterns and examples
  conversationHistory: number; // ~10,000 tokens — prior turns
  workingBuffer: number;   // ~15,000 tokens — reasoning + generation
  // Total: ~50,000 tokens for a typical context window
}

Configuration

Parameter	Description	Default
context_format	Context file format (claude-md, cursorrules, custom)	claude-md
auto_discover	Auto-detect project patterns and conventions	true
max_context_size	Maximum context file size in tokens	3000
include_examples	Include code examples in context	true
track_changes	Update context when project patterns change	true
scope	Context scope (global, project, directory)	project

Best Practices

1. Keep context files under 3,000 tokens and focused on decisions, not descriptions. Long context files waste context window budget and dilute the most important information. Include architecture decisions ("we use X because Y"), key file locations, and conventions that are not obvious from the code. Do not describe what the code does — agents can read the code. Describe what the code should do and how.

2. Update context files when project conventions change. Stale context is worse than no context — it causes agents to follow outdated patterns. When the team adopts a new convention (switching from REST to tRPC, changing the test framework), update the context file in the same PR. Treat CLAUDE.md as a living document that evolves with the project.

3. Use directory-level context files for module-specific conventions. A top-level CLAUDE.md should not contain React component conventions alongside database migration patterns. Place a CLAUDE.md in src/components/ for UI conventions and another in src/server/ for backend patterns. Agents working in those directories automatically pick up the relevant context without loading unrelated information.

4. Include a "Common Mistakes" section with specific examples. The highest-value context prevents recurring errors. If developers (or agents) repeatedly import server modules in client components, or forget to invalidate caches after mutations, list these mistakes explicitly. Negative examples ("do NOT do X") are often more actionable than positive guidelines ("do Y") because they address the specific failure modes the team encounters.

5. Reference key files by path rather than duplicating their content. Instead of pasting the full database schema into the context file, write "Database schema: see src/lib/db/schema.ts." The agent will read the file when needed, and the schema is always up-to-date. Only inline content that is stable and not easily found: architecture decisions, naming conventions, and team agreements.

Common Issues

Context files grow too large and exceed useful density. Teams add information incrementally without removing outdated content, resulting in context files that consume significant context window space with diminishing value. Schedule quarterly reviews of context files. Remove anything the code itself makes obvious, anything that has changed, and anything that agents consistently ignore. If a context file exceeds 200 lines, it needs pruning.

Multiple context sources give conflicting instructions. A global CLAUDE.md says "use semicolons" while a project CLAUDE.md says "no semicolons." Define clear precedence: directory-level overrides project-level overrides global-level. Document this precedence in the global context file. When conflicts are discovered, resolve them by removing the less specific instruction rather than adding overrides.

Context is too generic to be actionable. Statements like "write clean code" or "follow best practices" waste context space without changing agent behavior. Every line in a context file should be specific enough that someone could verify compliance: "Use const over let unless reassignment is needed" is verifiable. "Write good variable names" is not. Replace generic advice with concrete rules and examples.