Author: Evan

Supacode Large Codebase Worktrees
A Supacode large-codebase workflow can isolate each coding task in a real Git worktree, but the worktree does not explain architecture, call paths, design intent, or cross-module dependencies. Give every agent a narrow branch and directory plus a revision-bound repository evidence packet, then verify its plan against current source and tests.

This guidance reflects Supacode’s documented boundary as of July 23, 2026. Supacode v0.10.6 is a macOS worktree command center with per-worktree terminal state and reusable repository commands. The reviewed documentation does not present Supacode as a shared-memory system, code index, or knowledge graph. Those capabilities must come from your repository process or a separate context layer.

What Supacode Worktrees Solve

Supacode gives each task a concrete Git workspace. Its documentation says a new worktree is a real Git worktree backed by its own branch and directory, created under ~/.supacode/repos/<repository-name>/. Supacode selects the worktree, opens terminal state associated with it, and can run a configured setup script once.

For large repositories, that operating model solves several practical problems:
- one agent’s uncommitted files do not appear in another agent’s working directory;
- developers can keep multiple branches checked out without switching the main checkout;
- each worktree can retain its own terminal tabs, splits, notifications, and focused surface;
- setup commands can install dependencies, generate local artifacts, or launch an agent;
- run commands can repeat common development or test actions;
- archive commands can stop local infrastructure before the worktree is put away.
These controls reduce accidental interference and make task state easier to inspect. They also create a useful review boundary: branch, diff, terminal, and tests can be associated with one worktree.

Git itself still shares important repository data across linked worktrees. Most refs are shared, even though HEAD, the index, and other selected files are per-worktree. Services outside Git—ports, databases, caches, cloud environments, credentials, and queues—need their own isolation. A new directory is not a new infrastructure account.

The comparison in Git Worktree vs Knowledge Graph explains this division between write isolation and relationship-aware repository context.

Why Isolation Is Not Repository Understanding

An isolated checkout answers “where may this agent work?” It does not answer “which parts of the system govern this change?”

In a large codebase, behavior may span a public API, implementation package, generated client, database schema, feature flag, deployment configuration, and integration tests. An agent entering a clean worktree still has to locate those pieces. If it starts with broad recursive searches, it may spend tokens rediscovering the same layout another agent already mapped. Worse, it may stop after finding the first plausible match.

Repository understanding requires evidence about relationships and authority:
- which module owns the behavior;
- which callers and consumers depend on its current contract;
- which files are generated rather than directly edited;
- which design record explains an unusual constraint;
- which tests exercise the behavior at the correct boundary;
- which facts are observed and which remain hypotheses.
Supacode’s per-worktree terminal helps an agent run searches, tools, and tests in the right directory. Its repository commands make repeatable actions convenient. Neither feature establishes that the selected files are complete or that an architectural conclusion is correct.

The general Agent Swarm Codebase Context pattern is relevant even if you run only a few agents: shared evidence needs a revision, task packets need boundaries, and integration needs an owner.

Large Codebase Failure Modes

Parallel worktrees amplify existing repository weaknesses. Watch for failure modes that look like progress inside one branch but fail at integration.

False locality happens when the agent edits the closest file and misses an indirect caller, configuration gate, or generated artifact. The patch passes a narrow unit test but violates a wider contract.

Duplicate discovery happens when every agent scans the same top-level directories, dependency manifests, and test tree. Isolation makes the scans independent; it does not make them efficient.

Logical overlap occurs when agents modify different files that implement the same public behavior. Git may show no textual conflict, yet the combined changes disagree.

Base drift appears when long-running worktrees begin from different commits. A context packet built for one base can mislead an agent working from another.

Shared-resource collision appears when isolated directories point at the same database, development port, cache namespace, or cloud environment.

Unreviewed summaries become a problem when one agent’s inference is copied into shared context as fact. The next agent may treat a tentative conclusion as repository truth.

Mitigation starts before the first agent launches. Pin the base commit, identify public-contract ownership, enumerate external resources, and define the expected verification surface. Then make uncertainty visible rather than encouraging an agent to complete a confident narrative.

Where Code Knowledge Graphs Fit

A code knowledge graph or structured repository map fits between task assignment and source inspection. It can return candidate modules, symbols, dependency edges, tests, documents, and owners for a task. This makes repository context reusable without merging each agent’s branch or terminal state.

The graph should be read-only for ordinary task agents and labeled with the commit it represents. It should also expose coverage limits: unsupported languages, failed parses, excluded generated code, or edges inferred from configuration. Retrieval is a starting point, not proof.

A useful query packet might include:
1. the task and permitted write paths;
2. the indexed commit and current worktree commit;
3. entry points and likely implementation symbols;
4. direct callers and relevant transitive consumers;
5. related tests, schemas, configuration, and documents;
6. missing evidence that requires manual search.
The agent then confirms each important relationship in its own worktree. Dynamic registrations, reflection, runtime flags, and external systems often require tests or operational evidence beyond a static graph.

For teams designing this layer specifically around Supacode worktrees, Supacode Shared Context Across Worktrees provides a release-order companion architecture.

Practical Setup Pattern

Use a setup pattern that separates Git state, repository facts, and task decisions.

First, add the repository to Supacode and verify the actual Git binary, base branch, and managed worktree location. Supacode currently documents macOS 26.0 or newer as a requirement. Pin the app release during a controlled rollout; v0.10.6 was the latest first-party GitHub release when this article was verified.

Second, define repository commands conservatively. A setup script may install dependencies, generate required local artifacts, or start the chosen coding agent. A run command may launch the standard test watcher or development server. An archive script may stop task-local infrastructure. Because these commands execute in worktree terminal context, keep them reviewable and avoid embedding secrets.

Third, build a read-only context artifact for an approved base commit. It may be a module map, symbol index, dependency graph, test map, or a combination. Store provenance and generation failures. Do not store task-terminal output or unreviewed conclusions in the repository-facts layer.

Fourth, assign each task a branch, write scope, owner, service namespace, and evidence packet. Require a plan before edits and focused tests before broad tests. If two packets touch the same public contract, sequence the tasks or give one integrator authority.

Fifth, integrate deliberately. Update the branch from the approved base, rerun impact queries when the diff changes a public boundary, execute combined tests, and review the final diff independently of each worktree’s local success.

FAQ

Who should maintain shared repo context?

Assign a named team or role that already owns developer infrastructure, architecture documentation, or code intelligence. Task agents may report missing or stale evidence, but reviewed automation or responsible maintainers should approve changes to shared repository facts. Ownership should include refresh policy, access control, coverage monitoring, and incident correction.

What should be verified before running parallel agents?

Verify the base commit, worktree branch, write scope, shared-contract ownership, context revision, setup command, test command, ports, data stores, credentials, generated files, and integration order. Confirm that every agent can distinguish observed source evidence from inferred relationships and knows when to escalate uncertainty.

When should teams avoid parallel worktrees?

Avoid parallel execution when tasks change the same public contract, depend on an unsettled architecture decision, require one scarce mutable environment, or cannot be tested independently. Sequential work is also safer when the context map is materially stale or the integration owner cannot review combined behavior.

Conclusion

Supacode large-codebase worktrees are an effective isolation surface, not an automatic understanding layer. They organize branches, directories, terminals, and repeatable commands so multiple tasks can proceed with clearer operational boundaries.

Add repository understanding separately. Bind a read-only context map to the base commit, keep task reasoning private until reviewed, verify relationships in current source, and test the combined result. That layered workflow preserves what worktrees do well without asking them to solve architecture discovery.
July 23, 2026

Git Worktree vs Knowledge Graph

A Git worktree isolates a branch, directory, index, and HEAD; a code knowledge graph helps an agent retrieve relationships such as callers, dependencies, tests, and architecture boundaries. They solve different problems. Use worktrees to separate concurrent write state, and use a revision-bound knowledge layer to improve repository understanding before anyone edits.

This distinction matters in tools such as Supacode. Its documentation describes real Git worktrees, a managed directory for each worktree, per-worktree terminal state, and repeatable repository commands. It does not describe worktrees as AI memory, repository indexing, or a knowledge graph. Treating isolation as understanding leaves an agent with a clean directory but no reliable map of the system.

Quick Verdict

Choose the layer according to the failure you need to prevent.

Question	Git worktree	Code knowledge graph
Primary job	Isolate checked-out files and per-worktree Git state	Represent and retrieve repository relationships
Useful for	Parallel branches, separate builds, task-specific terminals	Impact analysis, dependency discovery, test selection
Source of truth	Current checkout and Git metadata	An index derived from a named repository revision
Main risk	Branch drift, duplicated services, conflicting shared resources	Stale, incomplete, or overexposed derived context
Final verification	Diff, status, merge checks, tests	Current source, current tests, and responsible reviewers

The choice is therefore not either/or. A parallel coding workflow often needs both. The worktree controls where an agent may change files. The graph or repository map controls which evidence it should inspect first. Neither layer proves that a patch is correct.

For a broader separation of rules and repository facts, read AGENTS.md vs Knowledge Graph. The same authority principle applies here: a tool can organize work, derived context can guide discovery, and checked-out source remains the final technical evidence.

What Git Worktrees Are Good At

Git defines a worktree as one of multiple working trees attached to the same repository. A linked worktree has its own working directory and per-worktree files such as HEAD and the index, while much repository data and most refs remain shared. This lets a developer check out more than one branch at a time without repeatedly switching the main working directory.

That boundary is concrete and operational. It supports:

assigning one branch and directory to each agent or task;
keeping uncommitted changes out of another agent’s checkout;
running task-specific build artifacts and tests from distinct paths;
inspecting one branch while another long-running process continues;
removing a finished linked worktree through Git’s lifecycle commands.

Supacode builds a macOS workflow around this Git mechanism. Its first-worktree guide says each new worktree is backed by a branch and directory, is created under ~/.supacode/repos/<repository-name>/, and receives its own terminal state. Repository commands can start a coding agent, install dependencies, run a dev server, or clean up before archive. These conveniences strengthen process isolation; they do not add semantic understanding of the code.

