Macaron Context Engineering for Coding Agents

Macaron context engineering means giving a coding-agent workflow a small, current, and accountable evidence set before it edits a repository. Start with the task boundary and architecture rules, add the dependency and test paths that matter, let the agent inspect current source, then require human review and verification. Do not assume a model, context window, HCP file, or agent session automatically becomes durable repository memory.

Mind Lab’s Macaron-V1 release introduces Harness Context Protocol (HCP) as a configuration standard for agent harness settings such as AGENTS.md, Skills, hooks, system instructions, and provider configuration. The official HCP SDK is explicit about its limit: it is wrapper-only and does not implement an agent by itself. That is a useful boundary. Configuration can make context repeatable, but the team still owns repository facts, freshness, permissions, and acceptance of a change.

Before You Give Macaron a Coding Task

Do not begin with “read the whole repo and fix it.” Begin by making the task inspectable.

Every coding-agent request should establish:

• Objective: the behavior to change and the acceptance criteria;
• Repository anchor: branch, commit, workspace, package, and allowed write paths;
• Authority: applicable AGENTS.md, architecture decision records, security or API owners, and deployment restrictions;
• Evidence: current source, relevant tests, configuration, incident data, and an explanation of why each item belongs in scope;
• Risk boundary: public compatibility, data handling, generated artifacts, migrations, feature flags, and external consumers;
• Verification: commands, environments, reviewers, and rollback conditions.

This is not paperwork for its own sake. A model can produce a plausible patch from incomplete context. The missing information is often exactly what makes a repository change risky: an internal API that is public in a plugin, a generated client with a separate source-of-truth, or a feature flag that alters behavior outside the code currently open.

The Macaron-V1-Coding-Venti model card positions the checkpoint for code understanding, repository-level software engineering, terminal use, and coding-agent workflows. Use that as a reason to run disciplined repository trials, not as permission to skip scope control. The companion Macaron-V1 large-codebase guide shows how to test architecture and dependency awareness before trusting a wider workflow.

Prepare Architecture and Dependency Context

Architecture context should answer questions that filenames cannot: where the public boundary is, which package owns it, what data or API contract is involved, and which decisions constrain the work.

Keep stable guidance in reviewed files. A root AGENTS.md can point to required build and test commands, generated-code policy, ownership, and links to architecture records. Store detailed procedures as Skills instead of putting all instructions into every agent session. The important rule is that the information has a source, an owner, and a refresh path.

Then create a task-specific evidence packet. It may include:

Evidence type	What to include	Why it matters
Architectural boundary	package overview, API contract, decision record, owner	Prevents an edit from violating a hidden system constraint
Dependency path	callers, imports, schemas, code generation, configuration, feature flags	Makes indirect impact visible before a patch
Test signals	focused unit/contract/integration tests, known regressions, fixtures	Ties a proposed behavior to observable verification
Operational evidence	logs, telemetry, environment assumptions, deployment sequence	Separates source-only theory from runtime reality
Unknowns	dynamic registration, external clients, incomplete extraction, stale docs	Gives the agent permission to escalate instead of inventing certainty

Use a graph or other approved index when the task needs multi-hop structure. A graph can locate candidate callers, tests, ownership, and documents more quickly than repeatedly scanning a large repository. It should label the commit, edge provenance, and refresh time. The agent must open the files behind high-impact results before planning an edit.

This is why context engineering is not a prompt-collection exercise. A list of clever instructions cannot replace a dependency map, and a dependency map cannot decide which contract the team is willing to change. The layers need to cooperate without duplicating one another.

Add Historical Decisions and Test Signals

Repository context gets stronger when it preserves decisions, not just files. A current code path may show what happens but not why a boundary exists, which compatibility promise matters, or which failed migration led to a guardrail.

Capture durable historical information in reviewed artifacts: architecture decision records, interface contracts, incident follow-ups, migration plans, and changelog entries. Link them from stable instructions or a graph relationship rather than pasting large histories into a model prompt. For a current task, select only the decisions that constrain the requested change.

Test signals deserve equal treatment. Include the tests most likely to falsify the proposed plan, not only the easiest commands to run. For example:

• a schema change should include generated-client and contract checks;
• an authorization edit should include denied-path and session-expiry behavior;
• a queue change should include retries, idempotency, and state transitions;
• a package split should include import, build, and release-boundary checks.

