Best Practices for Large Codebases

​

Overview

This document summarizes best practices for making Qoder CLI work more efficiently, especially in large codebases and Monorepos. The core principle is simple: prepare the information, constraints, and context Qoder needs in advance to minimize detours.

​

Write Effective Prompts

Clear prompts often save more time than multiple rounds of correction:

• State goals and constraints clearly: Specify not only what to do, but also what not to change and what rules must be followed.
• Provide key context: When dealing with specific files, interfaces, or conventions, name them directly to reduce Qoder's search overhead.
• Focus on one thing at a time: Break complex requirements into sequential, smaller steps rather than stacking all demands at once for better control.
• Define acceptance criteria: Clearly state "what counts as done" (e.g., a specific test passes, a command runs without errors) so Qoder can self-verify.

​

Manage Context

The context window is limited, so it must be actively managed during long sessions:

• When switching to an unrelated new task, use /clear to clear historical context.
• When a long session reaches a point where context becomes tight, use /compact to compress history and retain key information.
• Write stable project conventions into AGENTS.md to avoid repeating explanations in every conversation. See Memory.

For details on context mechanisms and differences, see How Memory Works.

​

Solidify Conventions with Project Instructions

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

• Use /init in the project root directory to generate AGENTS.md, documenting architecture, directory structure, common commands, and collaboration conventions.
• Use rule files under <project>/.qoder/rules/ to split instructions by topic (testing, API, security) to prevent a single AGENTS.md from becoming too bloated.
• When strict restrictions on certain commands or paths are needed, use permissions or Hooks instead of relying solely on instructions. See Permissions and Hooks.

​

Large Codebase

When working in large repositories:

• Start from a subdirectory: Launch Qoder in the subdirectory you are working on (rather than the repository root) so it prioritizes loading project instructions and rules at that level. Project memory is searched upwards from the current directory. See Memory.
• Narrow the exploration scope: Name relevant modules or files directly to prevent Qoder from searching broadly across the entire repository.
• Hierarchical project instructions: Place respective AGENTS.md and rules in key subdirectories to give different modules their own context.

​

Monorepo

A Monorepo typically contains multiple relatively independent packages or applications:

• Organize project instructions by package: Maintain AGENTS.md in each package directory, describing the package's responsibilities, dependencies, and conventions. When Qoder accesses a file in a package, it will load the instructions for that directory and its parent directories as needed.
• Work within the target package: When working on a specific package, launch from its directory or explicitly specify the working scope to reduce irrelevant context.
• Work in parallel: Use Worktrees to create independent workspaces for different packages or tasks to avoid interference. See Handling Multiple Tasks in Parallel.

​

Choose a Working Mode

Different tasks are suited to different working modes:

• High impact or uncertain direction: Use Plan to confirm the approach first. See Plan Before Execution (Plan).
• Clear endpoint, hands-off completion: Use Goal for continuous execution. See Continuous Goal Completion (Goal).
• Scripts and pipelines: Use Headless Mode. See Run in Scripts.

For a comprehensive guide on choosing a mode, see Choosing the Right Working Mode.

​

Let Qoder Self-Verify

• Have Qoder proactively run tests or builds after modifying code to form an "implement-verify-correct" closed loop.
• Use /diff and /review to review changes after completion. See Viewing and Reviewing Code Changes.
• For significant changes, combine with Git commits and use rollbacks to restore when necessary. See Reverting Changes and Restoring Sessions.