# Context Engineering Checklist *Ensure your AI agents have the right knowledge at the right time.* Context engineering is the practice of curating and delivering knowledge to AI agents so they make informed decisions. This checklist covers the full spectrum of context engineering, from basic documentation to dynamic context pipelines. --- ## Level 1: Static Context Foundations ### Knowledge base structure - [ ] **Project overview exists** in the agent config file (AGENTS.md / .github/copilot-instructions.md / etc.) - [ ] **Architecture documentation** describes the system structure at a level an agent can act on - [ ] **Directory guide** explains what each top-level directory contains and its purpose - [ ] **Technology choices** are listed with brief rationale (e.g., "Azure SQL Database for managed PaaS + geo-replication") - [ ] **External dependencies** are documented (third-party APIs, services, databases) ### Code-level documentation - [ ] **Public APIs have docstrings/JSDoc** explaining purpose, parameters, and return values - [ ] **Complex algorithms have inline comments** explaining the "why," not the "what" - [ ] **Non-obvious patterns have explanatory comments** (e.g., "We do X because of Y limitation") - [ ] **TODO/FIXME comments** include enough context for an agent to understand the issue - [ ] **Type definitions** serve as documentation (well-named types, interfaces, enums) ### Conventions documentation - [ ] **Naming conventions** are explicit with examples for each code construct - [ ] **File organization patterns** are documented (where does new code go?) - [ ] **Error handling patterns** are shown with working code examples - [ ] **Test writing patterns** are demonstrated with a complete test example - [ ] **API design patterns** are documented (request/response shapes, status codes, pagination) **Checkpoint:** Ask yourself -- if an agent read only your documentation (no code), could it make correct architectural decisions for a new feature? --- ## Level 2: Progressive Disclosure Progressive disclosure means the agent gets minimal context by default and can access deeper context on demand. This prevents context window overload. ### Layered documentation structure - [ ] **Root config file** contains only essential, always-relevant information (< 200 lines) - [ ] **Subdirectory config files** contain area-specific details (e.g., `api/.github/copilot-instructions.md`, `frontend/.github/copilot-instructions.md`) - [ ] **Deep reference docs** exist for complex subsystems but are not loaded by default - [ ] **The agent knows where to find more context** (config file lists paths to detailed docs) ### Information hierarchy - [ ] **Layer 1 (always loaded):** Project overview, commands, top rules, architecture summary - [ ] **Layer 2 (loaded when working in an area):** Module-specific conventions, local patterns - [ ] **Layer 3 (loaded on demand):** API specifications, database schemas, integration details - [ ] **Layer 4 (agent queries as needed):** Historical decisions (ADRs), troubleshooting guides ### Scoped rules - [ ] **Repo-wide rules** live in `.github/copilot-instructions.md` and apply to every Copilot Chat request. - [ ] **Scoped rules** live in `.github/instructions/*.instructions.md` with `applyTo` globs that activate only when matching files are in context. - [ ] **File-type rules** apply to specific file types (e.g., different rules for tests vs production code) via separate scoped instruction files. **Checkpoint:** Is the root config file under 200 lines? If it's longer, are there items that could move to subdirectory files or reference docs? --- ## Level 3: Dynamic Context Sources Dynamic context is information that changes or is generated at runtime, not stored statically in config files. ### Build and runtime context - [ ] **Current branch and recent commits** are available to the agent (most tools provide this) - [ ] **Test results** from the last run are accessible (not just pass/fail, but output details) - [ ] **Lint/type check output** is available for the agent to interpret - [ ] **Build logs** for the last failed build are accessible ### External data sources - [ ] **Issue tracker context:** The agent can access the relevant issue/ticket for the current task - [ ] **PR comments:** The agent can read review feedback on the current PR - [ ] **Monitoring data:** The agent can access error logs or performance metrics (read-only) - [ ] **API documentation:** The agent can query API specs for external services ### MCP servers (for tools that support them) - [ ] **Documentation MCP:** Agent can query internal documentation systems - [ ] **Database schema MCP:** Agent can inspect database structure (read-only) - [ ] **Issue tracker MCP:** Agent can read and create issues - [ ] **Search MCP:** Agent can search the codebase beyond what's in the current context window ### Context assembly - [ ] **Task-relevant context is identified** before the agent starts (what docs/code does this task need?) - [ ] **Irrelevant context is excluded** (large files, generated code, vendor directories are gitignored or excluded) - [ ] **Context budget is managed** (total context stays within the tool's effective window) **Checkpoint:** For a typical task, does the agent have access to all the information it needs without manually pasting content into the prompt? --- ## Level 4: Context Window Management The context window is finite. Managing it well is critical for agent performance. ### Context window efficiency - [ ] **Agent config file is concise** -- no unnecessary prose, every line earns its place - [ ] **Code examples in config are minimal** -- just enough to show the pattern, not full implementations - [ ] **Irrelevant files are excluded** from agent context: - [ ] `node_modules/`, `venv/`, `.venv/` etc. - [ ] Build output directories (`dist/`, `build/`, `.next/`) - [ ] Generated files (lockfiles, bundled assets) - [ ] Large data files (fixtures, seeds, migrations history) - [ ] **`.gitignore` is comprehensive** (most tools use it to exclude files from context) - [ ] **Repo-scoped ignore files exist where appropriate** (e.g., `.gitignore` excludes generated artifacts so Copilot does not load them as context). ### Context prioritization - [ ] **Most important rules are listed first** in the config file (models pay more attention to early content) - [ ] **Critical constraints use strong language** ("NEVER," "ALWAYS," "MUST") to signal importance - [ ] **Examples are placed near their rules** so the agent sees them in context - [ ] **Outdated information is removed** rather than commented out ### Large codebase strategies - [ ] **Repository map or index** exists for agents to understand the overall structure quickly - [ ] **Key files are identified** -- a list of the 10-20 most important files for understanding the project - [ ] **Module documentation** summarizes each major module in 5-10 lines - [ ] **Cross-references** connect related modules ("For the API client this service calls, see `lib/api-client.ts`") **Checkpoint:** Run a task with your agent and check whether it requested information it should have already had, or whether it was overwhelmed by irrelevant context. --- ## Level 5: Documentation Freshness Stale context is worse than no context because the agent follows it confidently. ### Freshness tracking - [ ] **Config file includes a "last updated" date** or is tracked via git blame - [ ] **Architecture docs are reviewed when architecture changes** (part of the PR checklist) - [ ] **Command sections are verified quarterly** (do all listed commands still work?) - [ ] **Convention sections are reviewed when conventions change** (part of team discussions) ### Staleness detection - [ ] **CI check for doc freshness** -- flag documentation files not updated in 90+ days - [ ] **Post-merge hook** -- remind to update docs when key files change (e.g., if EF Core migrations or `*.csproj` package references change, flag `docs/database-schema.md` / `docs/dependencies.md`) - [ ] **Quarterly audit** -- team reviews all documentation for accuracy ### Update triggers - [ ] **New dependency added** --> update technology section - [ ] **Architecture change** --> update architecture docs and config file - [ ] **New convention agreed** --> update conventions section - [ ] **Convention changed** --> update AND remove the old convention - [ ] **Module added or removed** --> update directory guide - [ ] **Command changed** --> update commands section (test that the old command no longer works) **Checkpoint:** Pick 3 random facts from your config file. Are they all still true? --- ## Level 6: Feedback Loop The context engineering process should improve continuously based on agent performance. ### Observation process - [ ] **Agent mistakes are logged** with the category of mistake (context gap, stale info, missing pattern, etc.) - [ ] **Recurring mistakes trigger config updates** within 1 week - [ ] **Successful patterns are documented** so they can be replicated ### Measurement - [ ] **Agent success rate is tracked** (tasks completed correctly on first attempt) - [ ] **Context-related failures are categorized:** - [ ] Missing information (the agent didn't know something it needed to know) - [ ] Stale information (the agent followed outdated instructions) - [ ] Conflicting information (two sources gave different answers) - [ ] Information overload (too much context, agent missed what mattered) - [ ] **Improvements are correlated with outcomes** (did adding rule X reduce mistake category Y?) ### Iteration cadence - [ ] **Weekly:** Review mistake log, update config file with new rules or context - [ ] **Monthly:** Audit documentation freshness, remove outdated content - [ ] **Quarterly:** Review overall context strategy, assess whether progressive disclosure is working **Checkpoint:** When was the last time you updated your agent config file based on an observed mistake? If it was more than 2 weeks ago, your feedback loop may be stalled. --- ## Quick Assessment Count your checked items across all levels: | Level | Your Score | Maximum | Priority | |-------|-----------|---------|----------| | 1: Static foundations | ___ | 15 | Must have | | 2: Progressive disclosure | ___ | 7 | Important for large projects | | 3: Dynamic sources | ___ | 12 | Important for complex workflows | | 4: Context window management | ___ | 12 | Important for all projects | | 5: Documentation freshness | ___ | 9 | Critical for ongoing effectiveness | | 6: Feedback loop | ___ | 9 | Critical for improvement | | **Total** | **___** | **64** | | **Interpretation:** - **50+:** Excellent context engineering. You're getting maximum value from your agents. - **35-49:** Good foundation. Focus on the levels where you scored lowest. - **20-34:** Significant room for improvement. Prioritize Level 1 and Level 5. - **Below 20:** Start with Level 1 basics. Each item you complete will noticeably improve agent output.