Category: AI Coding CLIs

Claude Code is Anthropic's interactive coding product; the Claude Agent SDK lets a team use the agent's tools, loop, and context management from its own Python or TypeScript program. The practical choice is therefore about operating model and control: use Claude Code when a developer is driving an interactive task, and evaluate the SDK when an application, CI job, or internal workflow must orchestrate the agent programmatically.

This is not a model-quality contest. The same underlying agent capabilities can appear in a very different workflow when the team owns the surrounding process, permissions, state, and observability. Start by choosing the smallest surface that can perform the job safely.

Quick Verdict

For Claude Agent SDK vs Claude Code, choose the surface whose operator and controls match the task before comparing implementation details.

Choose Claude Code for a human-led repository session: exploring a codebase, making a bounded change, reviewing the diff, and deciding the next action in the moment. Anthropic describes it as an AI coding assistant available in terminal, IDE, desktop, and web surfaces. Its interactive form is valuable when the developer's judgment is the control plane.

Choose the Claude Agent SDK when the agent must be embedded in a repeatable program. Anthropic's Agent SDK overview says it exposes the same tools, agent loop, and context management that power Claude Code, with Python and TypeScript interfaces. That makes it relevant to a controlled internal application, a CI/CD workflow, or an automation that needs to decide when and how an agent run begins.

The decision rule is simple: if the task's main operator is a developer at an interactive prompt, start with Claude Code. If software must call, constrain, record, and integrate the agent as part of a larger system, assess the SDK. If the actual question is cross-vendor CLI selection, use a dedicated Claude Code vs Codex CLI comparison instead.

Same Foundations, Different Product Boundaries

The naming can be confusing because the products are related. The Claude Code agent SDK is not merely a thin text-completion wrapper. According to Anthropic's documentation, it includes an agent loop, built-in tools, context management, hooks, subagents, Model Context Protocol support, permission controls, and session capabilities. Claude Code uses those broader agent capabilities in an interactive product.

There is also a lower-level boundary to keep clear. Anthropic's SDK and libraries overview distinguishes direct API client SDKs from higher-level agent products. With a client SDK, an application typically sends messages and owns the tool-execution loop it needs. With the Agent SDK, the agent runtime provides built-in tool execution and orchestration features. That is a product-boundary distinction, not a claim that one layer always produces better code.

Layer	Main interface	Who drives the run?	Tool loop	Typical decision
Claude Code	Interactive terminal, IDE, desktop, or web surface	A developer	Product workflow	Help a person complete a repository task
Claude Agent SDK	Python or TypeScript program	The team's application or automation	Agent runtime with documented built-in tools	Embed an agent in a controlled workflow
Client SDK	Direct API library	The team's application	Application-owned when needed	Build a custom model interaction from lower-level primitives

For this reason, search phrases such as “Claude Code SDK” often collapse several different questions. Before deciding, name the expected operator, the required tool boundary, the state that must persist, and the system that will own failures.

Quick Comparison Table

Decision dimension	Claude Code	Claude Agent SDK	What to verify in a pilot
Primary mode	Interactive coding session	Programmatic agent run	Who starts and approves each run?
Integration effort	Lower for a direct developer workflow	Higher because the team integrates it into its program	Where does orchestration code live and who owns it?
Agent tools and context	Available through the product	Available through the SDK's documented runtime	Which tools and context sources are allowed?
Permissions	Product and project controls shape the session	The application configures and operates its own SDK use	Which actions require human approval or must be disallowed?
Observability	Developer can inspect the interactive session	Team can design run records and operational telemetry	What trace, result, and failure data is retained?
Best initial fit	Ad hoc or supervised repository work	Repeatable automation, CI/CD, or an internal agent product	Can the task be made narrow and testable first?

Search terms such as claude code sdk python and claude code sdk typescript are planning language for this comparison. In Anthropic's current Agent SDK documentation, Python and TypeScript are the supported programmatic interfaces. Use the Agent SDK documentation rather than assuming an old example, package name, authentication path, or account entitlement remains valid at implementation time.

When Claude Code Fits Better

Claude Code fits when the important work is interactive judgment. A developer may need to read unexpected test failures, inspect a diff, compare two design options, or stop because a repository convention is unclear. In those moments, a direct session keeps the person close to the evidence and allows the task scope to change without first building an integration layer.

Good starting tasks are bounded and reviewable:

• investigate a failure and report the likely owning files;
• make a small change behind existing tests;
• update documentation after a human has defined the facts;
• propose a plan for a multi-file change without applying it;
• review a generated diff before a person accepts it.

Interactive convenience is not a substitute for repository context. A complex task still needs current source, architecture evidence, tests, and project rules. The guide to helping Claude Code understand a complex repository describes how to supply those layers without treating a large prompt as a complete system model.

When the Claude Agent SDK Fits Better

The Agent SDK fits when the agent is one stage in an application-owned process. Anthropic lists custom applications, CI/CD, production automation, and internal tools among the SDK's use cases. That creates value when a team needs repeatable entry conditions, an explicit tool policy, a standard task contract, or a result that another system can consume.

For teams searching claude code python sdk, the current official name for the programmable surface is the Claude Agent SDK; use its Python interface only after the task contract and execution boundary are clear.

For example, an internal service might prepare an approved task payload, invoke the Agent SDK against a constrained workspace, collect the final artifact and trace, run independent checks, then route the result to a human reviewer. The SDK does not remove the need to build those controls; it is the surface through which a team can place them around an agent run.

The strongest candidates have all three properties:

1. The task starts from a stable, machine-readable input.
2. The desired result can be checked independently of the agent's explanation.
3. A team can state the permitted tools, data, and escalation path in advance.

That may be a narrowly scoped CI investigation or a controlled code-maintenance action. It is not a reason to hand an open-ended production environment to an autonomous process. If the workflow coordinates multiple specialist roles, keep the task boundary and evidence handoff explicit as in an agent swarm codebase context workflow.

Ownership, Access, and Operational Limits

The critical trade-off in Claude Agent SDK vs Claude Code is ownership. An interactive client puts more of the session experience in the product. An SDK integration gives a team more freedom to decide when to run the agent and what surrounds it, but also makes that team responsible for the reliability of the integration.

Before an SDK rollout, name the owner for each boundary:

• Execution: Which process, workspace, and environment run the agent?
• Tool policy: Which read, write, shell, network, or MCP actions are available, and which need approval?
• Secrets and data: What credentials are exposed, how are they scoped, and what may be retained in logs?
• State: Which session or task records are durable, and when do they expire?
• Evidence: Which inputs, tool calls, tests, final artifacts, and human decisions are retained for diagnosis?
• Change control: Who may update the model choice, instructions, tools, or permissions?

A team assessing a claude code sdk typescript integration should make the same ownership decision before wiring the TypeScript interface into a wider automation path.

The official documentation confirms that the Agent SDK supports permissions, hooks, sessions, subagents, MCP, and built-in tools. It does not answer the policy choices for a particular organization. Likewise, pricing, account eligibility, authentication configuration, regional availability, and feature limits can change. Verify those operational facts in current official documentation and the intended account before treating an example as deployable policy.

Smallest Safe Pilot

Run a pilot that tests the operating model, not just a happy-path demo.

1. Select one narrow task with a pinned repository revision and an independently checkable result.
2. Begin with read-only or tightly allowlisted tools; do not expose broad credentials for convenience.
3. Record the inputs, instruction revision, available tools, important tool calls, final result, and test output.
4. Require a human to review every changed artifact during the first run set.
5. Expand only after the same task type behaves acceptably across varied cases and failures are understood.

For codebases that need repeated structural retrieval, pair the pilot with a current project-memory layer rather than copying a large repository into every run. Graphify is one approach to supplying source-linked repository relationships; it does not remove the need for a bounded task, tests, and human approval.

FAQ

What is the Claude Code SDK?

In this comparison, “Claude Code SDK” refers to the programmable product that Anthropic officially calls the Claude Agent SDK. It exposes agent capabilities that power Claude Code through Python and TypeScript, while Claude Code itself is the interactive coding product. Use the official overview for current implementation details and terminology.

Conclusion

