Professional Agentic Product Engineering

Tier 3

Tier 3 — Context Management: Give the agent the right context and tools, so it stops guessing

Reach for this tier when you re-explain the same conventions every session, or the agent can't see your DB, browser, or docs. Engineer that context once — durable project memory plus the right tools — and it stops re-asking and guessing.

The mental model under this whole tier: context is a finite budget with diminishing returns. As the window fills, the model's recall degrades — Anthropic names this context rot. So the job isn't to load everything (even at 1M); it's to find the smallest set of high-signal tokens that gets the result. Every tip below spends that budget: load just-in-time over pre-loading, /clear between tasks, compact deliberately, and push heavy exploration to subagents whose context stays isolated (Tier 6). Check usage any time with /context.

23. Feed high-signal context, not the whole repo.

Instead of: "Here's the entire codebase." (even at 1M tokens)

Prefer: just the affected modules + relevant docs, loaded just-in-time.

24. Keep secrets out of git and out of context — set this up first.

Instead of: real keys in the repo, or pasted into a prompt.

Prefer: .env gitignored and referenced by variable, enforced with a hook.

A coding agent reads your whole tree and everything you paste; both leak.

How:

  • Gitignore secrets before anything else. Real values in .env; add .env (plus .env.local, *.pem, *.key) to .gitignore — so neither git, a PR, nor the agent's own commits ever carry them. Commit a .env.example with blank keys as the shape to follow.
  • Never paste a key into a prompt — it lands in the transcript, the logs, and the context window. Reference it by variable (process.env.STRIPE_KEY); the app reads it at runtime.
  • Enforce it, don't just trust it: a PreToolUse guard hook that blocks any read or write of .env — the layer the model can't talk its way past.
  • Privacy boundary: code routed to a third-party model or gateway leaves Anthropic's trust boundary into that provider's data handling — keep sensitive code on Anthropic or your own infra (Level 2).

25. /clear between tasks; reset after repeated failure.

Instead of: one session for five unrelated tasks, then fixing the same bug four times.

Prefer: /clear between tasks; after ~2 failed fixes, /clear and rewrite the opening prompt.

26. Steer compaction, don't run it blind.

Instead of: "/compact"

Prefer: "/compact keep the data-model decisions and the failing-test list; drop the exploration."

27. CLAUDE.md = gotchas + conventions, not an encyclopedia.

Instead of: a 500-line style manual.

Prefer: architecture, key commands, forbidden patterns, and the mistakes it keeps repeating — pruned often.

How: keep it short; subdirectory CLAUDE.md files for local rules; point to docs rather than pasting them:

For the payment flow, see docs/payments.md.
NOTE: src/legacy/* is deprecated — use src/v2/* equivalents.

28. Put occasional knowledge in Skills — loaded only when the task matches.

Instead of: cramming the migration protocol into CLAUDE.md.

Prefer: a Skill that auto-loads only when the task matches its description.

How: .claude/skills/db-migration/SKILL.md — a folder, so it can carry scripts too:

---
name: db-migration
description: Use when creating or altering database schema or writing migrations.
---
# Migration protocol
- New file in /migrations; never edit an applied one.
- Run `npm run migrate:make <name>`; then fill up/down.

29. Add the right MCP servers; keep the surface small.

Instead of: copy-pasting data in and out by hand, or wiring 30 thin tools.

Prefer: connect a few high-value MCP servers (browser, DB, issue tracker) and let Claude use them directly.

How: add one, scope it to the project so the team shares it:

claude mcp add playwright --scope project npx @playwright/mcp@latest
claude mcp list   # confirm "connected"

Or commit .mcp.json to the repo root:

{ "mcpServers": {
  "playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@latest"] }
} }

>~20k tokens of MCP definitions already eats your working context. Few powerful gateway tools beat many thin REST mirrors.

30. Use external memory for multi-session work — compaction won't carry decisions across sessions.

Instead of: trusting compaction to carry decisions across sessions.

Prefer: write STATUS.md at session end; reload it at the next session's start.