agent-engineering-handbook/rules/015-context-engineering.mdc at main · d-padmanabhan/agent-engineering-handbook · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
---
title: Context Engineering for Coding Agents
description: Prompt packing, retrieval, and compaction patterns for reliable agent work.
alwaysApply: true
priority: 15
---

# Context Engineering for Coding Agents

This rule strengthens agent performance by making context **intentional**, **minimal**, and **reproducible**.

> [!NOTE]
> This rule complements `010-workflow.mdc` (phases + context files) and `100-core.mdc` (anti-slop guardrails).

---

## Goals

- Keep the agent’s working context small and high-signal
- Make work resumable across sessions without “reloading the world”
- Prefer retrieval over memory: fetch exactly what you need, when you need it

---

## Mental Model: Three Layers of Context

- **Working context (volatile)**: what the model sees right now
- **Repo context (retrievable)**: files, diffs, logs, docs that can be re-read on demand
- **Durable context (portable)**: short summaries + decisions captured in `tmp/` context files

> [!IMPORTANT]
> If it’s important and will matter later, it must be captured in **durable context**.

---

## Prompt Packing (What to Carry vs. What to Fetch)

### Always carry (paste/recap)

- **Goal**: one sentence
- **Non-goals**: 1-3 bullets
- **Constraints**: security, tooling, performance, “don’t refactor”, etc.
- **Current plan**: 3-7 steps max
- **Current state**: what’s done / what’s blocked
- **Critical artifacts**: exact file paths, key identifiers, and error messages (verbatim)

### Never carry (fetch instead)

- Entire files or long logs “just in case”
- Repeated restatements of requirements
- Unbounded command output without a reason

---

## Retrieval Strategy (Search → Read Narrow → Cite)

Use a tight loop:

1. **Search** for the smallest set of candidate files (prefer repo-local sources first)
2. **Read** only the minimal sections needed to decide or implement
3. **Cite** exact file paths / relevant snippets in your reasoning and updates

> [!TIP]
> Prefer “retrieve just-in-time” over “load everything up-front”. It is faster and more accurate.

---

## Compaction Strategy (Frequent Intentional Compaction)

After any meaningful milestone (plan approved, a module completed, a bug fixed), compact:

- Update `tmp/active-context.md` with:
  - **Current focus**
  - **Key decisions** (what and why)
  - **Blockers** (and next action)
  - **Context from previous sessions** (only what must persist)
- Update `tmp/progress.md` (if used) with “done/next”
- Add a **Handoff Bundle** (copy/pasteable) for resuming work

### Handoff Bundle (copy/paste)

```text
Goal:
Non-goals:
Constraints:
Current state:
Next 3 actions:
Key files/paths:
Key commands + outputs (verbatim, minimal):
```

---

## Context Reset Triggers (Start Fresh on Purpose)

Prefer a fresh chat/session when:

- Plan is approved and you’re moving into implementation (see `010-workflow.mdc`)
- The conversation has accumulated long tool output or multiple competing threads
- You are switching to a new, independent task

When restarting, bring only:

- The approved plan (or the updated `tmp/tasks.md`)
- The Handoff Bundle
- The minimal file/line references needed to continue

---

## Guardrails (Quality + Security)

- Follow `100-core.mdc` anti-slop rules: be minimal, anchored, specific
- Never paste secrets into context; redact tokens/keys/passwords
- Prefer deterministic artifacts: file paths, commands, exit codes, and diffs