Use Claude Code when a developer should drive the coding session. Use the Claude Agent SDK when your own program must orchestrate a bounded, observable agent workflow. Start with the smallest safe pilot and expand only when the team can explain the task contract, tool boundary, evidence trail, and failure owner.

Claude Code repeated repository scanning is a retrieval problem before it is a token problem. A workflow wastes context when each run rediscovers the same module boundaries, definitions, callers, and tests without preserving a source revision or reusing a trusted project map. The remedy is not “never scan again.” It is to scope each task, persist reusable structural candidates with provenance, retrieve only relevant evidence, and force rescans when freshness conditions fail.

In this article, recipe is editorial shorthand for a repeatable workflow. Claude Code implements reusable workflows as Skills; it does not document a built-in repository-map cache.

Why Recipes Re-Read the Same Repo

Claude Code repeated repository scanning usually begins when a reusable recipe has no persisted, revision-aware map of the structure it is about to inspect.

Repeated workflows often begin with broad instructions: inspect the repository, understand the architecture, then find the relevant code. That sequence is defensible for a new codebase, but expensive when every task repeats it.

Three things cause the loop:

• the recipe has no bounded target or stop condition;
• prior findings live only in conversation text and lack a revision;
• stable guidance, procedures, and mutable code facts are mixed in one always-loaded file.

Claude Code context optimization starts by separating those layers. Put stable conventions and essential commands in scoped CLAUDE.md files. Put specialized procedures in on-demand Skills. Keep current module, dependency, and test relationships in source-backed maps or an external index, not as timeless instructions.

Anthropic's large-codebase guidance recommends starting Claude in the relevant directory, using nested instructions, excluding generated or vendor paths, and using code intelligence for definitions and references. These measures reduce unrelated file reads without claiming that previous analysis remains correct forever.

For repeatable architecture and impact workflows, see Claude Code recipes for large codebases. The key addition here is measurement: prove that retrieval became smaller while review quality did not decline.

Where Context and Token Cost Accumulates

Effective Claude Code context optimization starts by measuring every context surface, not only the source files opened during the task.

Context grows from more than source files. Instructions, conversation turns, tool inputs and outputs, file reads, search results, and Skill content all consume space. Anthropic notes that large repositories can fill context with unrelated instructions and file reads, increasing token use and degrading performance.

The cost model needs qualification. Claude Code uses prompt caching and automatic compaction. API users are charged by token consumption, while Pro and Max usage is included in the subscription plan; therefore there is no universal dollar cost for “one repository scan.” Anthropic's cost documentation points users to /usage for session usage data and recommends moving specialized procedures from always-loaded CLAUDE.md content into Skills.

Measure the retrieval pattern instead of inventing a savings percentage:

Metric	What it reveals
file-read and search-tool count	breadth of repository inspection
input and cache-read tokens	context consumed or reused
time to first evidence-backed answer	retrieval latency
unsupported or omitted edges found in review	quality cost
age and indexed revision of reused maps	freshness exposure

Track these values for comparable tasks at a pinned commit. Lower token use accompanied by more missed dependencies is not an optimization.

Persist Project Maps and Dependency Graphs

A persisted project map is a team artifact or external index. It is not guaranteed Claude Code memory. At minimum, record modules, entry points, relation types, tests, source locations, repository revision, generation time, and known coverage gaps.

A search such as “Claude Code Graphify” usually reflects interest in attaching a persistent structural layer to Claude's workflow. Graphify can be evaluated as one possible external code-graph layer, but it should be treated as a separately operated source of candidate relationships, not a native Claude Code feature. The broader architecture is covered in knowledge graphs for AI coding assistants.

Persist only facts that are useful across tasks. A useful map might answer “which packages consume this schema?” or “which tests exercise this entry point?” It should not store a long narrative that every run must reread.

For each stored edge, keep:

• source and target identity;
• relation type and direction;
• source file or extraction evidence;
• indexed commit or content hash;
• extraction method and time;
• coverage or uncertainty note.

An external index may be exposed to Claude Code through MCP, a CLI, or another controlled tool. Query it for a small candidate set, then verify high-impact results against the current source revision.

Retrieve Only Task-Relevant Files

Begin each task with a retrieval plan:

1. Pin the revision and name the target behavior, symbol, or module.
2. Query a project map for candidate entry points and one relation type.
3. Open the defining source and the nearest relevant configuration.
4. Use code intelligence for definitions and references where available.
5. Read tests that claim to exercise the selected paths.
6. Expand only when evidence conflicts or a freshness rule fires.

This sequence turns a broad scan into progressive retrieval. It also keeps code intelligence, graph queries, text search, and tests in their appropriate roles. Definitions and references can be precise for supported languages; text search catches configuration and strings; graphs support reverse and cross-module discovery; tests provide behavioral evidence.

Use scoped Skills so the full procedure loads only when needed. Use nested CLAUDE.md or path-scoped rules for local conventions rather than placing every package's guidance in the root file. After context compaction, Claude Code reinjects some context surfaces according to documented limits, so concise, well-placed instructions still matter; context-window behavior should not be mistaken for a durable code index.

Risks and Freshness Checks

Less reading increases dependence on what was retained. A stale map can be more dangerous than a fresh scan because it looks intentional.

Force a refresh when dependency manifests, public schemas, routing, plugin registration, generated clients, build configuration, migrations, or ownership boundaries change. Also refresh when the stored revision is not an ancestor of the working revision, the index lacks the target language, or source verification contradicts a returned edge.

Use different expiry policies. Stable module descriptions may survive many commits with spot checks. Call edges, route registration, generated APIs, and tests around an active refactor should expire quickly. Runtime-discovered relationships need the shortest confidence window unless they are continuously observed.

Keep a rescan budget rather than a no-rescan rule. Broad scans are appropriate for an unfamiliar repository, a major architecture migration, a suspected coverage gap, or a failed freshness check. For routine changes, retrieve a small map slice and validate it against source.

Finally, audit omissions. Sample changes after merge and ask whether the retrieval plan missed a dependent module, relevant test, or operational boundary. Feed that failure into the map schema, freshness triggers, or recipe—not into an unsupported claim that more context is always better.

FAQ

When should a recipe force a rescan?

Force one when the pinned revision and stored map diverge materially, relevant manifests or schemas changed, the target uses unsupported dynamic behavior, or source contradicts the map. Also rescan after a known extraction failure or when the task crosses an unindexed repository boundary.

What maps should expire quickly?

Runtime registration, call chains around active refactors, generated interfaces, routes, feature flags, migrations, and test-to-behavior mappings should have short expiry windows. Stable ownership or high-level module-purpose records can last longer if they retain provenance and periodic review.

How should teams measure reduced reading?

Compare similar tasks at pinned revisions. Track file reads, searches, input and cache-read tokens, time to first cited evidence, map age, and omissions found in review. Use a baseline and report distributions, not one favorable run or a universal savings percentage.

claude code plan mode

Plan mode can help keep an analysis read-only while Claude explores and proposes a plan, but it does not create a persistent repository map. Teams still need scoped retrieval, freshness checks, evidence review, and appropriate permission rules for the surrounding workflow.

Conclusion

Reduce Claude Code repeated repository scanning by reusing small, revisioned maps and retrieving evidence progressively. Measure both context reduction and missed relationships. Rescan when freshness fails, and never let a persisted map outrank current source, configuration, tests, or responsible human review.

A Claude Code repository analysis Skill should standardize how an agent finds entry points, module relationships, dependencies, tests, and uncertainty. It should not contain a supposedly complete map of the repository. Put the Skill at .claude/skills/repository-analysis/SKILL.md, commit it with the project, give it a specific description, and test its evidence contract against a fixture repository before using it for consequential change planning.

The useful unit is one bounded workflow: receive a target and revision, collect source-backed relationships, label unsupported edges, map tests and risk, then return a predictable report for human review.

Before Building the Skill

A Claude Code repository analysis Skill needs a bounded owner and evidence contract. “Understand the repository” is too broad. A better contract is: “Given a symbol, module, endpoint, or change proposal, identify its entry points, direct relationships, relevant tests, and unresolved risks within a stated scope.”

A codebase Skill should own the repeatable procedure, not a mutable snapshot of repository relationships. That separation keeps the workflow reviewable as the code changes.

