paulund/context-engineering

Core Workflow

1. Discover context sources — search for these in order:

   • AGENTS.md (repo root) — agent guidance, conventions, known decisions
   • CONTEXT.md (repo root) — project glossary and domain vocabulary
   • CONTEXT-MAP.md (repo root) — bounded context locations
   • docs/adr/ — architecture decisions
   • docs/architecture.md — system architecture overview
   • README.md — project purpose and setup

2. Load relevant context — read files that touch the work at hand. Don't read everything — only what's relevant to the current task.

3. Identify missing context — if the task exposes domain terms not in CONTEXT.md or decisions not in ADRs, flag them. Don't create files for absent context — only when something concrete needs writing.

4. Feed context at the right time — present context before it's needed, not after. Load architecture context before proposing modules, load glossary before writing issue bodies.

Context Hierarchy

Session-level (always):
  AGENTS.md — conventions, preferences, operating behaviors

Task-level (when relevant):
  CONTEXT.md / CONTEXT-MAP.md — domain vocabulary
  docs/adr/ — architectural decisions
  docs/architecture.md — system overview

Decision-level (when needed):
  Relevant source files — existing patterns, prior art
  Related PRs — what changed and why
  Related issues — discussions and decisions

Common Rationalizations

| Rationalization | Reality | |---|---| | "I already know this codebase" | Your training data doesn't include this project's AGENTS.md or ADRs. Read them. | | "I'll read the context when I need it" | By then you've already made assumptions that may be wrong. Load context upfront. | | "This project doesn't have docs, so I'll guess" | If docs are missing, the code is the source of truth. Read it before guessing. | | "I don't want to overwhelm with too much context" | Load what's relevant to the task, not everything. Hierarchical loading solves this. |

Red Flags

• [ ] You're making assumptions about project conventions without reading AGENTS.md
• [ ] You're using domain terms that aren't defined in any project glossary
• [ ] You're proposing architecture that contradicts existing patterns
• [ ] You're making decisions that should be ADRs but aren't
• [ ] You're writing code without understanding the existing seam structure

Verification

• [ ] AGENTS.md loaded (if it exists)
• [ ] Relevant CONTEXT.md and ADRs loaded (if they exist)
• [ ] Missing context identified and flagged
• [ ] No domain terms used without definition
• [ ] No architecture proposed that contradicts existing patterns

Constraints

MUST DO

• Search for AGENTS.md, CONTEXT.md, and docs/adr/ before starting any non-trivial work.
• Load context hierarchically — session → task → decision level.
• Flag missing domain vocabulary or undocumented decisions.

MUST NOT DO

• Skip context discovery to "save time" — wrong context causes rework.
• Create CONTEXT.md or ADR files proactively — only when there's something concrete to write.
• Load all context files for every task — load only what's relevant.
• Guess project conventions — read them or derive from code.