01 / 43
Akt I

Context is an
architecture decision

After a few turns

The real question arrives
inside old noise

Turn 15
The stack is heavy
systemCLAUDE.md + MCP schemas
useranalyze CatalogService
toolread, grep, test x12
toolCI build/test output
usercan we migrate this?

Question got harder

Migration judgment now depends on what the context kept, lost and overemphasized.

Next move: measure

Before more analysis, ask what is already occupying the window.

/context moment

The budget is
already spent

/context
System prompt3.3K
System tools16.9K
MCP tools49.1K
Skills305
Messages8
Free space40.9%
Tool definitions can be the biggest file in the room

Before the agent reads CatalogService, it may already carry thousands of tokens of unused capability.

Context sources

The prompt is only
the visible layer

S

System prompt

Role, permissions, policies, injected product behavior.

T

MCP tool contracts

Schemas and descriptions loaded before a tool is ever called.

F

Files and artifacts

Code, docs, tests, configs, generated reports, and diagrams.

R

Tool results

Search output, logs, compiler failures, and static-analysis findings.

M

Memory

Project facts, preferences, summaries, previous decisions.

A

Agent messages

Plans, assumptions, mistakes, corrections, and user feedback.

Tooling trap

MCP sprawl
becomes context debt

$ claude mcp list |-- repo-search source access |-- architecture-maps diagram generation |-- jira ownership and scope |-- observability runtime evidence |-- dependency-scanner risk signals |-- test-runner verification `-- + many more...

Unused tool contracts spend attention before the first dependency is inspected.

Token budget

Tool contracts have
a context price

System prompt
~4K
MCP tool defs
~10K
CatalogService
~15K
Test output
~3K
Skill metadata
~50

Budget context like architecture.

Context Rot

Context Rot hurts
migration judgment

accuracy irrelevant context clean crowded
89 → 38

Noise competes with dependencies, invariants, and test signals.

Inspired by Chroma Context Rot research

Auto-compact trigger

The main context
fills up

Main Context before compact
System PromptClaude Code + MCP schemas
User Goalanalyze CatalogService
Skillrisk assessment workflow
Tool Resultread CatalogService.cs
Tool Resultgrep SaveChanges HiLo
...
Context almost full

Attention gets crowded

Useful evidence sits next to old plans, logs and unused tool schemas.

The model still answers

The risk is not silence. The risk is confident synthesis from blurred evidence.

Auto-compact trade-off

A summary is
not the evidence

After compact
System PromptClaude Code + MCP schemas
Compact SummaryArchitecture, risk and tests in compressed form
...
Tool Resultwrite risk-table.md
New evidence has room again

What improves

The session gets space for fresh code, tests and owner input.

What can vanish

Uncertainty, minority findings and exact references may be compressed away.

Fresh windows

Give noisy work
a fresh window

Main Context
PlanArchitecture, risk, tests
Taskarchitecture.extract()
Wait for evidence contract
->
Subagent Context
Taskextract boundaries
Tool Resultread 18 files
Tool Resultdependency graph
...
Artifactarchitecture-map.md

Return contract

Back comes an
Evidence Contract

01

Finding

Boundaries, risks and test gaps in one short claim.

02

References

Files, commands and snippets that support the claim.

03

Confidence

How strong the evidence is, and what is missing.

04

Artifact

Architecture Map, Risk Table or Test-Gap Report.

Raw noise stays out. Reviewable evidence comes back.

Bridge

Before orchestration
evidence hygiene

Clean context is better architecture.

Right evidence. Right time. Reviewable output.

Context hygiene

Clean context
improves decisions

Clean evidence flow
less duplication

Deduplicate evidence

One fact, one source.

less noise

Compact outputs

Findings, severity, references.

more review

Return typed artifacts

Architecture Map, Risk Table, Test-Gap Report.

Operating loop

Context control
is a workflow

01

Measure

Check budget before long analysis.

02

Route

Load tools, files and skills only when needed.

03

Compress

Return artifacts, references and open questions.

The harness exists to make this loop repeatable.

Akt II

From prompt
to agent harness

Pattern map

Analysis harness
components

Runtime

Agent

Executes the inspect, reason, act, verify loop.

Control

Harness

Defines permissions, context policy, logging, memory, and review gates.

Tools

MCP Gateway

Catalog, isolation and policy for tools; context efficiency depends on how the harness loads them.

Knowledge

Skills

Package reusable procedures for risk assessment, extraction, and verification.

Delegation

Subagents

Run bounded tasks in fresh context windows.

Gates

Hooks

Trigger tests, scans, and owner-review checks around risky actions.

Orchestrator

Orchestrator protects
the main context

Plan

Decompose

Architecture, risk, tests, migration path.

Route

Choose context

Select tools, skills, files, and subagents.

Synth

Merge artifacts

One recommendation with confidence and gaps.

Skill example

A Skill is
a migration checklist

name: legacy-risk-assessment
when: analyzing migration candidates
steps:
  1. map dependencies
  2. identify business invariants
  3. score risk and confidence
  4. produce review gates
outputs: architecture-map.md, risk-table.md, test-gaps.md

The skill carries steps and expected outputs.

Subagent design

Collaboration beats
blind delegation

Delegation

A
?
  • Good for independent scans
  • Risky for planning decisions
  • Can guess without user input

Collaboration

U
✓
  • Human-in-the-loop for key calls
  • Validated architecture choices
  • Main context keeps the decision story

Scaling pattern

Do not load it all
route the work

01

Legacy codebase

->
02

Chunk by decision

Architecture boundaries
Runtime risk
Missing tests

No full-codebase dump into the main Context Window.

Aggregation pattern

Parallel agents
keep main context clean

03
architecture
dependencies
test gaps
risk

Specialists read deeply

->
04

Evidence comes back

Relevant snippets, citations and open questions.

The main context keeps the decision story, not every raw tool result.

Akt III

CatalogService as
agent workflow

A/B result

Reading code
is not enough

No harness
Harness
Syntax and local control flow
OK
OK
The model can parse code.
Architecture boundaries
weak
strong
Needs dependency evidence.
Runtime and ownership risk
missed
captured
Needs runtime and owner signals.
Migration decision package
no
yes
Needs gates and review.

Anti-patterns

Stop making
the prompt bigger

01

Everything up front

Repo dumps, tool dumps and “just in case” docs crowd the decision.

02

Instructions as controls

“Be careful” is weaker than tests, scans and owner review.

03

Summaries without sources

A clean paragraph is not evidence unless it points back to code.