Write down the inputs before writing SKILL.md:

• target symbol, behavior, or directory;
• repository revision and working directory;
• excluded paths such as vendored or generated output;
• supported languages and available code-intelligence tools;
• required output fields and verification checks;
• escalation conditions for dynamic or inaccessible evidence.

Keep responsibilities separate. CLAUDE.md is appropriate for stable repository conventions and build commands. A Skill is the on-demand procedure. Current module and dependency relationships must still come from source, code intelligence, tests, or an external knowledge graph for AI coding assistants. For a deeper layer comparison, see Claude Code recipes vs knowledge graph.

Claude Code Skills expose names and descriptions for discovery, then load the full body when used. That makes the description part of the interface: say when the Skill should activate, what target it expects, and what output it produces.

Define the Repository Analysis Workflow

Start the codebase Skill with a small SKILL.md rather than a large reference manual:

---
name: repository-analysis
description: Analyze a specified repository symbol, module, or change surface and return source-backed entry points, relationships, tests, risks, and unknowns. Use for bounded repository analysis before planning a change.
---

1. Confirm the target, revision, and directories in scope.
2. Locate definitions and executable or configured entry points.
3. Trace direct inbound and outbound relationships.
4. Inspect indirect registration and generated boundaries separately.
5. Map specific tests to claimed behaviors.
6. Return evidence tables, unknowns, and verification steps.

This is deliberately procedural. Do not encode facts such as “service A always calls service B” in the Skill body unless they are stable architectural rules with an owner. Ask the Skill to rediscover mutable relations from evidence.

This Claude Code repository analysis Skill example therefore freezes the output contract while leaving current facts to source-backed retrieval.

Freeze an output schema so results can be compared across runs:

Field	Required content
Scope	revision, target, included and excluded paths
Entry points	file, symbol, trigger type, evidence
Relationships	from, relation, to, direct/inferred/unknown
Tests	test name, file, behavior or edge covered
Risks	failure mode, affected boundary, proposed check
Unknowns	missing tool, dynamic behavior, contradictory evidence

Require the Skill to stop and ask for scope when the target is ambiguous. A repeatable workflow that begins from the wrong boundary only makes a wrong answer more consistent.

Add Module, Dependency, and Entry-Point Queries

A practical Claude Code repository analysis Skill example should define query classes, not invent commands that may not exist in the reader's environment.

For module discovery, locate package manifests, build targets, module declarations, and top-level imports. Return ownership and responsibility only when supported by source, repository documentation, or an ownership file. Directory names are hints, not architectural proof.

For entry points, inspect executable mains, exported handlers, routes, jobs, event consumers, plugin registration, configuration loaders, and deployment manifests relevant to the target. Ask for the file and symbol that establishes each entry. Treat convention-based framework discovery as an explicit relation, not an ordinary function call.

For dependencies, prefer definitions and references from a configured code-intelligence plugin. Supplement those results with text search for configuration keys, strings, templates, schemas, and generated boundaries. The Skill should distinguish import dependency, call, registration, publication, data read/write, and deployment coupling; collapsing all of them into “depends on” makes later impact analysis unreliable.

For an external graph or search index, define the question and the evidence returned: indexed revision, source location, relation type, and query time. Claude Code can reach external services through MCP, but an MCP connection does not make the graph native or guarantee its correctness.

End every query block with a verification instruction. For example: reopen the defining file, reproduce one reference lookup, and flag any result that points outside the declared revision or scope.

Map Tests and Risk Areas

Make test mapping an evidence task. A test with a matching filename may not execute the path under review, while a contract or integration test in another package may be the strongest check.

Require these fields for each candidate test: test name, file, setup or fixture, entry point exercised, assertion relevant to the target, and coverage status. Use statuses such as directly exercises, covers an adjacent contract, name match only, and not found.

Then classify risk by boundary rather than by generic severity:

• public API or serialized schema compatibility;
• migration and persistent state behavior;
• authorization, tenancy, or secret handling;
• asynchronous delivery, retry, and idempotency;
• generated client or build artifact drift;
• deployment configuration and rollback.

For each material risk, request one existing check and one missing or proposed check. The Skill may recommend a test, but it should not edit code or execute a mutating command during an analysis-only run.

Test the Skill itself on a fixture repository with known entry points, callers, and tests. Include negative cases: aliases, dynamic registration, generated code, an unrelated name match, and one intentionally unknowable edge. The expected output must include “unknown”; otherwise the test rewards confident guessing.

Maintenance and Permission Risks

Assign an owner and review triggers. Update the Skill when its evidence schema, supported tooling, repository layout conventions, or risk policy changes. Do not update it merely to cache a one-off discovery; that belongs in source-backed documentation or a refreshed index.

Permissions need precise wording. The allowed-tools field can pre-approve listed tools while a Skill is active, but Anthropic states that it does not restrict other tools. It is not a read-only sandbox. For an analysis-only workflow, use organization or project permission rules, including deny rules or an appropriate permission mode, and keep workspace trust requirements in mind.

Avoid pre-approving broad shell access simply to make the Skill convenient. Prefer read, search, code-intelligence, and explicitly scoped graph queries. Separate the analysis Skill from any implementation or deployment Skill so a request for impact mapping cannot silently become a mutation workflow.

Operational checks can show whether the Skill loads, not whether its claims are correct. Claude Code's /context view helps inspect loaded configuration, and the skill_activated OpenTelemetry event can indicate invocation in supported monitoring setups. Neither proves that a call edge or test mapping is factual; fixture tests and source review remain necessary.

Version the Skill and its fixtures together. Record the Claude Code version, available code-intelligence plugins, permission mode, fixture commit, and expected evidence schema for every acceptance run. Re-run the suite after changing frontmatter, tool adapters, repository conventions, or a permission rule. Include one denied path and one stale external-index response so the Skill proves it can stop safely, not only complete a happy path. In production sampling, track unsupported relationship claims, missed tests, scope clarifications, and review corrections. A lower file-read count is useful only when these correctness measures remain stable.

Keep a rollback path. If a revised Skill increases false confidence or silently widens its tools, restore the prior reviewed version and preserve the failing output as a regression fixture. Treat Skill maintenance like interface maintenance, not prompt polishing.

FAQ

Who should approve Skill updates?

The repository or platform team can own the shared workflow, but affected module owners should approve changes to scope, evidence requirements, and risk rules. Permission changes deserve a security or tooling-owner review. Use normal code review and require an updated fixture result for behavioral changes.

What should the Skill not automate?

It should not edit code, change permissions, run deployment commands, approve its own evidence, or present inferred relationships as authoritative. Keep implementation, migration, and release operations outside an analysis-only Skill unless the team creates a separately reviewed workflow.

How should teams test Skill output?

Use a versioned fixture repository with known definitions, callers, indirect registrations, tests, and missing edges. Compare structured output, not prose style. Also sample the Skill against real changes and record false relationships, missed tests, unsupported claims, and time-to-evidence.

claude code mcp

MCP is one way Claude Code connects to external tools and data sources. A repository analysis Skill can request a scoped MCP query to a code-search or graph service, then verify returned edges against source. The Skill and the MCP server have separate permissions, ownership, and freshness concerns.

Conclusion

A sound Claude Code repository analysis Skill is a small, reviewable procedure with a strict evidence schema. Keep mutable repository facts outside the Skill, require explicit unknowns, test the workflow against known and negative cases, and enforce read-only behavior through actual permission controls rather than suggestive frontmatter.

Claude Code recipes for large codebases should be repeatable analysis workflows, not collections of clever prompts. In this article, recipe is editorial shorthand. Anthropic's current product surface is a Skill; legacy custom commands still work but have been merged into Skills. A useful recipe tells Claude what scope to inspect, what evidence to return, what uncertainty to preserve, and how a reviewer can verify the result.

The three recipes below cover architecture orientation, module and call-chain analysis, and impact plus test mapping. None assumes that Claude Code has a built-in repository graph. They work with source reads and code intelligence, and can optionally query an external, source-attributed index.

Before Using Recipes on a Large Codebase