Worktrees also do not isolate every resource. Git refs are mostly shared, and external resources such as a database, port, cache, cloud account, or package registry can still collide. Teams need unique ports, disposable data, explicit credentials, and cleanup rules where those resources matter.

What Code Knowledge Graphs Are Good At

A code knowledge graph is useful when a task depends on relationships that are expensive or error-prone to reconstruct from filenames alone. It can connect a symbol to callers, an API to implementations, a schema to consumers, a feature to tests, or a module to architectural documentation.

The graph’s value is evidence selection. Instead of giving an agent a large undifferentiated file dump, a query can return a small candidate path:

the public entry point involved in the request;
the implementation and configuration that govern it;
direct and transitive consumers;
related tests and generated artifacts;
documents or owners that constrain the change.

This layer should be descriptive, not authoritative by itself. Parsers miss dynamic behavior. Generated code may be absent. Runtime registration, reflection, environment variables, and external systems may not appear as static edges. Every retrieved relationship needs confirmation against the exact worktree revision before it influences a patch.

The 1M Context vs Knowledge Graph guide explains the adjacent capacity question: a large context window can hold more text, but it still needs a method for selecting fresh, relevant evidence.

Where Coding Agents Confuse the Two

The most common mistake is assuming that a fresh worktree gives an agent fresh understanding. It gives the agent a clean filesystem view. The agent may still repeat broad searches, read obsolete documentation, miss an indirect consumer, or infer architecture from directory names.

A second mistake is treating a graph as shared task state. Repository facts and task decisions have different lifecycles. “Function A calls function B at commit X” can be shared read-only. “Agent 2 plans to rename B” belongs to that task until reviewed. Mixing the two turns a neutral repository map into a stream of provisional conclusions.

A third mistake is assuming either layer prevents merge conflicts. Worktrees reduce simultaneous changes in one directory, but two agents can still edit the same logical contract on different branches. A graph may reveal overlapping impact paths, but it cannot arbitrate product intent. Ownership and integration order still need human or controlled-agent review.

The Share Repo Context Across Coding Agents guide provides a general context contract for teams that need common evidence without common write permissions.

How to Combine Both Layers

Combine the layers by binding repository context to a commit and keeping each task’s writes local to its worktree.

Start with a base revision. Generate or refresh a read-only module, symbol, dependency, test, and documentation map for that revision. Record the generator version and any known exclusions. Then create one worktree per task from the approved base, with a named branch and an explicit write scope.

Before an agent edits, give it a compact evidence packet: task goal, base commit, relevant nodes and edges, cited source paths, likely tests, and known unknowns. Require the agent to verify every important edge in its current checkout. If the worktree has moved ahead of the graph revision, either refresh the affected slice or mark retrieved context as stale.

During execution, keep these controls visible:

one owner for changes to each shared public contract;
separate ports, data, credentials, and services where necessary;
task-local plans, terminal output, assumptions, and failed experiments;
read-only access to the shared repository map;
focused tests in each worktree before integration tests on the combined branch;
a final diff and impact review at the merge point.

Make the evidence packet reviewable by someone other than the task agent. It should identify the base commit, selected paths, direct relationships, likely tests, and the reason each item was chosen. Reviewers can then reject a stale edge, add a missing consumer, or narrow an overbroad scope before parallel edits begin. That checkpoint turns a helpful repository map into accountable engineering input rather than an opaque prompt attachment.

Supacode’s repository setup, run, and archive commands can automate parts of this lifecycle. For example, a setup command can prepare dependencies or launch an agent, while an archive command can stop task-local infrastructure. Keep context generation explicit and independently versioned unless your own tooling provides it; the reviewed Supacode docs do not claim a built-in repository graph.

FAQ

Can a worktree share graph-backed context safely?

Yes, if the graph is read-only to task agents, scoped to approved repository data, and labeled with the exact commit or content revision it describes. Each agent should verify retrieved paths and relationships in its own checkout. Do not let graph access imply permission to read secrets or write outside the task boundary.

What should not be stored in a knowledge graph?

Exclude secrets, credentials, personal data, unrestricted terminal transcripts, proprietary data outside the approved repository scope, and provisional agent reasoning presented as fact. Task-specific plans, unreviewed conclusions, and ephemeral runtime state should stay with the task unless a deliberate review promotes them into shared documentation.

How should teams audit graph freshness?

Store the indexed commit, generation time, tool version, coverage notes, and failed parses. Compare the worktree’s current commit with the graph revision before every task. Renames, dependency-file changes, schema changes, code generation, and public-interface edits should trigger a targeted refresh or a full rebuild according to measured coverage.

Conclusion

Git worktree vs knowledge graph is a comparison of control plane and understanding layer, not competing implementations. Worktrees isolate branch, directory, index, and terminal workflows. A knowledge graph or structured repository map selects relationship-aware evidence.

Use both when parallel agents must change a large repository: bind shared context to a revision, keep task decisions and writes isolated, and verify every important claim in current source and tests. A clean worktree limits interference. Fresh, reviewable repository context limits guesswork.

July 23, 2026

OpenCode Skills vs Code Knowledge Graphs

Use OpenCode Skills to define repeatable work; use a code knowledge graph to answer what the repository currently contains and how its parts relate. A Skill can require an impact review before a migration, but it should not become a manually maintained list of callers, imports, symbols, and tests. A graph can expose that evidence for a specific revision, but it should not decide the team’s workflow or approval policy.

This distinction matters because both layers may be called “agent memory.” They do different jobs, have different owners, and fail in different ways. OpenCode documents Skills as on-demand SKILL.md instructions. It does not document a native code knowledge graph or a durable semantic repository-memory feature. A graph is therefore an optional external layer, queried through a tool or workflow and verified against current source.

Quick Verdict

The practical split is simple: a Skill says how to work; a graph says what the system appears to be; source and tests decide whether a proposed change is correct.

Layer	Owns	Refresh trigger	Example	Unsafe use
OpenCode Skill	Repeatable procedure, decision gates, commands, evidence requirements	A team changes its workflow	“For API removals, trace consumers, run contract tests, and request owner review.”	Storing a hand-written caller inventory or current schema map
Code knowledge graph	Files, symbols, imports, calls, tests, owners, documents, and typed relationships	Source, configuration, or artifact changes	“These handlers reach this schema and these contract tests.”	Treating inferred edges as unquestioned facts
Current task packet	Scope, commit, acceptance criteria, selected evidence, open risks	The task changes or ends	“Migrate this endpoint only; these consumers are in scope.”	Turning a temporary debugging hypothesis into permanent policy

The existing Context Engineering for OpenCode article covers the full context stack. This page owns the narrower boundary between OpenCode Skills and an external repository graph. For the adjacent distinction between human rules and generated structure, see AGENTS.md vs Knowledge Graph.

What OpenCode Skills Are Best For

OpenCode defines an Agent Skill as a reusable SKILL.md file. The agent sees a list of available Skills and can load the full instruction only when needed. The official discovery paths include project and global .opencode/skills, .claude/skills, and .agents/skills directories. OpenCode also lets a team allow, deny, or require approval for Skill access, including per-agent overrides.

Those mechanics make Skills a good place for procedures that recur across tasks but are too detailed for a root instruction file. A good OpenCode Skill can define:

when the procedure applies and who may invoke it;
required inputs, such as a base commit, issue link, or affected public contract;
the order of exploration, planning, implementation, review, and verification;
commands that must run and what result would block the change;
which approvals belong to API, security, data, or release owners;
a handoff format that preserves paths, assumptions, and unresolved risks.

For example, a public-api-removal Skill can require a search for exports, consumers, samples, and documentation; ask for a dependency path; require compatibility tests; and route the final diff to the API owner. That is procedural knowledge. It remains useful even after package names, symbols, and call paths change.

Skills are also a better fit for controlled access than an oversized instruction document. A destructive migration procedure can be hidden from an exploratory agent, require approval for a planning agent, and be allowed for a designated implementation agent. The procedure is discoverable without making every conversation carry every detailed checklist.

Keep a Skill concise and testable. A rule such as “check the deployment contract before editing generated clients” is actionable. A 700-line document that duplicates source files, package inventories, and incident notes is neither durable procedure nor reliable repository evidence. It is a stale second copy of the system.

What Code Knowledge Graphs Are Best For

A code knowledge graph is useful when the question is relational. Which modules import a schema? Which callers reach a permission check? Which tests cover an exported symbol? Which architectural record explains why a boundary exists? These questions require more than a workflow description.

The graph can model packages, files, symbols, routes, APIs, schemas, tests, owners, and documents as nodes. Typed edges can represent imports, calls, implementations, generation, coverage, ownership, or rationale. A traversal can produce a candidate impact path before OpenCode opens the supporting source.

That gives the agent a useful discovery route, not an automatic answer. Dynamic registration, reflection, configuration, generated artifacts, external consumers, and incomplete extraction can all hide or distort a relationship. A high-impact edge must carry enough provenance to be investigated: the repository revision, extractor version, edge type, location, and whether it was deterministic or inferred.

Graphify is one optional example of this external layer. It turns code and documents into graph artifacts and lets an agent query relationships before reading the underlying evidence. Its value is not that a graph replaces source; it is that the graph preserves structural questions that flat chunks or a huge prompt may hide. The graph must still be refreshed as the repository changes.

The graph should not become a policy engine. It cannot decide whether a risky migration deserves a security review. It can show that a data path reaches a sensitive service, which is evidence the appropriate human-owned rule should use. Likewise, it cannot authoritatively decide that a test suite is adequate merely because a COVERS edge exists.

Workflow Rules vs System Understanding

The easiest way to avoid drift is to give each fact one primary home.

