Qoder CLI Context Engineering

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

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

Before You Start

Start by separating product behavior from repository knowledge.

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

Before designing the context system, record five facts:

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.