context-engineering

Files (4)

• SKILL.md
• __init__.py · scripts/
• render_semantic_context.py · scripts/
• semantic_context.py · scripts/

SKILL.md (first lines)

# Context Engineering

## Overview

Feed agents the right information at the right time. Context is the single biggest lever
for output quality — too little and the agent hallucinates, too much and it loses focus.
Context engineering is the practice of deliberately curating what the agent sees, when
it sees it, and how it is structured.

This skill is **orchestrator-loaded**, not a slash command. `plan-feature`,
`implement-feature`, `validate-feature`, and the parallel-review skills consult this
skill when assembling the context block they pass to a worker agent or sub-agent. It
encodes the conventions specific to this repo: OpenSpec proposals, `work-packages.yaml`
scopes, agent worktrees, and the coordinator handoff layer.

## When to Use

- Starting a new coding session, especially after `worktree.py setup`
- Agent output quality is declining (wrong patterns, hallucinated APIs, ignoring conventions)
- Switching between work packages (different `wp-*` IDs in the same change)
- Setting up a new project for AI-assisted development (rules file, references library)
- A worker is about to be dispatched and the orchestrator must decide what context to pack
- Cross-session handoff — sanitizing prior session logs before exposing them to a fresh worker

## The Context Hierarchy

Structure context from most persistent to most transient:

```
+-------------------------------------+
|  1. Rules Files (CLAUDE.md, etc.)   |  <- Always loaded, project-wide
+-------------------------------------+
|  2. Spec / Architecture Docs        |  <- Loaded per feature/session
+-------------------------------------+
|  3. Relevant Source Files           |  <- Loaded per task
+-------------------------------------+
|  4. Error Output / Test Results     |  <- Loaded per iteration
+-------------------------------------+
|  5. Conversation History            |  <- Accumulates, compacts
+-------------------------------------+
```

### Level 1: Rules Files

Create a rules file that persists across sessions. This is the highest-leverage context
you can provide.

**`CLAUDE.md` at the repo root** (loaded by the Claude Code harness on every turn):

```markdown
# Project: [Name]

## Tech Stack
- Python 3.12, uv, pytest
- TypeScript 5, Vite, React 18 (web app)

## Commands
- Test (Python, **source-contribution-only**): `skills/.venv/bin/python -m pytest skills/tests/`
- Test (Node): `npm test`
- Lint: `npm run lint --fix`
- Type check: `npx tsc --noEmit`

## Code Conventions
- Functional components with hooks (no class components)
- Named exports (no default exports)
- Colocate tests next to source: `Button.tsx` -> `Button.test.tsx`

## Boundaries
- Never commit `.env` files or secrets
- Ask before modifying database schema
- Always run tests before committing
```

**Equivalent files for other tools:**
- `.cursorrules` or `.cursor/rules/*.md` (Cursor)
- `.windsurfrules` (Windsurf)
- `.github/copilot-instructions.md` (GitHub Copilot)
- `AGENTS.md` (OpenAI Codex)

In this source repo, the canonical rules file is `CLAUDE.md` at the root. After
source-contribution-only edits, regenerate the runtime mirrors with the repository installer.

### Level 2: Specs and Architecture

Load the relevant spec section when starting a feature. Don't load the entire spec if
only one section applies.

In this repo, the per-feature specs live under `openspec/changes/<change-id>/`:

- `openspec/changes/<change-id>/proposal.md` — what we're building and why
- `openspec/changes/<change-id>/design.md` — design decisions (D1, D2, ...) and trade-offs
- `openspec/changes/<change-id>/work-packages.yaml` — scope, locks, verification per package
- `openspec/changes/<change-id>/specs/` — delta specs scoped per capability

**Effective:** "Here is the relevant section of `proposal.md` plus design decisions D2
and D4 that motivate this work package: [excerpt]"

**Wasteful:** "Here is the entire 5,000-word proposal." (when only one capability matters)

When the orchestrator dispatches a worker for a specific `wp-*` package, the context
block should include:

1. The package's own entry from `work-packages.yaml` (its `description`, `depends_on`,
   `scope`, `verification`, and `locks.reason`).
2. The matching design decisions referenced by that entry (e.g. "Design decisions: D2, D4").
3. The matching spec scenarios listed in the entry.

### Level 3: Relevant Source Files

Before editing a file, read it. Before implementing a pattern, find an existing example
in the codebase.

**Pre-task context loading:**

1. Read the file(s) you'll modify
2. Read related test files
3. Find one example of a similar pattern already in the codebase
4. Read any type definitions or interfaces involved

From jankneumann/agentic-coding-tools, MIT.

More from jankneumann/agentic-coding-tools