Best Practices for Large Codebases

​

Overview

This page gathers practices that make Qoder CLI CN work more efficiently, especially in large codebases and monorepos. The core idea comes down to one sentence: prepare the information, constraints, and context Qoder needs in advance, so it takes fewer detours.

​

Writing good prompts

A clear prompt often saves more time than multiple rounds of corrections:

• State goals and constraints: say not only what to do, but also what should not change and what must be followed.
• Provide key context: when specific files, interfaces, or conventions are involved, name them directly to cut Qoder's search cost.
• Focus on one thing at a time: splitting a complex requirement into ordered small steps is more controllable than stacking all demands at once.
• Give acceptance criteria: make it explicit what "done" means (for example, a certain test passing or a command running without errors), and Qoder will verify itself against it.

​

Managing context

The context window is finite; manage it actively in long sessions:

• When switching to an unrelated new task, clear the history context with /clear.
• Midway through a long session when context gets tight, compress the history with /compact while retaining key information.
• Write stable project conventions into AGENTS.md to avoid re-explaining them in every conversation — see Memory.

For the mechanics and distinctions of context, see How Memory Works.

​

Solidifying conventions with project instructions

For teams and large projects, AGENTS.md and rules are key to consistency:

• Generate AGENTS.md with /init in the project root, and fill in architecture notes, directory structure, common commands, and collaboration conventions.
• Split instructions by topic (testing, API, security) into rule files under <project>/.qoder/rules/, avoiding a single bloated AGENTS.md.
• When you need to hard-restrict certain commands or paths, use permissions or Hooks rather than instructions alone — see Permissions and Directory Trust and Hooks.

​

Large codebases

When working in a big repository:

• Start from a subdirectory: launch Qoder in the subdirectory you are working on (rather than the repo root), so it prioritizes loading that level's project instructions and rules. Project memory is discovered upward from the current directory — see Memory.
• Narrow the exploration scope: name the relevant modules or files directly, so Qoder doesn't search broadly across the whole repository.
• Layered project instructions: place per-directory AGENTS.md and rules in key subdirectories, so different modules carry their own context.

​

Monorepos

A monorepo usually contains multiple relatively independent packages or apps:

• Organize project instructions per package: maintain an AGENTS.md in each package directory describing that package's responsibilities, dependencies, and conventions. After Qoder touches a package's files, it loads the instructions of that directory and its ancestors on demand.
• Work inside the target package: when handling a package, launch from its directory or state the working scope explicitly to reduce irrelevant context.
• Drive work in parallel: use Worktrees to open separate workspaces for different packages or tasks, avoiding interference — see Parallel Tasks.

​

Choosing the right way of working

Different tasks suit different ways of working:

• High impact or uncertain direction: confirm the approach with Plan first — see Plan Before Executing.
• Clear finish line, want to hand it off: use Goal for continuous execution — see Working Toward a Goal.
• Scripts and pipelines: use Headless mode — see Run in Scripts.

For the overall guide to choosing, see Choosing a Way of Working.

​

Let Qoder verify itself

• Have Qoder proactively run tests or builds after changing code, forming an "implement — verify — fix" loop.
• After changes are done, double-check with /diff and /review — see Reviewing Changes.
• For important changes, pair with Git commits, and use rewind to revert when needed — see Undo and Restore.