Question	Primary home	Why
What must an agent do before a public schema change?	Skill	It is a team-owned procedure with approval and verification gates.
Which packages depend on the schema now?	Graph plus current source	It is a revision-bound structural observation.
What exact migration is approved this week?	Task packet and issue	It is a temporary, human-scoped decision.
Which build command is mandatory?	`AGENTS.md` or focused instruction	It is stable project policy rather than a graph relationship.
Did the new patch preserve behavior?	Tests, runtime evidence, and review	No instruction or graph can establish this without verification.

OpenCode’s rules documentation gives AGENTS.md a separate role: project guidance is included in the model’s context, and opencode.json can add instruction files or globs. Rules state team expectations. Skills package an on-demand workflow. A graph provides a structure-aware evidence index. Mixing the layers invites ambiguity: a graph-derived fact pasted into a Skill is likely to age; a procedural exception encoded as an edge has no clear policy owner.

This separation also makes provider changes less fragile. OpenCode supports many model providers and custom endpoints, but choosing another model does not transfer a private chain of reasoning from the old session. What can persist is the repository’s reviewed rule files, versioned Skills, task evidence, and external graph artifact. The new model must still load and verify them in its own context.

How to Combine Both Layers

Combine the layers in a small, auditable loop rather than loading everything by default.

Start with the Skill. It states the task category, required constraints, decision owner, and verification sequence.
Set the task boundary. Pin a commit, issue, allowed paths, acceptance criteria, and known risks. This prevents an impact query from turning into a repository-wide rewrite.
Query structural evidence. Use the graph to locate direct and multi-hop dependencies, tests, ownership, and relevant architecture documents.
Open current source. Read the files behind high-impact graph paths. Treat inferred, dynamic, or stale relationships as hypotheses rather than commands.
Plan with evidence. Put exact paths, symbols, unresolved edges, and the required tests in the implementation handoff.
Edit, test, and review. Run the Skill’s prescribed checks, inspect the diff, and obtain the responsible human approval.
Update the right layer. Change the Skill only if the procedure changed; refresh the graph when structure changed; record task conclusions in a durable decision record only when the team accepts them as policy or rationale.

OpenCode can reach an external graph through a local or remote MCP server. Its MCP documentation warns that every server and tool description consumes context, so enable graph tools for the agents or tasks that actually need them. A large global tool catalog can erase the context budget saved by better repository selection.

This pattern provides useful information gain over a generic “add memory” recommendation. It makes freshness observable. A reviewer can ask: Which revision produced this graph result? Which Skill required the query? Which source files confirmed it? Which tests disproved or supported the plan? Those questions turn contextual hints into accountable engineering evidence.

FAQ

Can Skills and graph facts conflict?

They should not own the same fact. A Skill may say “verify every generated client before removing a schema.” The graph may return the current generated-client paths. If a path differs from a Skill example, source state wins for the structural fact and the Skill should be revised only if the procedure itself is wrong. Do not edit the graph merely to make it agree with a prose instruction.

Who should approve shared graph updates?

The team responsible for extraction and data quality owns the graph pipeline; owners of affected packages should review important relationship changes; task owners remain responsible for checking high-risk paths against source and tests. A vendor, model, or autonomous agent cannot inherit that accountability.

What should stay in a Skill instead?

Keep reusable action rules in the Skill: scope checks, approval gates, allowed tools, expected evidence, commands, rollback requirements, and handoff shape. Do not place transient issue state, credentials, generated source dumps, exhaustive symbol lists, or unverified architecture claims there.

Conclusion

OpenCode Skills and code knowledge graphs are complementary because they answer different questions. Skills preserve a reviewable way of working. Graphs preserve queryable, revision-bound relationships. Current source, tests, and accountable reviewers decide whether an edit is safe.

Use a Skill when the team needs a repeatable procedure. Add a graph when repository work repeatedly depends on discovering multi-hop structure. Keep both narrow, preserve provenance, and make every high-impact graph result lead back to source verification rather than treating “agent memory” as an authority on its own.

July 23, 2026

Macaron Context vs Code Knowledge Graph

Macaron long context lets a coding workflow place more repository evidence in one model request; a code knowledge graph makes relationships such as calls, imports, ownership, and test coverage queryable. Use the window to reason over a bounded, known evidence set. Use a graph to discover and connect evidence when the task crosses modules. Use current source and tests to verify both.

The fact boundary matters. Macaron-V1-Coding-Venti lists a 1M context length in its MindLab Research model card and a 1,048,576-position configuration. The official MoL harness reference profiles use 262K context at launch. The frequently repeated 2M figure belongs to MindLab’s LongStraw reinforcement-learning training infrastructure, not to a Macaron-V1 inference guarantee. Treat capacity as a dated deployment setting, not a replacement for repository structure.

Quick Verdict

Use long context when a task already has a small, well-justified set of source files, tests, specifications, and decisions to compare. Use a code graph when you first need to answer which files, callers, consumers, tests, or owners are relevant. Use both for a risky multi-module change: graph-select the evidence, read it in context, then verify the result.

Method	Primary question	Best fit	What it cannot establish
Macaron context window	How much evidence can be present together?	A known subsystem, diff review, distributed contract and test reading	That all relevant evidence was included or used correctly
Lexical or semantic retrieval	Which chunks match this query?	Symbols, errors, exact terms, and concept search	A complete dependency or authority path
Code knowledge graph	Which repository entities relate, and through which typed path?	Impact tracing, callers, imports, schemas, tests, ownership	Dynamic behavior, perfect freshness, or policy decisions
Source and tests	Is the claimed behavior supported now?	Any high-impact plan or change	Nothing can replace current evidence and verification

The broader 1M Context vs Knowledge Graph guide compares this pattern across model families. This page applies it to Macaron-V1’s official 1M model specification and its documented serving caveat.

What Long Context Helps With

Long context is valuable after evidence selection. A coding agent can keep a larger coherent slice of the task together: interface contract, implementation, callers, tests, architecture decision, migration plan, logs, and current diff. This reduces the need to compress every source file into summaries that lose important constraints.

With Macaron-V1, a useful long-context request might contain a pinned commit’s authentication middleware, session model, policy configuration, contract tests, recent incident note, and a targeted acceptance criterion. The agent can compare the materials in one working view and explain contradictions without repeatedly reloading fragments.

Long context also helps with:

reviewing a known migration path across schema, generated client, consumers, and release notes;
comparing a proposed patch against multiple invariants and test suites;
retaining a bounded tool trajectory while synthesizing a plan;
reading a subsystem where the relevant files and documents have already been identified;
checking whether a diagnosis accounts for both implementation and operational evidence.

The model card’s 1M context value should be read narrowly. It describes the checkpoint configuration. The MoL harness’s documented 262K launch setting describes a provided self-hosted profile. Hosted service behavior may differ again. A team trial should record the exact model, endpoint or harness, context setting, system instructions, tool configuration, prompt size, cache behavior, and repository commit. Without this, “Macaron handled our large codebase” is not reproducible.

Long prompts are not automatically better prompts. Unneeded files, duplicate definitions, stale documents, generated code, vendor code, and tool descriptions can dilute the evidence that matters. A larger window can reduce some retrieval pressure, but it cannot determine authority or make the model notice every important relation.

What Code Knowledge Graphs Add

A code knowledge graph preserves explicit repository structure. It turns questions such as “who consumes this API?” or “which tests reach this schema?” into traversals over named entities and typed relationships.

Useful nodes include packages, files, symbols, routes, APIs, schemas, configuration, tests, owners, and design documents. Useful edges include imports, calls, implementations, generated-from, covers, owned-by, and rationale-for. The result is not merely a ranked set of chunks; it is a candidate explanation of why the evidence belongs together.

That matters when a query is structural rather than textual. Searching for a field name may find its declaration and many incidental mentions. A graph can show that the field is serialized by one adapter, consumed by three clients, validated by a contract suite, and covered by a deployment flag. The agent can then read those primary files together in its context window.

Graphs add three controls that large prompts lack by default:

Relationship visibility. An impact path can be inspected and challenged rather than inferred from a pile of files.
Provenance and freshness. Important graph results can name the source locations, repository revision, extraction method, and refresh date.
Repeatable selection. Different agents or model providers can query the same maintained evidence layer instead of starting discovery from scratch.

Graphify is an optional external implementation of this pattern. It can generate code and document graph artifacts that guide an agent toward structural evidence. It is not a claim that Macaron or a separately configured HCP SDK includes a native code graph. An external graph must be refreshed and its important edges verified against current source.

Repository Tasks That Need Structure

Structure matters when the consequence of a change lies outside the first file the model opens.

Task	Candidate relationship path	Why a graph helps
Remove a public field	schema → serializers → generated clients → consumers → examples → contract tests	Surface matching alone can miss generated or downstream users
Change an authorization rule	entry point → middleware → policy → session store → error tests → audit owner	The behavior spans code, configuration, and responsibility boundaries
Split a package	exports → imports → build graph → package owners → release artifacts	The task is about dependency direction, not one code snippet
Diagnose a delayed job	schedule → queue → worker → retry policy → state write → telemetry	Runtime behavior often crosses vocabulary and modules
Modernize a database call	query helper → transaction boundary → callers → migration → integration tests	Local edits can change ordering, consistency, or rollback behavior

For each path, the graph gives a starting hypothesis. Dynamic registration, reflection, runtime configuration, feature flags, generated code, and external integrations may still be omitted. The model should mark uncertain edges and request the source or owner evidence needed to resolve them.

This is a better test of repository understanding than asking whether a model can summarize a large directory. A useful response identifies the expected path, distinguishes confirmed and inferred relationships, and proposes the tests that can falsify its plan.

How to Combine Context Windows and Graphs

Use the two layers in sequence rather than forcing a false choice.