Claude Code recipes for large codebases should begin by reducing the search surface. Anthropic's large-codebase guidance recommends starting Claude in the directory relevant to the task, using nested CLAUDE.md files for local conventions, excluding generated or vendor directories, and adding code-intelligence plugins where supported. That setup matters more than making a repository analysis prompt longer.

Define four fields before running any recipe:

1. Scope: repository commit, workspace or package boundaries, and directories that are out of scope.
2. Question: one architecture, call-chain, or impact question, stated so a reviewer can tell when it has been answered.
3. Evidence contract: file paths, symbols, line-level references where practical, relevant tests, and commands or tools used.
4. Stop conditions: missing language support, generated indirection, runtime registration, unavailable services, or contradictory evidence.

This turns the prompt into reviewable work. It also prevents a common failure mode: Claude reads broadly, produces a plausible summary, and leaves no way to distinguish code evidence from inference.

Treat repository analysis prompts as evidence contracts rather than prose templates. The required scope, output fields, and stop conditions matter more than stylistic wording.

Stable conventions belong in CLAUDE.md; the procedure belongs in a Skill; current dependency and call relationships still need to come from code, code intelligence, or an external knowledge graph for AI coding assistants. If your team wants to package the procedure, see the Claude Code repository analysis Skill.

Recipe for Architecture Overview

Architecture-focused repository analysis prompts should build a bounded orientation map, not summarize every directory. Give Claude the commit and scope, then ask it to identify:

A search for “Claude Code recipes for large codebases Reddit” may provide examples, but the architecture recipe still needs repository-specific evidence and review criteria.

• user-facing or machine-facing entry points;
• top-level modules and the responsibility of each;
• dependency direction between those modules;
• shared infrastructure and cross-cutting concerns;
• configuration, build, and deployment boundaries relevant to the target area;
• unresolved areas that would require runtime evidence or an owner interview.

Require a compact output table with component, responsibility, entry evidence, outbound dependency, and confidence. The confidence column is not a probability score. It should use explicit labels such as direct source evidence, supported inference, or unknown.

A practical instruction is:

Start from documented and executable entry points. Trace only enough imports, registrations, and configuration to explain the target system boundary. Cite a file and symbol for every component. Mark runtime-discovered relationships as unknown unless a test, configuration file, or code-intelligence result supports them. End with three verification checks a maintainer can run.

Do not ask for “the complete architecture.” In a monorepo, that request encourages breadth without proof. Ask for the smallest map that answers the task, then expand one uncertain boundary at a time. The deliverable should let a new reviewer challenge individual edges instead of accepting one polished narrative.

Recipe for Module and Call-Chain Analysis

A search such as “Claude Code recipes for large codebases Reddit” often reflects a reasonable need for reusable examples. The useful pattern, however, is not a copied prompt. It is a call-chain contract that separates direct evidence from possible runtime behavior.

Start with one symbol, endpoint, event, job, or configuration key. Ask Claude to return:

• its definition and public entry points;
• direct callers or references found through code intelligence;
• adapters, registrations, dependency-injection bindings, and generated layers;
• outbound calls and observable side effects;
• branches that are indirect, dynamic, or not statically resolvable;
• the files and tests a reviewer should open next.

Code intelligence can provide precise definition and reference lookups for supported languages. Text search remains useful for strings, configuration, templates, and languages without a configured server. Neither technique alone proves a complete runtime call graph.

Use an edge table rather than prose:

From	Relation	To	Evidence	Status
symbol or entry point	calls, registers, publishes, reads	target	file, symbol, lookup	direct, inferred, unknown

Then require a reverse check: choose one claimed downstream effect and trace back to the original entry point independently. If the two paths disagree, the recipe should report the disagreement rather than smooth it over.

Recipe for Impact and Test Mapping

Impact analysis begins with a proposed change, not with the whole repository. State the symbol, schema, API, configuration, or behavior that may change. Ask Claude to map four surfaces: direct dependents, compatibility boundaries, stateful or operational effects, and tests.

The output should distinguish:

• compile-time impact: imports, types, interfaces, generated clients, and build targets;
• runtime impact: registrations, queues, routes, feature flags, migrations, and external integrations;
• behavioral impact: assumptions encoded in callers, validation, error handling, and fallback paths;
• verification coverage: unit, integration, contract, end-to-end, and operational checks.

A test file is not automatically evidence that a behavior is covered. Require Claude to cite the specific test name and explain which edge or behavior it exercises. Also ask for negative cases: tests that appear related by filename but do not reach the changed path, and important paths for which no test was found.

Finish with a review matrix: risk, affected evidence, existing check, missing check, owner. The owner can be a team or CODEOWNERS path; do not invent a person. For a high-risk boundary, the recipe should recommend a human verification step or a targeted test, not a larger speculative scan.

If an external code graph is available, query it for candidate dependents, then confirm the important edges against the pinned source revision. Anthropic documents exposing an existing search or RAG index through MCP; that is an integration option, not a native Claude Code index.

Limits, Drift, and Review Notes

A recipe controls procedure. It does not make stale instructions, incomplete language-server results, or an outdated graph correct. Treat every stored project map as a snapshot with a source commit and generation time. Force revalidation when dependency manifests, routing, schemas, build configuration, or generated interfaces change.

Review output at three levels:

• Evidence validity: do cited paths and symbols exist at the stated revision?
• Edge validity: does the source support the claimed direction and relation?
• Coverage: did the recipe search the relevant static, configuration, generated, and runtime-registration surfaces?

Keep unknowns visible. Dynamic dispatch, reflection, generated code, macro expansion, and runtime configuration can defeat static inspection. A mature result may contain more qualified uncertainty than an early result; that is often an improvement.

Finally, keep the recipe short enough to maintain. Put stable repository facts in scoped CLAUDE.md files, reusable procedures in Skills, and current structural claims in source-backed evidence. When any of those layers changes, review its owner and revision independently.

FAQ

Who should maintain repository recipes?

The team that owns the affected architecture boundary should maintain the recipe, with one named role responsible for review. Platform teams can own the shared evidence schema, but module owners should approve scope, special cases, and verification rules. Store the recipe with the repository so changes are reviewed beside code.

When should a recipe call a graph query?

Call an external graph when the question spans many modules, requires reverse dependency lookup, or repeats often enough that broad source scanning is wasteful. Use it to generate candidate relationships, not final truth. Check high-impact edges against source at the graph's indexed commit.

How should teams audit recipe output?

Sample cited files and symbols, reproduce at least one lookup, reverse-trace one important edge, and inspect every “unknown.” Compare the result with a small fixture or a change whose impact is already understood. Record false edges, omissions, and stale sources so the recipe or context layer can be corrected.

what is claude code

Claude Code is Anthropic's coding agent for terminal, IDE, desktop, and web workflows. It can read repositories, use tools, follow CLAUDE.md instructions, and load Skills. Those features support analysis workflows, but they do not turn every repository into an automatically maintained code graph.

Conclusion

The best Claude Code recipes for large codebases are narrow, evidence-producing, and comfortable reporting uncertainty. Start with one bounded question, require files and symbols for every important claim, and end with a human-verifiable check. Save repeated procedures as Skills, and treat code intelligence or an external graph as evidence sources whose coverage and freshness still need review.

To switch Codex provider context safely, change provider and authentication at user scope, treat old sessions as provider-bound records, and rehydrate the task from revision-bound repository evidence. A working route proves connectivity. It does not transfer the previous model’s architecture judgments, file selection, dependency understanding, or private reasoning.

This guide separates the official Codex configuration model from third-party routing features and from the evidence a model needs to continue a large repository task.

Quick Verdict

The correct switch procedure depends on which layer changed.

Layer	What can move	What does not move automatically	Safe response
Provider configuration	Model provider ID, base URL, wire API, headers, and credential source	Repository conclusions	Configure at user scope and verify with a new process
Third-party route	Active CC Switch profile, local proxy, protocol conversion, model mapping	Equivalent provider behavior	Confirm provider, protocol, route, and model separately
Session history	Visibility, record classification, readable plain-text history	Backend-specific encrypted reasoning or reliable continuation	Resume on the original backend or start a fresh session
Repository evidence	Commit-pinned paths, symbols, dependencies, tests, owners, decisions	Private chain of thought	Build a reviewed, provider-neutral task packet

