最佳实践与大型代码库

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

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

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

• 切换到不相关的新任务时，用 /clear 清除历史上下文。
• 长会话进行到中途、上下文变紧张时，用 /compact 压缩历史，保留关键信息。
• 把稳定的项目约定写进 AGENTS.md，避免每次都在对话里重复解释，见 记忆。

上下文的机制和区别见 Qoder CLI 如何记住信息。 对团队和大型项目，AGENTS.md 和 rules 是提升一致性的关键：

• 在项目根目录用 /init 生成 AGENTS.md，写入架构说明、目录结构、常用命令和协作约定。
• 用 <project>/.qoder/rules/ 下的规则文件按主题（测试、API、安全）拆分指令，避免单个 AGENTS.md 过于臃肿。
• 需要硬性限制某类命令或路径时，用权限或 Hooks，而不是仅靠说明，见 权限 和 Hooks。

在大仓库中工作时：

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

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

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

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

• 影响面大或方向不确定：先用 Plan 确认方案，见 先规划再执行（Plan）。
• 有明确终点、想放手完成：用 Goal 持续执行，见 持续完成目标（Goal）。
• 脚本和流水线：用 Headless 模式，见 在脚本中运行 Qoder CLI。

选择方式的整体指南见 选择合适的工作方式。

• 让 Qoder 在改完代码后主动运行测试或构建，形成"实现—验证—修正"的闭环。
• 改动完成后用 /diff 和 /review 复核，见 查看和审查代码改动。
• 涉及重要改动时配合 Git 提交，必要时用回退还原，见 撤销改动与恢复会话。