Pin the task. Record objective, acceptance criteria, base commit, allowed write paths, and reviewers.
Select the evidence neighborhood. Search and graph-traverse direct dependencies, multi-hop consumers, tests, owners, configuration, and relevant decisions.
Verify the path. Open raw source behind high-impact graph edges. Note stale, dynamic, or unconfirmed behavior.
Build the context packet. Include only the current files and documents that explain the task, plus an explicit unknowns list.
Reason with Macaron. Ask for a minimal plan, cited evidence, change risks, test rationale, and a boundary between fact and inference.
Edit under control. Restrict writes to approved scope, review the diff, run focused and broader checks, and obtain owner approval.
Refresh after structure changes. Update the graph after accepted refactors, symbol moves, generated-artifact changes, or dependency rewiring. Do not turn temporary task notes into permanent graph facts.

MindLab’s separately published HCP SDK can standardize configuration inputs such as Skills, resources, MCP, hooks, workspace staging, and provider settings. Its public documentation describes a wrapper around other runtime components, not a Macaron checkpoint feature, agent, or repository-memory database. Use that configuration role to make a workflow repeatable, while keeping repository intelligence in source-controlled artifacts and an independently maintained graph.

The combined workflow yields a practical division of labor: the graph reduces repeated discovery, the context window holds the selected evidence for synthesis, and current source plus tests constrain the outcome. This is more reliable than assuming a long prompt or a graph query is self-validating.

FAQ

What 2M context claims should be verified?

First verify what the number measures. For Macaron-V1-Coding-Venti, the official model card and configuration support a 1M model-context specification. MindLab’s LongStraw materials describe 2M-plus reinforcement-learning training infrastructure. They do not establish a 2M production inference window for Macaron-V1. Also verify the actual endpoint or self-hosted harness setting; MindLab’s reference MoL profiles use 262K.

Can graph retrieval miss important files?

Yes. A graph can miss dynamic behavior, unsupported language features, generated files, stale documentation, external services, or an incorrectly inferred edge. Treat traversal as evidence selection, record provenance and revision, inspect high-impact source, and sample the graph against known changes. Retrieval failure is an engineering risk to measure, not a reason to discard structure entirely.

When should teams use both approaches?

Use both when a task spans multiple packages or artifacts and the selected evidence still fits comfortably inside the actual deployment context budget. A graph is most useful before the model knows the relevant neighborhood; long context is most useful after the neighborhood is justified. For a small, known, single-file change, direct source reading and focused tests are usually cheaper.

Conclusion

Macaron context vs knowledge graph is not a contest between a large model window and repository structure. A 1M Macaron-V1 specification can make it easier to synthesize a known body of evidence. A graph can make relationship paths, provenance, and repeated discovery more explicit. Neither proves a patch is correct.

Use a graph to select and explain structural evidence, Macaron to reason over the selected current material, and source inspection, tests, and responsible reviewers to validate the change. Keep the 2M LongStraw training claim separate from the Macaron-V1 inference question.

For the model-specific repository trial, use the Macaron-V1 large-codebase test plan. For constructing and maintaining the bounded evidence packet, continue with Macaron context engineering.

July 23, 2026

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.

Confirm the task contract, base commit, and allowed write scope.
Read the relevant project rules and named architecture records.
Search or traverse the direct and multi-hop dependencies of the target symbol or behavior.
Open current source, configuration, and tests behind important relationships.
List confirmed facts, inferred paths, and unknown external or dynamic behavior separately.
Propose the smallest viable edit, expected tests, rollback point, and responsible reviewer.
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.

July 23, 2026

Macaron-V1 for Large Codebase Understanding

Macaron-V1 large-codebase work should be evaluated as a repository-understanding problem, not as proof that a model can accept a long prompt. Test whether the coding checkpoint can identify architecture boundaries, trace dependencies, predict the impact of a change, select relevant tests, and explain uncertainty against a pinned repository revision.

MindLab Research released Macaron-V1-Coding-Venti on July 21, 2026 as a merged coding-specialist checkpoint derived from the Macaron-V1 Venti L2 Coding LoRA and GLM-5.2. Its model card lists code understanding, repository-level software engineering, terminal use, and coding-agent workflows as intended domains. It also lists a 1M context length and MIT license. Those are capability and access claims, not a completed evaluation of your codebase.

What Large Codebase Understanding Means

Large-codebase understanding is the ability to make a defensible claim about a system whose behavior is distributed across files, packages, configuration, generated artifacts, tests, documents, and runtime boundaries.

For a coding model, useful evidence includes more than a correct-looking patch. A repository-aware response should be able to:

identify the relevant package, public boundary, and responsible owner;
distinguish a definition from its callers, implementations, generated copies, and obsolete siblings;
trace a likely change path through imports, calls, schemas, configuration, and tests;
name what is directly observed, what is inferred, and what cannot be known from the checked-out source;
select tests that validate the behavior rather than merely executing nearby files;
preserve scope when the task asks for a narrow change instead of offering a speculative refactor.

The target is not “the model read every file.” It is a change plan or answer that a reviewer can reconstruct from current evidence. A model might correctly summarize an unfamiliar repository while failing to notice a dynamic registration path, a deployment flag, or an external client. A strong evaluation records both the right conclusion and the evidence route used to reach it.

For this reason, treat Macaron-V1-Coding-Venti as the specific subject of a trial, not “Macaron” as a generic label. The Coding-Venti card says its L2 Coding LoRA is merged into the GLM-5.2 base, so it can be deployed as a standard merged checkpoint without runtime adapter loading. The fuller Macaron-V1 Venti system and its routing harness are separate surfaces with their own context and serving behavior.

What Long Context Alone Cannot Prove

A large context window expands the amount of material a model can receive. It does not demonstrate that the model selected the right evidence, connected the right relationships, or respected authority and freshness.

The Coding-Venti model card and configuration declare a 1,048,576-position model limit. MindLab’s checked-in Mixture-of-LoRA harness, however, configures its Venti and Tall launch profiles with a 262,144-token context limit. Both details are important during a trial: the former describes the checkpoint specification; the latter describes a reference self-hosted serving profile. Neither means every hosted endpoint, local deployment, prompt shape, or repository task has the same usable context.

Do not transfer LongStraw’s multi-million-token number to Macaron-V1 inference. LongStraw is MindLab’s long-context reinforcement-learning infrastructure. Its public repository describes training-side resident state and response replay; it is not a product specification saying that Macaron-V1-Coding-Venti receives 2M tokens in production.

Even when a trial really can provide a large repository slice, several questions remain:

Question	What a context limit cannot answer
Evidence selection	Whether the model attended to the relevant contract instead of a duplicate or stale file
Dependency reasoning	Whether it recognized an indirect caller, generator, feature flag, or runtime registration
Change safety	Whether a proposed edit preserves compatibility and deployment behavior
Freshness	Whether the included files and documents match the commit being changed
Reviewability	Whether a human can locate the sources behind the recommendation

The adjacent 1M Context vs Knowledge Graph guide explains why capacity, retrieval, and repository relationships are separate design choices. For a model trial, use the context window to hold a bounded, known evidence set—not as a substitute for an impact-analysis method.

Tests for Architecture and Dependency Awareness

Build a private evaluation set from completed, reviewable changes. Each task should have an expected evidence path and a verification result. Avoid leaking the target diff into the prompt.

Start with five test families:

Architecture localization. Give the model a feature request and ask which package owns the boundary, which documents establish the intent, and which files are only adjacent. Score cited paths and stated uncertainty.
Dependency tracing. Ask for direct callers, transitive consumers, generated outputs, configuration gates, and test surfaces for one API or schema. Compare the answer with a reviewer-created path and current source search.
Impact analysis. Present a proposed behavioral change. Require a list of compatible and incompatible consumers, migration steps, rollback conditions, and tests. Penalize ungrounded dependencies and missed public contracts.
Cross-module repair. Seed a realistic bug whose cause and symptom live in different modules. Require a diagnosis, minimal edit plan, test rationale, and statement of what must be run in a real environment.
Negative-evidence handling. Include a tempting but irrelevant file or stale document. Ask the model to separate confirmed evidence from a hypothesis. This measures whether it can say “not established” instead of filling gaps confidently.

Record exact inputs for every run: repository commit, model ID, serving stack, context budget, system instructions, tools, retrieval or graph configuration, temperature, and date. Then record outputs that a reviewer cares about: correct affected files, unsupported claims, missed dependencies, patch correctness, test selection, reviewer corrections, latency, and token use.

Run a baseline with ordinary repository search and file reading. Then run a long-context version, and where appropriate a graph-selected-evidence version. The comparison reveals whether capacity improves the task or merely increases prompt size. It also prevents an impressive vendor benchmark number from replacing evidence on your private architecture.

Failure Modes to Watch

Repository work fails at boundaries. Watch for these patterns during a Macaron-V1 trial:

The complete-dump illusion: the prompt contains many files, but the answer ignores the one policy, generator, or test that governs the change.
False impact paths: the model mistakes lexical similarity for a call or data-flow relationship, or invents a dependency that source does not support.
Stale graph or index: structural retrieval points to a previous commit after a rename, code generation, or package split.
Scope expansion: a narrow defect fix becomes a broad refactor because the model discovers adjacent technical debt.
Tool compatibility confusion: OpenAI-compatible transport or an API response does not prove reliable tool calling, patch application, or terminal behavior in a specific harness.
Benchmark transfer: vendor-reported SWE or terminal scores are treated as proof of repository understanding on a different codebase and workflow.

Mitigate these failures by setting a base commit, using read-only exploration first, requiring citations to current paths and symbols, and asking for an explicit “unknown or unverified” list. For edits, restrict write paths, run focused tests before broad checks, and route public-contract changes to the relevant human owner.

A code knowledge graph can reduce repeated discovery by making a candidate dependency path visible. It cannot guarantee completeness. Use it to select evidence, then inspect current source and tests. That balance is especially useful when a model’s window is large enough to read a subsystem but not enough to turn raw repository scale into reliable understanding.

Evidence and Version Notes