OpenAI’s Codex documentation defines custom model providers in config.toml: a provider can specify its base URL, wire API, authentication, and headers, and model_provider selects it. Provider switching therefore changes the connection contract. It does not define an automatic migration of task state.

What a Codex Provider Switch Changes

Official Codex supports custom providers and profiles. The advanced configuration guide shows model_provider and [model_providers.<id>] entries for user configuration, including environment-key and command-backed authentication. It also documents one-run overrides and named profile files under ~/.codex/.

Provider and authentication configuration has an important security boundary: project .codex/config.toml files cannot override keys that redirect credentials or change provider authentication. Codex ignores project-local model_provider, model_providers, openai_base_url, and related protected keys. Put provider and authentication settings in user-level ~/.codex/config.toml or a user profile, not in repository configuration.

A third-party manager can edit or route those settings, but it does not become an official Codex capability. CC Switch is a community project that manages provider profiles and can put a local protocol-conversion route between Codex and an upstream. Its Kimi guide converts Codex Responses requests to Chat Completions and back. Its Claude guide converts between Codex Responses and Anthropic Messages. Both recommend restarting Codex after switching so the running process reloads configuration and model-catalog state.

Codex++ has a different boundary. Its own repository calls it an unofficial tweak loader for the Codex desktop app. It patches the local app to load UI and main-process tweaks; it says it does not replace Codex or proxy the user’s account. Codex++ is not a provider switcher and should not be cited as a way to transfer codebase context.

After any provider change, verify:

• the effective user-level model_provider;
• the selected model and provider-specific model ID;
• direct connection versus local proxy;
• wire protocol and conversion path;
• credential source without printing the credential;
• whether the active CLI process loaded the new configuration;
• tool availability, sandbox, and approval behavior.

Session History Is Not Repository Understanding

Session history preserves records, not a portable mental model. CC Switch’s unified Codex session-history feature illustrates the difference precisely. Its guide says unification changes only the session’s model_provider classification tag, optionally migrating existing records after making backups. Official and third-party sessions can then appear in one history list.

That normalization does not make reasoning provider-neutral. The guide warns that cross-provider resume may fail because encrypted_content can be decrypted only by the backend that created it. A session can be visible and readable but not continuable through the new provider.

Even when resume works, the transcript may contain:

• conclusions tied to an older commit or dirty worktree;
• tool output that no longer reflects current files;
• model-specific interpretations presented without provenance;
• rejected paths that look like recommendations when excerpted;
• an incomplete list of consumers, tests, or generated artifacts;
• assumptions about tool calling, context capacity, or output format.

Therefore, do not equate “CC Switch repository memory” with repository understanding. CC Switch can expose session records, provider configuration, MCP, and Skills. Its public materials do not describe a native, provider-neutral code graph that transfers verified system relationships into a new model.

For cross-provider work, use old history to recover task chronology and unresolved questions. Rebuild important claims from source and tests.

Build a Model-Independent Repository Evidence Layer

A model-independent layer stores facts that another provider can inspect without relying on the old backend’s private reasoning. It should combine source-controlled instructions, architecture decisions, generated structural evidence, task boundaries, and verification output.

Build it in five parts:

1. Identity: repository, branch or worktree, commit, dirty-file list, and task owner.
2. Scope: requested outcome, non-goals, protected paths, acceptance criteria, and allowed external systems.
3. Structure: relevant packages, files, symbols, imports, calls, schemas, generated artifacts, tests, owners, and decision records.
4. Provenance: source location, graph revision, extractor version, deterministic or inferred status, and freshness timestamp.
5. Verification: commands already run, exact results, known failures, remaining risks, and required approvals.

The graph is a retrieval aid, not the final authority. Dynamic registration, reflection, configuration, generated code, and out-of-repository consumers can be absent. Make the destination model open source behind high-impact edges and rerun tests before it edits.

Keep the artifact provider-neutral. Do not store opaque reasoning ciphertext, vendor-specific token traces, or unsupported summaries as repository facts. Label a statement as one of:

• Verified fact: confirmed in source, an authoritative document, or a reproducible command.
• Model-specific hypothesis: a useful interpretation that still needs evidence.
• Human decision: an approved constraint, exception, or trade-off with an owner.
• Stale or disproved: retained only for audit history and excluded from the active plan.

The generic shared-context guide remains the canonical owner for cross-tool repository context. The CC Switch codebase-context guide covers CC Switch-specific failure modes.

Provider Switch Checklist

Use the switch as a controlled handoff, not a mid-sentence backend substitution.

Prepare

• Pin the commit and capture uncommitted changes.
• Save the goal, non-goals, acceptance criteria, and current plan.
• Export task-relevant graph evidence with source locations.
• Mark model-specific assumptions and unresolved failures.
• Record the old provider, model, route, and session ID.
• Remove secrets and sensitive data from the handoff.

Switch

• Change provider/auth only in user-level configuration or an authorized third-party manager.
• If CC Switch routing is involved, confirm the provider card, local route, app-level toggle, protocol, and model mapping.
• Restart Codex when the process must reload configuration or model catalogs.
• Do not use Codex++ as evidence that provider routing changed.

Validate

• Confirm effective provider and model without exposing credentials.
• Start a new session when cross-provider resume fails or provenance is ambiguous.
• Load the provider-neutral task packet.
• Reopen source behind high-impact relationships.
• Restate the plan and compare it with the saved constraints.
• Rerun focused tests, then broader repository-required checks.
• Review the final diff for assumptions introduced after the switch.

If the new model cannot reproduce the old plan from current evidence, stop and plan again. Continuing from an unverifiable summary is faster only until it produces the wrong change.

FAQ

What should be retested after switching providers?

Retest the behavior the task changes, protocol-sensitive tool calls, structured outputs, patch application, and every repository-required build, type, lint, contract, integration, or security check relevant to the diff. Also repeat discovery checks for callers, generated artifacts, schemas, and tests if the old list was model-derived rather than source-linked.

How should model-specific assumptions be marked?

Label them explicitly as hypotheses with the originating provider, model, session, repository revision, evidence inspected, and required confirmation. Promote an assumption to a verified fact only after current source, authoritative documentation, or a reproducible test supports it. Keep human decisions separate and name their owner.

When should a task restart from planning?

Restart from planning when the session cannot resume, the repository revision changed, the new provider disputes a high-impact assumption, graph evidence is stale, required tools differ, acceptance criteria are unclear, or focused tests contradict the inherited plan. Planning should also restart when the old task packet lacks provenance for files, dependencies, or safety constraints.

Conclusion

Switching Codex providers changes configuration and routing, not repository understanding. Official Codex protects provider and authentication settings at user scope; CC Switch can manage third-party routes and session visibility; Codex++ loads desktop tweaks. These are separate tools with separate boundaries.

Carry the task through a model-independent evidence layer: pin the revision, preserve source-linked structure, label assumptions, and record tests. Then let the new provider verify that packet in a fresh session. If it cannot reproduce the plan, restart planning before changing code.

CodeWhale context optimization should reduce repeated repository discovery, not hide evidence from the agent. Build a revision-bound module and dependency map, link tests and entry points, retrieve a small packet for each task, and measure search and startup behavior against a baseline. Keep current source and verification available whenever cached context is stale or incomplete.

Codewhale v0.9.0 provides model and provider routing, saved sessions, compaction, task-scoped Fleet inputs, and subagents. It does not document a native repository index, code graph, or Fleet-wide shared repository memory. In this guide, indexing is an external Graphify-style evidence layer connected to Codewhale’s documented tools and context inputs.

Why CodeWhale Agents Re-Read Repos

Repeated reading is often a rational response to missing or untrusted context. A new worker must discover where the subsystem lives, which symbols matter, what calls them, and which tests establish behavior. If no reusable evidence identifies those paths, searching again is safer than trusting an old summary.

Codewhale’s subagent behavior makes the boundary explicit. The agent path starts fresh by default with the role prompt and assigned task. Context is carried only when fork_context: true is requested. Fresh sessions are appropriate for independent exploration, but several fresh agents can repeat the same rg, file-open, and dependency-tracing steps.