Mark the difference between a passing test and proof of behavior. A narrow unit test can pass while a deployment-specific configuration remains wrong. Conversely, a failing integration test can reflect a fixture or environment issue unrelated to the code change. The agent should explain what each test establishes and what it leaves unverified.

Macaron’s official MoL harness keeps per-adapter context and short cross-adapter summaries in its proxy. That is a serving mechanism, not a general guarantee that your repository’s decisions will persist correctly across projects, sessions, providers, or deployments. Keep team knowledge in versioned, reviewable artifacts; treat session summaries as working state that must be checked before reuse.

Query Context Before Multi-File Edits

Before a multi-file edit, run a read-only planning pass. The goal is to convert broad context into a small evidence-backed plan.

1. Confirm the task contract, base commit, and allowed write scope.
2. Read the relevant project rules and named architecture records.
3. Search or traverse the direct and multi-hop dependencies of the target symbol or behavior.
4. Open current source, configuration, and tests behind important relationships.
5. List confirmed facts, inferred paths, and unknown external or dynamic behavior separately.
6. Propose the smallest viable edit, expected tests, rollback point, and responsible reviewer.
7. Only then grant write access for the approved scope.

This sequence is compatible with HCP-style configuration without depending on a particular runtime. HCP can express Skills, embedded resources, MCP configuration, hooks, workspace staging, provider settings, and context-window settings. The public SDK delegates runtime materialization to pi-hcp; it does not itself create an autonomous coding agent. If your stack differs, preserve the same logical separation rather than copying its syntax blindly.

When using Macaron-V1-Coding-Venti, test the actual provider or self-hosted deployment. The model card specifies a 1M context architecture, while the official MoL harness reference profiles use 262K. That gap reinforces a basic operating rule: include a measurable context budget in every experiment and never infer effective repository recall from a model-card limit.

Limits, Drift, and Human Review

Context can become wrong in several independent ways.

Risk	Early signal	Control
Stale instructions	command or ownership reference no longer matches the repository	Review instruction changes with code and link them to owners
Stale structural evidence	graph path points to renamed or generated code	Pin the indexed commit, refresh after structural change, verify source
Session drift	a prior summary omits a constraint or carries an old assumption	Treat session notes as leads; reload evidence for each high-risk task
Context overload	important source is diluted by broad instructions, logs, or tool descriptions	Select a bounded packet and enable only needed tools
Authority confusion	model treats a comment, document, or inferred edge as policy	Declare source priority and route policy changes to human owners
Unreviewed broad diff	a local fix touches public contracts or unrelated packages	Limit write scope, require diff inspection, tests, and accountable review

Let context expire according to its type. A task packet expires when the task closes or its base commit changes. Generated structural facts expire when source changes. Operational evidence may expire with an incident or deployment. Stable policies should change only through review, but still need periodic ownership checks. This approach avoids a single permanent “memory” file accumulating stale facts, secrets, and abandoned hypotheses.

Human review remains the decision boundary for security, data, public APIs, migration order, and deployments. The review should examine not only the final diff but also the dependency path, source evidence, test plan, and unresolved unknowns. A coding agent can compress discovery work; it cannot eliminate the team’s accountability for change.

FAQ

What context should expire first?

Expire task-local notes, logs, investigation hypotheses, and selected file lists first. They are tied to a commit and a narrow objective. Refresh graph results after relevant structural changes. Keep architecture decisions and stable procedures longer, but review their owners and links rather than treating age as accuracy.

Who should review generated repository notes?

The team that runs the index or documentation pipeline owns its mechanics and freshness. Package owners should review high-impact structural claims; security, data, API, and release owners should review decisions in their domains. The task owner must verify that generated notes match current source before relying on them for an edit.

How much context is too much?

Context is too much when it obscures the task boundary, leaves no room for current evidence, increases latency or cost without improving coverage, or prevents a reviewer from seeing why each source was included. Measure effective evidence coverage and correction rate, not prompt size alone.

Conclusion

Macaron context engineering is a discipline for making coding-agent work reviewable. Give the model a scoped task, current architecture and dependency evidence, relevant decisions, and tests; let it inspect source before it edits; then make humans and verification the authority for high-risk changes.

HCP and agent harnesses can standardize how that context is assembled. They do not remove drift, turn summaries into durable repository truth, or automatically prove a multi-file edit is safe. Keep each layer owned, revision-bound, and auditable.