MindLab’s model card publishes a table of coding and terminal benchmarks, including SWE Verified and TerminalBench 2.1. Those are vendor-reported results. The same card says the full benchmark methodology is forthcoming, so they should not be presented as an independent ranking or a direct prediction of your codebase performance.

The most defensible claims for a release note or trial plan are narrower:

Macaron-V1 is an official Mind Lab release dated July 21, 2026.
Macaron-V1-Coding-Venti is a MindLab Research coding checkpoint with a stated 1M context specification, open weights, and MIT license.
The official harness exposes OpenAI-compatible APIs and routes task requests through its profile architecture.
Reference harness launchers use 262K context, so deployment context must be measured rather than assumed.

Everything beyond that—including cost, hosted limits, patch quality, security behavior, and repository reliability—belongs in a dated trial record. Preserve model revision, checkpoint hash when available, serving configuration, prompt template, and repository commit. Without that record, a future comparison cannot tell whether a result changed because of the model, the harness, the task, or the codebase.

FAQ

What should be tested before trusting Macaron-V1?

Test representative architecture localization, dependency paths, impact analysis, cross-module repairs, and negative-evidence handling on a pinned private repository. Require source citations, expected tests, and reviewable diffs. Also test the actual serving profile and context budget you will use; do not infer production behavior from the model-card limit.

How should teams record model version results?

Store the model ID, checkpoint/revision, provider or harness version, context setting, tool configuration, prompt template, date, repository commit, task fixtures, outputs, scores, reviewer corrections, and test results. Keep vendor benchmarks in a separate evidence field so they cannot be mistaken for internal evaluation data.

When is long context not enough?

Long context is not enough when evidence is unknown, relationships are multi-hop, behavior is dynamic, documents conflict, or the change has external consumers. Use source search, an approved structure index or graph, task boundaries, and tests to select and verify evidence before relying on model synthesis.

Conclusion

Macaron-V1 large-codebase understanding is a testable workflow claim, not a property granted by a 1M context number. The Coding-Venti checkpoint is explicitly positioned for repository and coding-agent work, but only a controlled trial can show whether it understands your architecture, dependencies, impact paths, and tests.

Measure the checkpoint and harness on pinned repository tasks. Use long context to retain a known evidence set, use structural tools to locate relationships, and make current source, tests, and responsible reviewers the final authority.

July 23, 2026

Kimi K3 Codebase Understanding Tests

Kimi K3 is available as a hosted model, but Moonshot has not published a dedicated repository-understanding result. The useful question is therefore not whether its million-token window can hold a codebase. It is whether K3 can recover architecture, trace dependencies, predict change impact, and complete a controlled multi-file refactor with evidence.

This guide defines a reproducible test for those capabilities. For launch specifications and product access, see the existing Kimi K3 guide; this article owns the evaluation protocol rather than repeating a model review.

Why Kimi K3 Codebase Claims Need Testing

Moonshot released hosted Kimi K3 access on July 17, 2026 through Kimi.com, Kimi Work, Kimi Code, and the Kimi API. The official API identifier is kimi-k3, while Kimi Code documents the shorter k3 identifier. Moonshot advertises up to a one-million-token context window, although the effective Kimi Code limit depends on the membership tier.

The launch post also says K3 can navigate massive repositories and reports results on DeepSWE, Program Bench, Terminal Bench 2.1, FrontierSWE, SWE Marathon, PostTrain Bench, MLS Bench, and the internal Kimi Code Bench 2.0. These results support a claim that K3 was designed for long-horizon coding. They do not isolate repository understanding.

End-to-end coding scores mix several variables:

the model and reasoning setting;
the agent harness and search policy;
repository tools and test feedback;
time, token, and permission limits;
task quality and grader behavior.

Even the official release illustrates why setup details matter. Its benchmark table reports 67.5 for DeepSWE, while a footnote cites 67.3 for K3 with the mini-SWE-agent harness on the official leaderboard. Neither number is necessarily wrong; they describe different recorded conditions. A private evaluation must be at least as precise about its own conditions.

Large context creates capacity, not a verified mental model. A prompt may contain every file yet still produce a wrong dependency path, overlook runtime configuration, or infer architectural intent from stale documentation. The 1M context versus knowledge graph guide explains this distinction between storage, selection, and explicit relationships.

What Would Count as Repository Understanding

Repository understanding is the ability to produce correct, traceable conclusions about a specific revision of a codebase. A useful evaluation should test four separate capabilities instead of awarding one impressionistic score.

Capability	Required output	Verification target
Architecture recovery	module boundaries, entry points, responsibilities, and external interfaces	expert-maintained architecture map
Dependency tracing	direct and transitive call, data, schema, configuration, and build paths	static/runtime evidence plus reviewed source
Change-impact analysis	affected code, tests, consumers, migrations, and deployment concerns	hidden impact set prepared before the run
Multi-file refactoring	minimal patch that preserves contracts and behavior	hidden tests, contract checks, and human review

Evidence quality is part of the capability. Each conclusion should cite a file and symbol, relevant configuration, or executed command. A plausible diagram without traceable support is not a correct architecture answer.

Calibration matters too. The model should separate observed facts from inferences and unknowns. Rewarding “not enough evidence” when a cross-repository consumer is inaccessible is safer than forcing complete-looking answers. False confidence should reduce the score even when part of the final patch works.

A Reproducible Test Plan

Start by freezing the environment. Record the repository commit, submodules, dependency lockfiles, build image, database fixtures, and tool versions. Prepare the answer key and hidden checks before K3 sees the tasks so the rubric cannot drift toward its output.

Use the following protocol:

Select one localized task and at least three cross-module tasks from recent, accepted engineering work. Remove secrets and avoid public tasks that may have entered training data.
Start every run from a fresh session and clean worktree. Use kimi-k3 for API trials or document that the Kimi Code surface used k3.
Lock the harness, system instructions, reasoning effort, tools, network policy, permissions, context budget, timeout, and maximum turns.
Give every compared model the same repository snapshot and tool access. Do not improve one model’s prompt after seeing its first failure.
Require an evidence packet before editing: architecture summary, dependency paths, expected impact, uncertainties, and planned verification.
Run at least three independent trials per task. Preserve prompts, tool trajectories, patches, tests, latency, token use, and errors.
Score against the precommitted answer key, then conduct a blinded human review for unsupported claims, unnecessary edits, and missed risks.

A practical 100-point rubric can assign 20 points each to architecture, dependency tracing, and impact analysis; 30 to refactor correctness; and 10 to evidence quality and calibration. Publish the weights before testing. A failed hidden contract test should cap the refactor score regardless of how polished the explanation appears.

If the objective is model comparison, keep the harness constant. If the objective is product comparison, test each model in its native coding agent but label the result as an end-to-end system outcome. Mixing those questions produces a ranking that cannot explain its cause.

Tasks to Include in the Evaluation

The task set should expose different failure modes. Four task families provide a useful minimum.

Recover the Architecture

Ask K3 to identify entry points, module responsibilities, public interfaces, persistence boundaries, and one important runtime flow. Require citations for every node and edge. Compare the result with a map reviewed by maintainers, scoring missing and invented relationships separately.

Trace a Dependency Path

Choose a request, event, schema, or shared type that crosses several modules. Ask for the path from producer to consumer, including registration, configuration, generated code, tests, and conditional branches. Seed at least one misleading same-name symbol to detect search-only answers.

Predict Change Impact

Describe a narrow contract change without revealing the known impact set. K3 should list direct edits, transitive consumers, migrations, tests, rollout order, and inaccessible evidence. Score recall and precision; listing every package should not earn full credit.

Execute a Multi-File Refactor

Use a change that is small enough to review but broad enough to cross a real boundary. Require a plan, implementation, focused tests, full regression checks, and a final dependency audit. Hidden tests should cover behavior, compatibility, and an unrelated path that must remain unchanged.

For every family, record navigation efficiency, evidence accuracy, unnecessary file reads, unsupported assumptions, changed-file count, test selection, and human correction time. Pass rate alone can hide a costly patch that reviewers must largely rewrite.

Limits and Evidence Standards

This protocol measures K3 in one controlled environment, not all repositories. Results can change with language, repository size, test quality, architecture, harness updates, and model service revisions. Publish the repository characteristics and repeat the test after material model or agent changes.

Moonshot’s reported benchmarks remain vendor evidence. Kimi Code Bench 2.0 is internal, and other coding benchmarks evaluate task completion under named harnesses rather than pure repository comprehension. Cite them as orientation, not validation of a private result.

The release state also needs precise wording. Hosted K3 is available, so tests do not need to wait for a future model launch. However, Moonshot said full weights would arrive by July 27, and no official K3 weight repository or license was visible in its canonical GitHub or Hugging Face listings on July 17. Self-hosting, weight-level research, and license conclusions should wait for those artifacts.

Finally, avoid presenting a one-million-token run as a fair baseline unless the client actually exposes that capacity. Record the effective limit, retrieved files, cache behavior, and any compaction. For structured navigation, a current code index or Graphify code knowledge graph can help select evidence, but generated relationships still require source and test verification.

FAQ

What evidence should teams publish?

Publish the repository revision or a reproducible anonymized fixture, task definitions, hidden-test construction method, answer-key ownership, model and harness identifiers, settings, tool policy, trial count, aggregate scores, failure categories, and representative redacted trajectories. State which results are vendor-reported, internally measured, or independently reproduced.

How should prompts be versioned?

Store the system prompt, task prompt, repository instructions, tool descriptions, rubric, and environment manifest together under a version or content hash. Record model ID, surface, reasoning effort, date, permissions, network access, context limit, timeout, and turns. A wording change or added hint creates a new test version.

When should tests wait for release?

Do not wait to test hosted Kimi K3; it is already available. Wait when the research question specifically requires downloadable weights, a verified license, self-hosted inference, or the forthcoming technical report. Recheck official artifacts before publishing conclusions about those properties.

Conclusion