Provider switching creates a related cost. Codewhale can select models and providers through a common runtime, and Fleet profiles can pin a route. The incoming model can receive saved transcript text, configured instructions, or an explicit task packet. It does not inherit another provider’s hidden reasoning. Rebuilding repository understanding from current evidence may therefore dominate startup.

Saved sessions and /compact help with transcript continuity. The user guide describes compaction as a way to recover context budget by summarizing long history. That is useful inside a session, but a compacted transcript is not an automatically refreshed architecture index.

Optimization begins by classifying repeated work:

• necessary rereads validate changed or high-risk source;
• avoidable discovery repeatedly locates stable module boundaries and entry points;
• stale-context recovery corrects an old map or summary;
• provider-specific interpretation compares how models reason over the same evidence.

The target is the second category. Removing the first would make the workflow faster but less trustworthy.

Build a Module and Dependency Map

Generate a small, queryable repository map from a pinned commit. Start with information that is expensive to rediscover and likely to be useful across tasks:

• packages, services, libraries, generated areas, and their owners;
• public and internal entry points;
• import, call, registration, schema, event, and configuration relationships;
• build and deployment boundaries;
• architecture records linked to affected code;
• cross-repository contracts and the location of their source of truth.

Every record should contain provenance. A parsed import can point to a file and line. A generated-client edge should name its generator. An inferred runtime relationship should carry lower confidence and an explanation. The complete map should identify its repository revision and generation method.

Do not load the whole graph into every prompt. Query it by task. For “change retry behavior in the queue consumer,” retrieve the consumer, its configuration, retry scheduler, error types, telemetry path, owners, and tests. Let Codewhale open those current files and expand only when evidence indicates another dependency.

Codewhale’s v0.9.0 configuration also documents an optional cache-maximal working-set mode that materializes the full current contents of top active files to stabilize provider prefix caching. That is a prompt-cache optimization for selected files, not a repository map. Use it only after evidence selection; it cannot tell the task which files were missed.

The CodeWhale Large Codebase Context guide explains the model-independent evidence contract behind this map.

Index Related Tests and Entry Points

A module map saves search time only if it leads to behavior-relevant verification. Link each important entry point and relationship path to the tests that exercise it.

Useful test-index fields include:

Field	Purpose
test path and command	makes verification reproducible
behavior or contract covered	prevents “nearby test” selection
environment and fixtures	exposes database, network, or service dependencies
source relationship	explains why the test belongs to the task
last successful revision	signals possible drift without promising current success
owner and known limitations	routes failures and prevents false confidence

Entry points require the same care. Record CLI commands, server routes, background jobs, plugin registrations, migrations, and generated interfaces. A symbol search may find a function but miss the configuration that activates it.

Fleet task specs can carry input_files, additional context, required files, and expected artifacts. Use those fields to give a worker the selected source and test paths, not an unbounded request to “understand the repository.” The worker’s receipt should return the commands and artifact evidence needed to verify the result.

Rebuild or incrementally update the index when source changes affect mapped relationships. A checksum or commit match is necessary, but high-impact work should still read the relevant current files.

Retrieve Context by Task

The smallest useful context packet answers seven questions:

1. What behavior must change?
2. Which revision and workspace are authoritative?
3. Which modules and entry points are in scope?
4. Which dependency paths justify that scope?
5. Which rules and decisions apply?
6. Which tests and reviewers verify the result?
7. Which relationships remain uncertain?

Keep temporary state outside the shared map. A worker’s plan, tool output, debugging hypothesis, and provider-specific conclusion belong to its task record. If a finding should become shared knowledge, require source locations, revision, derivation method, and review.

Codewhale’s opt-in memory is not the place for repository indexing. Its v0.9.0 memory documentation calls the file user-scoped and intended for durable personal preferences across repositories and sessions. Repo conventions belong in project instructions; structural facts belong in a versioned evidence layer.

For Fleet workflows, the related CodeWhale Fleet Context Sharing guide explains how read-only repo evidence and isolated worker state fit together.

Validate Savings Without Hiding Risk

Measure optimization with controlled, repeatable tasks. Do not promise a fixed token reduction: provider token accounting, repository shape, task complexity, caching, and model behavior differ.

Choose several representative tasks and run each with and without the external context layer at the same revision. Record:

• time until the agent proposes a source-linked plan;
• search and file-read actions before the first edit;
• provider-reported input and output tokens when available;
• repeated reads of unchanged files;
• number of graph expansions or fallback full-text searches;
• missed dependencies found during review;
• relevant test selection and pass/fail results;
• reviewer corrections and unsupported claims.

Savings are meaningful only when quality holds. A task that uses fewer tokens but misses a generated consumer is not optimized. Add guardrails: stale context triggers a targeted refresh; disagreement with current source invalidates the cached edge; security, migration, public API, and incident tasks default to broader verification.

Compare medians across several tasks rather than promoting one successful run. Keep the provider, model, revision, task brief, permissions, and verification commands stable so the comparison measures context retrieval instead of an unrelated route change.

FAQ

When should CodeWhale ignore cached context?

Ignore or bypass it when the commit differs, mapped files changed, generation failed, a live source check contradicts an edge, or the task touches dynamic registration, generated code, migrations, security controls, incident response, or external contracts not represented in the map. A provider change alone does not invalidate source-derived facts, but it does require model-specific conclusions to be reconsidered.

How should provider-specific notes be labeled?

Store the provider, model, date, task, revision, and evidence used. Mark the note as observation, hypothesis, or measured result. Do not promote it into shared repository knowledge unless current source or repeatable tests support it. Keep pricing, context-window, and token-accounting notes tied to the concrete route because those attributes can vary by provider.

What evidence proves optimization helped?

Use a matched baseline showing fewer redundant searches or reads, lower startup time, or lower provider-reported token use while preserving dependency recall, test selection, reviewer acceptance, and task correctness. Report the task set and measurement method. One fast run or a smaller prompt does not prove safer repository understanding.

Conclusion

Codewhale context optimization works best when it removes repeated discovery while retaining current evidence. Build an external revision-bound module, dependency, entry-point, and test index. Retrieve only the slice a task needs, keep worker state separate, and fall back to source inspection whenever freshness or coverage is uncertain.

Measure search actions, time, tokens, dependency recall, test quality, and reviewer corrections together. If a smaller context packet makes a risk harder to see, it is compression—not optimization.

CodeWhale large codebase work needs a repository evidence layer that remains stable when the active model or provider changes. Codewhale can read and edit code, run commands, check results, and route many models through one terminal-agent runtime. Those capabilities do not automatically reveal module boundaries, indirect callers, design intent, related tests, or cross-repository contracts.

This guide uses Codewhale for the product’s spelling and preserves CodeWhale where it is part of the supplied search language. Facts were checked against the v0.9.0 documentation and release published on July 16, 2026. The repository may move ahead of that release, so unreleased files should not be presented as installed behavior.

What CodeWhale Brings to Terminal Agents

Codewhale is an open-source, MIT-licensed coding agent for the terminal. Its official README describes an interactive TUI and a headless codewhale exec path for scripts and CI. The runtime can read code, edit files, execute commands, and inspect results. It also resolves a selected provider and model to a concrete API route.

The provider layer is valuable for teams that want one operational surface across hosted and local models. Codewhale documents DeepSeek, Claude, GPT, Kimi, GLM, and many other routes. In the TUI, /model selects a provider and model together, while /provider changes the active provider. A team can therefore compare routes or assign different configured models to Fleet profiles without replacing its whole agent harness.

Large-repository usefulness still depends on how the task is framed. A terminal agent sees the workspace, tools, instructions, and context supplied for a run. It does not gain a complete architecture model simply because the provider supports a large context window or because the runtime can search files.

The latest public release at the verification cutoff is v0.9.0, published on July 16, 2026. npm also marks 0.9.0 as its latest distribution tag. Do not describe a later repository version as released until both the release channel and the package channel support that claim.

Codewhale’s own onboarding advice is appropriately conservative: start unfamiliar work in Plan mode, identify sources and critical files, then move to Act for changes. That sequence is useful, but the team must still provide or discover the repository facts on which the plan depends.

