> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 最佳实践与大型代码库

# 概述

这篇文档汇总了让 Qoder CLI 更高效工作的一些实践经验，尤其是在大型代码库和 Monorepo 中。核心思路只有一句：**把 Qoder 需要的信息、约束和上下文提前准备好，让它少走弯路。**

# 写好提示词

清晰的提示词往往比多轮纠正更省时间：

* **说清目标和约束**：不仅说要做什么，也说清不希望改动什么、必须遵守什么。
* **提供关键上下文**：涉及具体文件、接口或约定时，直接点名，减少 Qoder 的搜索成本。
* **一次聚焦一件事**：把复杂需求拆成有先后的小步骤，比一次性堆叠所有要求更可控。
* **给出验收标准**：明确"怎样算完成"（例如某个测试通过、某个命令无报错），Qoder 会据此自我验证。

# 管理上下文

上下文窗口是有限的，长会话中要主动管理：

* 切换到不相关的新任务时，用 `/clear` 清除历史上下文。
* 长会话进行到中途、上下文变紧张时，用 `/compact` 压缩历史，保留关键信息。
* 把稳定的项目约定写进 `AGENTS.md`，避免每次都在对话里重复解释，见 [记忆](https://docs.qoder.com/zh/cli/04-扩展QoderCLI/memory.md)。

上下文的机制和区别见 [Qoder CLI 如何记住信息](https://docs.qoder.com/zh/cli/02-核心概念/context.md)。

# 用项目说明固化约定

对团队和大型项目，`AGENTS.md` 和 rules 是提升一致性的关键：

* 在项目根目录用 `/init` 生成 `AGENTS.md`，写入架构说明、目录结构、常用命令和协作约定。
* 用 `<project>/.qoder/rules/` 下的规则文件按主题（测试、API、安全）拆分指令，避免单个 `AGENTS.md` 过于臃肿。
* 需要**硬性**限制某类命令或路径时，用权限或 Hooks，而不是仅靠说明，见 [权限](https://docs.qoder.com/zh/cli/06-配置与安全/permissions.md) 和 [Hooks](https://docs.qoder.com/zh/cli/04-扩展QoderCLI/hooks.md)。

# 大型代码库

在大仓库中工作时：

* **从子目录启动**：在你要处理的子目录（而非仓库根）启动 Qoder，让它优先加载该层级的项目说明和规则。项目记忆会从当前目录向上查找，见 [记忆](https://docs.qoder.com/zh/cli/04-扩展QoderCLI/memory.md)。
* **缩小探索范围**：直接点名相关模块或文件，避免 Qoder 在整个仓库中大范围搜索。
* **分层的项目说明**：在关键子目录放置各自的 `AGENTS.md` 和规则，让不同模块带上自己的上下文。

# Monorepo

Monorepo 通常包含多个相对独立的包或应用：

* **按包组织项目说明**：在每个包目录下维护 `AGENTS.md`，描述该包的职责、依赖和约定。Qoder 访问某个包的文件后会按需加载对应目录及其上层的说明。
* **在目标包内工作**：处理某个包时，从该包目录启动或明确指定工作范围，减少无关上下文。
* **并行推进**：用 Worktree 为不同包或不同任务开独立工作区，避免互相干扰，见 [并行处理多个任务](https://docs.qoder.com/zh/cli/03-使用QoderCLI/03-多任务与协作/parallel.md)。

# 选对工作方式

不同任务适合不同的工作方式：

* **影响面大或方向不确定**：先用 Plan 确认方案，见 [先规划再执行（Plan）](https://docs.qoder.com/zh/cli/03-使用QoderCLI/01-开始一个任务/plan.md)。
* **有明确终点、想放手完成**：用 Goal 持续执行，见 [持续完成目标（Goal）](https://docs.qoder.com/zh/cli/03-使用QoderCLI/02-任务自动化/goal.md)。
* **脚本和流水线**：用 Headless 模式，见 [在脚本中运行 Qoder CLI](https://docs.qoder.com/zh/cli/03-使用QoderCLI/02-任务自动化/headless.md)。

选择方式的整体指南见 [选择合适的工作方式](https://docs.qoder.com/zh/cli/02-核心概念/work-modes.md)。

# 让 Qoder 自我验证

* 让 Qoder 在改完代码后主动运行测试或构建，形成"实现—验证—修正"的闭环。
* 改动完成后用 `/diff` 和 `/review` 复核，见 [查看和审查代码改动](https://docs.qoder.com/zh/cli/03-使用QoderCLI/04-管理会话和改动/review.md)。
* 涉及重要改动时配合 Git 提交，必要时用回退还原，见 [撤销改动与恢复会话](https://docs.qoder.com/zh/cli/03-使用QoderCLI/04-管理会话和改动/checkpoint.md)。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.