Kimi K3’s launch evidence justifies a serious codebase evaluation, not an automatic repository-understanding verdict. Its context window and coding benchmarks indicate capacity for demanding agent workflows, while the absence of a dedicated repository test leaves the central claim open.

Freeze the environment, precommit the rubric, test architecture, dependencies, impact, and refactoring separately, and retain evidence from repeated runs. Treat K3 as repository-capable only when it produces traceable conclusions and correct changes on the codebase that matters to your team.

July 17, 2026

Qoder Subagent Context for Codebases

Qoder Subagents do not automatically share the main session's full context or one another's intermediate work. Give each role an explicit evidence packet containing the repository revision, task boundary, relevant paths, architecture constraints, approved findings, expected output, and verification commands. Treat the final handoff as a reviewable artifact, not as shared memory.

This design lets planning, implementation, testing, and review agents use consistent repository facts without loading the same raw conversation into every context. It also preserves isolation: each Subagent receives only what it needs and operates within its own tool, permission, runtime, and workspace boundaries.

Why Subagents Rebuild Context

Qoder CLI defines a Subagent as a specialized agent with its own conversation context, system prompt, tool registry, transcript, and compression flow. Its intermediate search and reasoning do not directly enter the main conversation. The main session coordinates the task and receives the Subagent's result.

Isolation keeps exploration details from crowding the coordinator's context, but it creates an information-transfer problem. A planner may discover that an API handler is generated, yet an implementation agent will not know that fact unless the handoff says so. A tester may find an undocumented consumer, while a reviewer sees only the patch unless that evidence is carried forward.

The same problem appears when a Subagent starts from a broad instruction such as “review this migration.” It may have to rediscover:

the repository commit and working-tree state;
which package owns the behavior;
the approved architecture boundary;
callers, schemas, generated outputs, and external consumers;
commands that produce a representative test result;
decisions already made and questions that remain open.

Repeated discovery consumes tool calls and increases inconsistency. Two agents can inspect different files, trust different documents, and produce individually plausible but incompatible recommendations.

Qoder's optional auto-memory is not a substitute for a handoff. It is enabled separately, stores selected local Markdown facts, and can become stale. Project AGENTS.md and rules provide durable guidance, but they do not contain every task finding. A reliable Qoder subagent context workflow therefore distinguishes stable repository knowledge from temporary evidence and role-specific reasoning.

Define Shared Repository Knowledge

Shared repository knowledge should be a small, versioned contract that every role can verify.

A useful evidence packet contains:

Field	What to record	Why it matters
Revision	Commit, branch, and relevant uncommitted-state note	Prevents agents from reasoning over different snapshots
Objective	Requested outcome and explicit non-goals	Limits scope expansion
Relevant paths	Entry points, likely owners, tests, and documents	Reduces duplicate scanning without hiding source
Architecture constraints	Approved boundaries and decision records	Preserves design intent
Relationship evidence	Callers, imports, schemas, generators, and consumers	Supports impact analysis
Permissions	Allowed tools, paths, commands, and network access	Keeps each role inside its authority
Verification	Focused tests, broader checks, and acceptance conditions	Gives every role the same definition of done
Open questions	Uncertain, stale, dynamic, or cross-repository facts	Stops inference from becoming a silent decision

Store durable commands, conventions, ownership, and review requirements in maintained project memory. Qoder CLI supports project AGENTS.md, machine-local AGENTS.local.md, and focused .qoder/rules files. Store the active task packet separately so temporary paths, logs, and hypotheses do not become permanent instructions.

When relationships are expensive to rediscover, a separately maintained repository index or knowledge graph can supply a shared query layer. The graph is external evidence, not automatic Qoder AI agent memory. Every important edge should identify its source and indexed revision, and the receiving agent should inspect current code before acting.

The broader shared-context workflow for coding agents explains how to keep common evidence portable across tools. The Qoder CLI context-engineering guide owns the underlying memory and document layers.

Split Planning, Implementation, Testing, and Review Context

Give every Qoder agent one responsibility and the least context needed to fulfill it.

Role	Receives	Produces	Recommended boundary
Planning	Objective, revision, architecture records, relationship leads	Impact map, candidate files, risks, test plan, unresolved questions	Read and search tools; no source edits
Implementation	Approved plan, exact paths, constraints, acceptance conditions	Focused patch, changed-path list, deviations, local validation	Edit only approved areas; isolated worktree for parallel edits
Testing	Patch or commit, impact map, test commands, known risks	Reproducible results, uncovered paths, failures, environment notes	Read plus approved test commands; no product-code changes by default
Review	Original objective, approved plan, diff, test evidence, open risks	Findings, evidence links, approval or required revisions	Read-only source and diff inspection