Why Large Repos Need More Than Model Routing

Model routing answers, “Which provider and model will process this turn?” Repository understanding answers, “Which system relationships must this task preserve?” These questions intersect, but neither resolves the other.

Consider a change to an authentication claim. The named type may live in one package, while its serializers, middleware, generated clients, deployment flags, database migrations, and contract tests live elsewhere. A model can produce a locally plausible edit after reading the definition and its obvious callers. The edit can still break a consumer reached through registration, configuration, reflection, generated code, or another repository.

Switching providers can make this gap more visible. The new model receives the current prompt, workspace, and whatever durable instructions the harness loads. It does not inherit private reasoning that another model formed in an earlier turn. A saved session or summary may preserve text, but text is not proof that the underlying relationships remain accurate.

Three failure patterns are common:

• Path familiarity masquerades as architecture knowledge. An agent repeatedly opens popular directories and misses a less obvious runtime path.
• A prior summary becomes authority. A handoff says a module is unused, although current imports or configuration say otherwise.
• A provider change alters the explanation, not the evidence. Two models produce confident but incompatible impact summaries because neither received a revision-bound dependency map.

Treat provider choice as an execution decision. Treat repository evidence as a separate, inspectable input that any suitable model can query.

Repository Knowledge CodeWhale Still Needs

A useful repository context layer is small enough to retrieve and specific enough to audit. It should not be a giant prose summary of everything the team knows.

Start with these model-independent facts:

Evidence	Useful contents	Verification anchor
Module map	packages, services, entry points, generated areas, ownership	repository revision and manifests
Dependency paths	imports, calls, registrations, schema and event flows	exact source locations
Test index	unit, integration, contract, migration, and end-to-end coverage	current test files and commands
Decision links	architecture records, approved constraints, deprecations	dated documents and owners
External boundaries	APIs, queues, databases, clients, sibling repositories	contracts plus deployment configuration

This evidence should identify its source revision. “Service A calls service B” is only reusable when the record says how that relationship was derived and when it was last refreshed. Generated and inferred edges should be labeled differently from directly parsed imports or explicit configuration.

Codewhale already separates some authority layers. Its documentation places repo instructions in AGENTS.md, repo governance in .codewhale/constitution.json, and optional personal memory in a user-scoped file. None of those should become an improvised dependency database. Instructions explain how an agent should work. A constitution ranks authority and verification expectations. User memory stores durable personal preferences when explicitly enabled.

For a fuller treatment of portable repository facts, see Share Repo Context Across Coding Agents. The principle is the same for Codewhale: keep structural evidence independent from one provider’s session.

Code Graphs for Multi-Model Workflows

An external, revision-bound code graph can make the repository evidence layer queryable. “External” is important: Codewhale v0.9.0 does not document a native code graph, repository index, or automatically shared repository-memory service.

A graph can represent files, symbols, packages, tests, documents, owners, schemas, and their typed relationships. Before an agent edits a parser, the task can retrieve the parser’s callers, relevant configuration, generated consumers, and tests. The model then reads the selected current files rather than trusting the graph as an oracle.

A practical query packet contains:

1. the task objective and acceptance criteria;
2. the repository revision and allowed write scope;
3. relevant nodes and relationship paths;
4. direct source locations for every important edge;
5. applicable decisions and instructions;
6. tests that cover the affected behavior;
7. unresolved or low-confidence relationships.

This pattern keeps providers replaceable. DeepSeek and Claude may explain a path differently, but they can receive the same versioned evidence. Their model-specific conclusions stay in the task record until source or test results justify promoting a fact into shared repository knowledge.

Graphify’s broader knowledge graph guide for AI coding assistants explains structural retrieval in more depth. The important operating rule is simpler: use a graph to select and connect evidence, then use current code and tests to verify the claim.

Verification Checklist

Before relying on Codewhale for a large-repository change, verify the product surface, the task evidence, and the result separately.

• Confirm the installed package and public release. At this cutoff, both point to v0.9.0.
• Record the active provider, model, workspace, branch, and commit.
• Read the applicable AGENTS.md and repo-local constitution without treating either as repository structure.
• Identify entry points, affected modules, indirect consumers, generated artifacts, and external contracts.
• Pin graph or index output to the same revision as the checkout.
• Read the current source behind load-bearing relationship claims.
• Select behavior-relevant tests, not only tests located beside the edited file.
• Label model-specific hypotheses and reject unsupported handoff claims.
• Re-query changed dependency paths after the patch.
• Preserve commands, test output, diffs, and unresolved risks for review.

This checklist does not guarantee correctness. It gives a reviewer a reconstructable evidence path and makes provider changes less likely to erase why the task was considered safe.

FAQ

Which repo facts should be model-independent?

Keep stable, verifiable facts model-independent: module ownership, public entry points, imports, calls, schema relationships, deployment boundaries, test coverage, architecture decisions, and source provenance. Store the repository revision and evidence path with each fact. Do not promote an agent’s unverified diagnosis, speculative intent, or private chain of reasoning into the shared layer.

What should writers verify in CodeWhale docs?

Verify the product spelling, latest released version, provider and model controls, terminal and headless execution paths, Fleet terminology, constitution location, memory scope, and subagent behavior against the released documentation. At the July 23 cutoff, the relevant public release and npm package are v0.9.0. Also verify negative boundaries: the cited docs do not claim a native code graph or shared repository index.

When should teams avoid provider switching mid-task?

Avoid switching during a migration, incident response, release gate, or security-sensitive change when the incoming model cannot reconstruct the plan and evidence. Finish the current verification boundary first, or create a handoff containing the revision, task scope, source paths, graph queries, tests, results, assumptions, and open risks. Restart planning if that evidence cannot be reproduced.

Conclusion

Codewhale gives teams a flexible terminal-agent runtime and a practical way to route different models through common tools. For a large codebase, that is the execution layer—not the repository understanding layer.

Use Codewhale with a pinned task, current source, explicit instructions, and revision-bound relationship evidence. Keep architecture and dependency facts model-independent, label uncertain conclusions, and make tests the final gate. If another provider cannot reproduce the evidence behind a proposed change, the workflow is not ready to switch models or edit the repository.

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:

1. the repository root and working commit;
2. the source, test, generated, vendored, and migration-controlled paths;
3. the teams that own architecture and shared instructions;
4. the actions the agent may perform without approval;
5. 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:

1. identify the behavior, symbol, route, or schema at the center of the task;
2. query the current structural artifact for direct and transitive relationships;
3. select the smallest source, document, and test set that can verify those paths;
4. open the current files in Qoder CLI;
5. mark every important relationship as confirmed, inferred, or unresolved;
6. 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.

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:

1. Freeze the task against a repository revision and define its allowed scope.
2. Query the graph for the target entity, direct neighbors, cross-package paths, and related tests.
3. Inspect the source files and documents behind important nodes and edges.
4. Mark dynamic, inferred, cross-repository, or stale relationships as uncertain.
5. Produce an impact statement before editing.
6. 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.

Claudex context engineering means giving the model current, scoped repository evidence instead of assuming that changing the model creates repository knowledge. In this article, Claudex specifically means the unofficial, MIT-licensed liuzhao1225/claudex wrapper—not the several unrelated projects that share the name.

As of July 17, 2026, this Claudex project was only days old. It launched the installed Claude Code client through a localhost CLIProxyAPI gateway and selected gpt-5.6-sol by default. Neither OpenAI nor Anthropic documents or endorses this route, so teams should treat it as an experimental integration and keep their repository knowledge portable.

What Claudex Context Engineering Means

Claudex is a routing wrapper, not a new model or context engine.

Its launch script verifies that the chosen model appears in the proxy's catalog, sets Claude Code gateway and model environment variables, and then executes the existing claude binary. The default identifier is gpt-5.6-sol. OpenAI's official Codex model page currently lists the same identifier and describes Sol as its flagship GPT-5.6 option for complex coding and other demanding work.

That confirms the model name in native Codex. It does not establish feature parity through a third-party protocol translator, benchmark Claudex on repository tasks, or show that every ChatGPT account can use the route.

The useful mental model has four separate layers:

Layer	Responsibility	Source of truth
Client	Tools, file access, instructions, session flow	Installed Claude Code version
Route	Authentication and protocol translation	Claudex plus its pinned CLIProxyAPI release
Model	Reasoning over supplied context	Selected upstream model and settings
Repository knowledge	Architecture, dependencies, ownership, tests	Maintained project artifacts and current source

Context engineering operates mainly in the fourth layer. A stronger model may interpret evidence better, but it cannot recover a private service boundary, generated-code rule, or migration constraint that the workflow never supplies.

Before adoption, run a controlled task on both the native client and the Claudex route. Record the exact versions, model identifier, reasoning setting, files opened, searches performed, plan accuracy, test selection, and review corrections. This tests the complete workflow instead of attributing every result to the model name.

Organize CLAUDE.md and Project Rules

Use CLAUDE.md for stable instructions that should shape most work in the repository.

Anthropic's Claude Code memory documentation says project instructions can live in ./CLAUDE.md or ./.claude/CLAUDE.md. Ancestor instruction files load at launch, while files in subdirectories load when Claude reads within those areas. Modular files under .claude/rules/ can also be scoped to particular paths.

Because Claudex ultimately executes the installed claude client, normal instruction discovery should remain client-side behavior. That is an inference from the wrapper's source, not a Claudex compatibility guarantee. Test it after upgrades, especially when the gateway or Claude Code protocol changes.

Keep the root file concise and operational:

• list the correct build, lint, test, and type-check commands;
• name generated, vendored, and migration-controlled paths;
• identify architecture indexes and package owners;
• define approval points for schemas, permissions, and public interfaces;
• require source inspection before repository-wide edits;
• state how to report uncertainty and verification results.

Do not paste a changing dependency inventory into global instructions. Anthropic describes these files as context rather than enforced configuration and recommends concise, specific rules, with a target below 200 lines per file. Put enforceable restrictions in permissions, hooks, or external review controls.

If a team standardizes on AGENTS.md across tools, avoid two hand-maintained copies. Claude Code reads CLAUDE.md, not AGENTS.md, but its official documentation supports importing AGENTS.md from CLAUDE.md. Add Claude-specific guidance only where the client truly needs it.

A practical root rule might require a pre-edit report:

Before a cross-package change, report:
1. entry point and owning package;
2. direct and transitive dependency path;
3. generated artifacts and schema sources;
4. focused tests and rollback path;
5. unresolved assumptions requiring approval.

This rule directs the agent toward evidence without freezing today's repository map into a permanent prompt.

Add Architecture and Dependency Signals

Architecture context should reveal relationships that file names and local imports cannot explain.

Maintain a short system overview, package boundaries, key data flows, architecture decision records, ownership rules, generated-code paths, and deployment constraints. Each artifact should identify its maintainer, relevant source revision, and review trigger. A polished diagram with no date or owner is a weak source because the agent cannot judge whether it describes the current system.

Dependency signals should connect intent to implementation. For a proposed change, the agent needs to locate:

• the entry point and authoritative implementation;
• callers, consumers, and runtime dependencies;
• schemas or generators that own derived files;
• tests that observe the changed behavior;
• security, migration, and rollback boundaries.

Static rules point to evidence; current source and dependency signals determine the plan.

Use progressive disclosure. The root instructions should point to an architecture index, while package-local rules and task-specific retrieval provide detail only when relevant. This leaves more context for current code and reduces the chance that an unrelated design record dominates the task.

For a broader method that is independent of the model route, see how to help Claude Code understand a complex repository. The same project knowledge should remain useful if the team later returns to native Claude models or moves the task to another coding agent.

Use Code Graphs for Cross-File Planning

A code graph is useful when cross-file relationships exceed what a compact CLAUDE.md can maintain.

The graph can represent symbols, files, packages, routes, schemas, tests, owners, and architecture records as nodes. Typed edges can express imports, calls, generation, coverage, ownership, or documented rationale. An agent can query those relationships to select a small evidence set before reading the source.

For a multi-file change, use a graph-assisted planning loop:

1. Define the behavior and entry point instead of starting with a broad repository scan.
2. Query inbound and outbound dependency paths around the affected symbol or package.
3. Identify tests, generated artifacts, schemas, and owners connected to that path.
4. Open the current source files and verify every material edge.
5. Draft the plan with confirmed facts separated from inference.
6. Run focused tests, then expand verification according to the impact radius.

The graph is a navigation and impact-analysis layer, not approval evidence by itself. Record the indexed commit, generation time, parser coverage, ignored paths, and inferred-edge rules. Refresh it after structural changes or reject results that are older than the source under review.

Claudex does not create this graph. A separate repository tool must build and expose it through commands, files, or another supported integration. Graphify is one option for generating a code knowledge graph, but the workflow should still verify proposed paths against current source and tests.

This separation also prevents model lock-in. The same maintained graph and architecture index can support a GPT-5.6 Sol route, native Claude Code, and a shared multi-agent workflow. The companion guide to sharing repository context across coding agents explains how to keep common evidence separate from tool-specific instructions.

Limits and Staleness Risks

The largest Claudex risk is not prompt length; it is treating an experimental route as stable infrastructure.

Anthropic's gateway documentation states that it does not endorse, maintain, or audit third-party gateways and does not support routing Claude Code to non-Claude models through a gateway. It also warns that client features can break when a gateway fails to pass through newer protocol capabilities.

Claudex reduces some local exposure by binding its proxy to 127.0.0.1, pinning a CLIProxyAPI build, and storing a local token. “Localhost-only” does not mean source code stays on the device. The proxy still sends prompts, credentials, tool results, and selected code to upstream services. Review the proxy, provider data controls, and repository sensitivity before use.

Verify the route and the evidence layer separately before approving repository-wide changes.

Use this release gate:

• pin the Claudex, CLIProxyAPI, and Claude Code versions;
• verify the exact model identifier rather than accepting a silent fallback;
• inspect the effective project instructions and permission boundary;
• refresh architecture and graph artifacts against the working commit;
• test subagent behavior and tool compatibility explicitly;
• compare a representative repository task with a supported native workflow;
• review current OpenAI terms, plan guidance, and Anthropic gateway documentation;
• require human approval for dependency-wide, permission, schema, or migration changes.

Passing CI in the Claudex repository is useful but limited evidence. Its workflow checks shell code, unit behavior, and pinned dependencies; model-catalog responses and the Claude executable are mocked in relevant tests. That is not an independent evaluation of protocol parity, model quality, repository understanding, or account safety.

Staleness applies to every layer. Models and account availability change, gateway translations lag client features, CLAUDE.md accumulates obsolete rules, architecture documents drift, and graphs age after merges. Attach an owner and event-driven refresh trigger to each artifact, then make the agent report its evidence timestamps.

FAQ

Who should maintain context files?

Platform or developer-experience owners should maintain shared workflow rules. Architecture owners should review system boundaries and decision records. Package teams should maintain local commands, schemas, and tests. Every artifact needs an owner, authority level, and refresh trigger; no single person should silently redefine repository-wide permissions.

What should not be duplicated in prompts?

Do not duplicate large source files, secrets, volatile dependency lists, generated output, or the full text of architecture records. Keep stable directives in project rules, retrieve current relationships from maintained artifacts, and cite the authoritative files in the task plan. Duplicate facts become contradictory facts after the next merge.

How should subagents share repo knowledge?

Give subagents a common evidence bundle: task goal, working commit, architecture index, relevant graph query, source paths, tests, permissions, and unresolved assumptions. Keep role-specific instructions separate. With Claudex, also verify CLAUDE_CODE_SUBAGENT_MODEL and actual subagent behavior instead of assuming that every Claude-specific capability translates unchanged.

Conclusion

Context engineering for Claudex is valuable only when the repository knowledge survives the model route.

Treat liuzhao1225/claudex as an unofficial, fast-changing bridge to GPT-5.6 Sol. Keep stable constraints in concise CLAUDE.md rules, retrieve architecture and dependency evidence on demand, use code graphs to narrow cross-file planning, and verify every material relationship against current source and tests.

The decision rule is straightforward: if the team cannot reproduce the plan with pinned versions, dated context, and an explicit approval path, improve the knowledge and verification layer before trusting the model swap.