Qoder CLI supports project-level Subagent definitions under .qoder/agents/*.md and user definitions under ~/.qoder/agents/*.md. The current /agents interface and qodercli agents list show what the installed version discovered. Built-in roles can vary by version and enabled features, so a workflow should refer to verified role names instead of assuming a universal list.

The role prompt should say what information the Subagent receives and what its response must contain. For example, an implementation handoff should require changed files, decisions made, assumptions, commands run, failures, and any departure from the approved plan. A final answer that says only “done” is not a usable context transfer.

Do not pass the planner's private reasoning as authority. Pass its cited findings, unresolved questions, and approved plan. This keeps downstream work auditable and gives another agent enough information to challenge an incorrect conclusion.

Reduce Duplicate Scans and Conflicting Changes

The coordinator should perform one evidence preflight, then distribute role-specific views of the same packet.

Start by locking the revision, objective, ownership, and acceptance criteria. Ask a read-only planning role to locate evidence and mark uncertainty. After approval, freeze a plan identifier or digest so implementation and review can confirm they are evaluating the same scope.

For parallel work, divide by non-overlapping ownership rather than by arbitrary file count. Qoder Subagents can use isolation: worktree, which gives an editing role a separate Git worktree. Worktree isolation reduces accidental file collisions; it does not make two architectural decisions compatible. Assign one integration owner to order changes, resolve overlapping contracts, and decide which result becomes canonical.

A compact handoff log should record:

task and plan identifiers;
source and output revisions;
agent role and effective tool boundary;
evidence inspected and key findings;
files changed or tests executed;
assumptions, failures, and unresolved questions;
next owner and required decision.

Reuse verified relationship queries rather than copying large tool transcripts. A graph result can identify a dependency path, while the packet records the path, provenance, and files checked. The next agent can validate the claim without repeating the entire scan.

For a product-neutral design across many parallel workers, see agent swarm codebase context. The Qoder-specific workflow remains smaller: use discovered Subagents, explicit packets, scoped tools, and one accountable coordinator.

Permission and Drift Risks

Shared evidence reduces repeated work, but it can also spread a wrong assumption faster.

Use these safeguards:

Pin the snapshot. Put the repository revision and packet timestamp in every handoff.
Mark authority. Separate current source, approved decisions, generated graph findings, test output, and model inference.
Limit tools. Configure each Subagent with the tools required for its role; do not give a reviewer write access by habit.
Check permission inheritance. If a Subagent omits its permission mode, Qoder documents that it inherits the current parent mode. Inspect the effective boundary rather than trusting a prompt label.
Protect parallel edits. Use worktrees for independent implementation tasks and inspect every returned diff before integration.
Expire task context. Close or refresh packets when the source revision, architecture, ownership, or acceptance criteria change.
Re-run evidence. Test output and graph paths should be reproducible from the recorded revision.
Escalate decisions. Security, data, public contracts, deployment, and cross-team boundaries need the responsible human owner.

Qoder permissions control whether tools can act; they do not prove the correctness of a plan or patch. Likewise, an AGENTS.md instruction is context rather than enforcement. Put mandatory path, command, and tool restrictions in permission rules or Hooks, then verify behavior with tests and review.

Avoid putting secrets, customer data, credentials, or unrelated private material into a shared packet. The coordinator should also exclude speculative reasoning that downstream agents could mistake for an approved fact.

FAQ

What should subagents not share?

Do not share secrets, credentials, customer data, unrestricted environment dumps, private reasoning, unrelated source, or stale conclusions. Keep role-specific scratch output isolated. Share only evidence and decisions needed for the next role, with provenance, revision, authority, and explicit uncertainty.

How should teams log handoffs?

Use a structured record tied to the task and repository revision. Include the role, effective tools and permissions, evidence inspected, findings, changed files, commands and results, assumptions, deviations, open risks, and next owner. Store durable decisions in approved project documentation rather than leaving them only in a conversation transcript.

When should one agent own a decision?

Use one decision owner when parallel tasks touch the same public contract, schema, package boundary, migration order, generated artifact, or deployment sequence. Specialized agents can provide evidence, but the coordinator or responsible human owner should select the canonical plan and integration order.

Conclusion

Qoder Subagents provide useful context isolation, configurable tools and permissions, parallel execution, and optional worktree separation. Those capabilities help divide repository work, but they do not create automatic shared repository knowledge.

Build Qoder subagent context around explicit, revision-locked evidence packets. Give planning, implementation, testing, and review roles different inputs and authority. Log every handoff, refresh stale evidence, inspect worktree diffs, and keep one owner accountable for decisions that cross boundaries.

The decision rule is straightforward: share verified facts and approved constraints, not entire transcripts. If the next role cannot reproduce a claim from the recorded source, it should treat that claim as unresolved.

July 17, 2026

Qoder CLI Context Engineering

Qoder CLI context engineering is the practice of supplying the agent with the smallest current evidence set that can support a correct plan. Use AGENTS.md and scoped rules for durable guidance, reviewed architecture documents for design intent, a task packet for the current objective, and code indexes or graphs for relationships that static instructions cannot maintain.

The important boundary is simple: Qoder CLI can load layered instructions and optional memory, but none of those layers automatically proves which modules, callers, schemas, or tests a change will affect.

Before You Start

Start by separating product behavior from repository knowledge.

Qoder's current CLI memory documentation describes user-level ~/.qoder/AGENTS.md, project AGENTS.md, machine-local AGENTS.local.md, and focused rules under .qoder/rules/. The TUI can create or update project memory with /init and show active memory through /memory. Optional auto-memory exists, but it requires explicit environment settings and stores local Markdown artifacts; it is not a continuously synchronized model of the codebase.

Before designing the context system, record five facts:

the repository root and working commit;
the source, test, generated, vendored, and migration-controlled paths;
the teams that own architecture and shared instructions;
the actions the agent may perform without approval;
the commands that establish an acceptable result.

Then choose an evidence hierarchy. A practical order is current source and executable tests, approved schemas and architecture decisions, generated structural artifacts, task notes, and finally model inference. The hierarchy prevents a polished summary or stale memory from overruling the implementation it was meant to explain.

Use a trusted workspace when project memory and settings must load. Qoder documents that memory discovery can walk from the workspace toward the Git root and that nested memory may load only after the agent reads a file in that subtree. Do not assume starting at the repository root injects every nested instruction file into the first prompt.

This guide assumes Qoder CLI, not Qoder Desktop. Qoder's Repo Wiki and embedding-index documentation currently belong to its general/Desktop product documentation. They should not be represented as native Qoder CLI context layers without a CLI-specific source.

Layer AGENTS.md, Docs, and Task Context

Each context layer should answer a different question.

Layer	Question it answers	Suitable content	Refresh trigger
`AGENTS.md`	How should work be performed here?	commands, conventions, ownership, protected boundaries, required checks	policy or workflow change
`.qoder/rules/`	When does focused guidance apply?	file-scoped, manual, or task-class rules	affected workflow changes
Architecture docs	Why is the system shaped this way?	data flows, decisions, compatibility and deployment constraints	architecture decision changes
Task packet	What must this run accomplish?	objective, non-goals, acceptance criteria, allowed writes, current evidence	every task
Source and tests	What is true at this commit?	implementation, schemas, fixtures, observed behavior	every code change

Keep the root AGENTS.md concise. It should point to evidence rather than reproduce a directory tour that becomes obsolete after the next refactor. Good entries name the supported build and test commands, generated files that must not be edited, ownership boundaries, and changes that require explicit review.

Qoder supports imports from an instruction file with @path/to/file, and its rule system can activate guidance always, manually, by model decision, or when matching files are accessed. Use those mechanisms to keep specialized policy near its owner. Avoid contradictory layers because the current documentation does not promise a simple universal winner for every conflict among user, project, local, nested, and rule-file text.

Architecture documents carry rationale that code structure alone may not reveal. Record service boundaries, dependency direction, schemas, rollout sequences, and decisions that intentionally preserve an unusual design. Every document needs an owner and a change trigger. An undated diagram is a lead, not proof.

The task packet should stay temporary. A useful packet includes:

Goal:
Non-goals:
Base commit:
Allowed paths:
Protected paths:
Known entry point:
Relevant architecture records:
Acceptance tests:
Approval-required decisions:
Unknowns to resolve before editing:

Do not add a one-off failure, speculative dependency, or transient stack trace to permanent memory merely because it helped one run. Promote a finding only after a maintainer confirms that future tasks should rely on it.

For the deeper distinction between human rules and generated relationships, see AGENTS.md vs a knowledge graph.

Add Code Indexes and Knowledge Graphs

Use a code index or knowledge graph when the task depends on relationships that are expensive or unsafe to maintain by hand.

Examples include cross-package imports, callers, generated-from relationships, schema consumers, tests that cover a symbol, service ownership, and architecture records that explain a boundary. These relationships change with the repository. Copying them into AGENTS.md creates a second, manually maintained version of the code.

A graph-assisted Qoder workflow can follow this sequence:

identify the behavior, symbol, route, or schema at the center of the task;
query the current structural artifact for direct and transitive relationships;
select the smallest source, document, and test set that can verify those paths;
open the current files in Qoder CLI;
mark every important relationship as confirmed, inferred, or unresolved;
plan edits only after the evidence set covers the expected impact radius.

The graph remains an external context source unless Qoder documents a native integration. Qoder CLI supports MCP servers, so a team may expose its own index through an MCP tool or ordinary commands. Graphify is one option: its documentation describes typed repository relationships, provenance-marked extracted and inferred edges, and queryable artifacts. That is a Graphify capability, not a built-in Qoder claim.

Record the graph's source commit, generation time, parser coverage, ignored paths, and inference policy. Verify high-impact paths against raw source. Static analysis can miss reflection, runtime registration, cross-repository consumers, generated artifacts, and deployment dependencies; semantic inference can be wrong.

Use a plain search index when the task is an exact identifier or error lookup. Use a graph when the task asks what depends on something, how a request travels, or which tests and contracts define an impact boundary. Small repositories and one-off tasks may not justify a graph at all.

Use Context During Agent Planning

Planning should produce an evidence contract, not merely a list of files to edit.

Ask the agent to report:

the behavior and authoritative entry point;
confirmed dependency paths with source locations;
schemas, generated outputs, and external contracts in scope;
focused tests and broader regression checks;
architecture constraints and their owners;
uncertain relationships that require search or approval;
a rollback or containment strategy for high-impact changes.

Qoder CLI's Subagents can help explore these questions without filling the main conversation. Current Subagent documentation says each worker has an isolated context, system prompt, tools, transcript, and compression flow. Its intermediate context does not automatically enter the parent session. Pass the task packet, relevant paths, evidence snapshot, and required return format explicitly.

Use read-only exploration before granting write access to a broad task. Qoder's permission system evaluates tool calls as allow, ask, or deny and covers files, shell commands, web access, MCP tools, and Subagents. Permissions limit actions; they do not prove that an architectural conclusion is correct.

When several workers are involved, give each one a non-overlapping question or component. Let one integration owner reconcile their findings and approve the final plan. A shared graph and AGENTS.md can give workers the same starting evidence, but they do not create a shared conversation or resolve conflicting interpretations.

Before editing, require a plan checkpoint:

Gate	Pass condition
Evidence	Each material dependency claim cites current source, a dated artifact, or an explicit unknown
Scope	Allowed and protected paths are named
Verification	Focused and repository-required tests are listed
Authority	Schema, permission, migration, and public-interface decisions have an owner
Freshness	Instructions, documents, and structural artifacts align with the working commit

Maintenance, Drift, and Risk Notes

Context quality decays unless updates are tied to events.

Use change-coupled maintenance:

update commands and constraints in the pull request that changes them;
update architecture records when a boundary or rationale changes;
rebuild or incrementally refresh structural indexes after relevant merges;
remove task-only assumptions when the task closes;
review local auto-memory before relying on it across machines;
run /memory after major configuration changes to inspect what Qoder loaded;
keep permission and hook controls separate from prose instructions.

Stale context should fail visibly. Include source revisions and timestamps on generated artifacts. Reject a graph that predates a structural change. Flag an architecture document whose owner or last review is unknown. If AGENTS.md names a command that CI no longer runs, fix or remove the instruction rather than teaching the agent an exception.

Treat memory and agent configuration as sensitive review surfaces. A malicious or careless instruction can steer tools toward broad reads, shell execution, or external transmission. Qoder's permission layers and trusted-directory checks reduce action risk, but teams still need least-privilege tool sets, protected configuration review, secret isolation, and approval for network or production operations.

Measure outcomes at the task level: missed dependencies, unsupported assumptions, time to a correct plan, duplicate reads, tokens consumed, reviewer corrections, regressions, and index-refresh cost. A larger context bundle is not automatically a better one.

FAQ

Who approves context changes?

Repository owners should approve shared workflow rules. Architecture owners should approve system boundaries and decision records. Tooling or platform teams should own generated indexes and their refresh process. Security owners should review permissions, hooks, external tools, and protected-path rules. Task authors may create temporary context, but they should not silently redefine durable project policy.

How should teams remove stale assumptions?

Attach an owner and event-driven refresh trigger to every durable artifact. Search for references when code, commands, schemas, or ownership change. Rebuild structural artifacts against the accepted commit, and delete task-local hypotheses when the task closes. Require the agent to label evidence dates and unresolved assumptions in its plan.

What context should be task-only?

Keep the issue objective, temporary debugging output, speculative hypotheses, branch-specific file lists, short-lived rollout facts, and unreviewed agent findings in the task packet or handoff log. Promote only stable, reviewed guidance to AGENTS.md, architecture documents, or shared structural artifacts.

Conclusion

Qoder CLI context engineering works best as a governed evidence pipeline.

Put stable operating rules in AGENTS.md and scoped Qoder rules. Keep architecture intent in owned documents. Use an external index or code graph to select relationship evidence, then verify it against current source and tests. Give each task and Subagent an explicit packet, and require one owner to approve the combined plan.

The decision rule is practical: if a planning claim cannot be traced to current source, a dated artifact, or a named human decision, treat it as an assumption—not repository knowledge.

July 17, 2026

Qoder CLI for Large Codebases

A Qoder CLI large codebase workflow should use AGENTS.md for stable conventions, not as a complete repository model. Large projects also need current source evidence, architecture records, dependency discovery, task boundaries, tests, and review. A separately maintained code knowledge graph can help select related evidence, but it is not documented as a native Qoder CLI feature.

This distinction matters because Qoder CLI rebuilds context for every session. Its official memory system can restore selected instructions and optional saved facts, yet neither mechanism guarantees current knowledge of callers, runtime behavior, design history, or another repository. The engineering problem is therefore evidence management, not simply prompt size.

Why Large Codebases Stress Qoder CLI

A large repository is a changing network rather than a stack of independent files. A seemingly local schema edit may affect generated clients, event consumers, migration jobs, deployment order, and another service maintained by a different team. The relevant relationship may appear in code, configuration, a design decision, or only in a failing integration test.

Qoder CLI can search, read, edit, and run commands, but tool access does not decide which evidence deserves attention. The agent still has to resolve several sources of ambiguity:

two packages may use the same symbol name for different business concepts;
a current test may contradict an old architecture document;
generated files may look editable even though their source lives elsewhere;
dynamic registration may hide a caller from ordinary text search;
a monorepo rule may apply only after a file in a nested directory is accessed;
an external consumer may not exist in the checked-out repository at all.

The last two points are especially important for Qoder repository context. The official memory documentation says Qoder searches upward from the workspace for project memory and stops by default at the Git root. Nested AGENTS.md and matching rules are loaded on demand after Qoder successfully reads a file within that subtree. Starting at the root does not preload every package-specific instruction.

Sessions introduce another boundary. Static memory can reload maintained instructions, while optional auto-memory can save selected reusable facts. A Subagent has its own isolated context and does not receive the parent conversation in full. The main session must pass relevant paths, evidence, constraints, and expected output when delegating work.

What AGENTS.md Can Capture

AGENTS.md is best used as a concise operating contract for humans and coding agents.

Qoder CLI documents the following static-memory scopes:

Scope	Current location	Suitable content
User	`~/.qoder/AGENTS.md`	Personal workflow preferences that apply across projects
Shared project	`<project>/AGENTS.md`	Team commands, repository boundaries, review rules, and architecture orientation
Local project	`<project>/AGENTS.local.md`	Machine-specific URLs, local fixtures, or setup notes that should not be committed
Focused rules	`<project>/.qoder/rules/*/.md`	Topic-specific or file-scoped instructions

The default context filename is AGENTS.md, although Qoder supports changing it through context.fileName. The TUI command /init can initialize or update the project file, and /memory shows the memory available to the session.

For an AGENTS.md large project setup, record facts that remain useful across tasks:

authoritative build, test, format, and release commands;
package ownership and boundaries that filenames do not reveal;
generated-file rules and the location of their sources;
security, compatibility, and review requirements;
links or imports to approved architecture and decision records;
the minimum verification expected before a change is complete.

Qoder also supports @path/to/file imports from AGENTS.md. That is useful for pointing to maintained architecture or testing documents without copying them into one oversized instruction file. Keep the root contract short and route readers to evidence with a clear owner and refresh rule.

The companion Qoder CLI context-engineering guide turns these layers into a maintained team workflow.

What Rule Files Cannot Represent

Rule files describe expectations. They do not automatically derive the repository’s current structure.

The difference becomes clear when a task asks a relational question:

Question	Why a rule file is insufficient	Evidence needed
What calls this handler?	Callers change with code and may be indirect	Symbol references, routes, runtime registration, and source inspection
Which packages will a schema change affect?	Consumers may span languages or repositories	Imports, generated clients, contracts, owners, and integration tests
Why does this boundary exist?	A short rule rarely preserves the full rationale	Current decision record, issue history, and responsible owner
Is this file safe to edit?	Generation chains and deployment rules evolve	Generator config, build scripts, and current repository state
What should be tested?	Risk depends on the actual dependency path	Coverage, callers, contracts, and failure history

Optional auto-memory does not close this gap. Qoder CLI currently enables it only in interactive sessions through QODER_MEMORY=1. It stores selected project background, preferences, feedback, and references as local Markdown. Those notes can become stale, and they do not become team-shared just because the source repository is committed.

Static memory is not enforcement. Qoder directs teams to permissions or Hooks when a command, tool, or path must be blocked. A deny rule and generator-aware test are stronger than prose alone.

Finally, public CLI documentation does not define a deterministic winner for contradictory prose across every user, project, local, nested, and rule layer. Avoid creating conflicts that require the model to guess. If two scopes disagree, resolve the source files and verify the loaded set through /memory.

Where Code Knowledge Graphs Help

A code knowledge graph can complement Qoder CLI by turning repository relationships into a queryable evidence index.

Graph nodes can represent packages, files, symbols, APIs, schemas, tests, owners, and design documents. Typed edges can represent imports, calls, implementations, generation, coverage, ownership, or rationale. The graph can then answer a narrow discovery question before the agent opens current source.

This is an external context layer, not a Qoder CLI capability claim. Qoder CLI supports MCP servers as tool sources, so a team may expose an independently maintained graph through MCP or another approved interface. The agent should still follow every graph result back to source.

A safe graph-guided workflow is:

Freeze the task against a repository revision and define its allowed scope.
Query the graph for the target entity, direct neighbors, cross-package paths, and related tests.
Inspect the source files and documents behind important nodes and edges.
Mark dynamic, inferred, cross-repository, or stale relationships as uncertain.
Produce an impact statement before editing.
Run focused tests, broader contract checks, and human review after the change.

Graphify is one way to generate reusable relationship artifacts from code and supporting documents. Its output should be treated as navigational evidence with provenance, not as an authority that overrides the current repository.

The broader comparison of AGENTS.md and knowledge graphs explains why the two layers should coexist. Developers using another terminal agent can apply the same boundary in the guide to helping Claude Code understand a complex repository.

Limits and Verification Notes

Every context layer can fail, so a large-codebase workflow needs explicit stop conditions.

Use these controls before accepting a repository-wide result:

Check freshness. Record the source commit for architecture documents, generated indexes, and graphs. Refresh them after structural merges.
Confirm loaded instructions. Use /memory when nested or scoped rules matter. Do not assume a file loaded because it exists.
Separate guidance from controls. Put mandatory restrictions in permissions or Hooks, not only prose.
Constrain delegation. Qoder Subagents have isolated contexts and configurable tools and permissions. Pass an evidence packet instead of assuming shared conclusions.
Inspect the installed surface. Built-in Subagents can vary by version and enabled features; /agents or qodercli agents list is the source of truth.
Verify graph edges. Reflection, configuration, generated code, runtime registration, and external systems can escape extraction.
Test behavior. Run the smallest relevant tests first, then contract, integration, or repository-wide checks justified by the impact path.
Require an owner. Architecture, security, persistence, public API, and deployment changes need review by the responsible boundary owner.

No current public benchmark establishes that Qoder CLI understands every large repository or that one configuration wins universally. Evaluate the workflow on representative private tasks: architecture location, dependency tracing, constrained multi-file changes, test selection, and recovery from an incorrect assumption.

FAQ

Who should maintain project memory files?

Assign ownership by subject. The platform or developer-experience team can maintain root commands and common workflow rules; package owners should maintain local boundaries and tests; security and operations owners should approve their policies. Review shared memory through normal pull requests, and name an owner for every imported architecture document.

When should teams refresh repository context?

Refresh context after package moves, public-contract changes, generator updates, dependency rewiring, major migrations, ownership changes, and revised architecture decisions. Also refresh before a high-risk task when the graph or document revision predates the affected code. Event-based refreshes are more reliable than an arbitrary calendar alone.

What belongs outside agent instructions?

Keep secrets, credentials, customer data, transient logs, speculative hypotheses, full source dumps, and fast-changing task status outside shared instructions. Store executable controls in permissions or Hooks, current behavior in source and tests, design rationale in approved records, and structural relationships in a refreshable index or graph.

Conclusion

Qoder CLI can load durable project guidance, scoped rules, optional local memory, and specialized Subagents. Those are useful foundations for AI codebase understanding, but they are not a complete representation of a large repository.

Use AGENTS.md to state stable conventions and route the agent toward maintained evidence. Use source, tests, architecture records, and dependency tooling to establish current facts. Add an external code knowledge graph when repeated cross-file and cross-document relationship questions justify its maintenance cost.

The decision rule is simple: if a repository claim cannot show its source, revision, relationship path, and verification method, treat it as a lead to investigate—not a fact to edit against.

July 17, 2026

Author: Evan

What Supacode Worktrees Solve

Why Isolation Is Not Repository Understanding

Large Codebase Failure Modes

Where Code Knowledge Graphs Fit

Practical Setup Pattern

FAQ

Who should maintain shared repo context?

What should be verified before running parallel agents?

When should teams avoid parallel worktrees?

Conclusion

Quick Verdict

What Git Worktrees Are Good At

What Code Knowledge Graphs Are Good At

Where Coding Agents Confuse the Two

How to Combine Both Layers

FAQ

Can a worktree share graph-backed context safely?

What should not be stored in a knowledge graph?

How should teams audit graph freshness?

Conclusion

Quick Verdict

What OpenCode Skills Are Best For

What Code Knowledge Graphs Are Best For

Workflow Rules vs System Understanding

How to Combine Both Layers

FAQ

Can Skills and graph facts conflict?

Who should approve shared graph updates?

What should stay in a Skill instead?

Conclusion

Quick Verdict

What Long Context Helps With

What Code Knowledge Graphs Add

Repository Tasks That Need Structure

How to Combine Context Windows and Graphs

FAQ

What 2M context claims should be verified?

Can graph retrieval miss important files?

When should teams use both approaches?

Conclusion

Before You Give Macaron a Coding Task

Prepare Architecture and Dependency Context

Add Historical Decisions and Test Signals

Query Context Before Multi-File Edits

Limits, Drift, and Human Review

FAQ

What context should expire first?

Who should review generated repository notes?

How much context is too much?

Conclusion

What Large Codebase Understanding Means

What Long Context Alone Cannot Prove

Tests for Architecture and Dependency Awareness

Failure Modes to Watch

Evidence and Version Notes

FAQ

What should be tested before trusting Macaron-V1?

How should teams record model version results?

When is long context not enough?

Conclusion

Why Kimi K3 Codebase Claims Need Testing

What Would Count as Repository Understanding

A Reproducible Test Plan

Tasks to Include in the Evaluation

Recover the Architecture

Trace a Dependency Path

Predict Change Impact

Execute a Multi-File Refactor

Limits and Evidence Standards

FAQ

What evidence should teams publish?

How should prompts be versioned?

When should tests wait for release?

Conclusion

Why Subagents Rebuild Context

Define Shared Repository Knowledge

Split Planning, Implementation, Testing, and Review Context

Reduce Duplicate Scans and Conflicting Changes

Permission and Drift Risks