项目与工作区
理解项目、工作区、分支和 checkpoint。
North Coder 围绕项目和工作区组织任务。项目代表一个代码库或目录；工作区代表一次具体任务的执行环境。
核心概念
| 概念 | 说明 |
|---|---|
| 项目 | 一个本地代码目录或 Git 仓库。 |
| 工作区 | Agent 处理任务的独立环境。 |
| Source ref | 创建工作区时的起点，可以是分支、tag 或 commit。 |
| Target branch | 任务最终希望合入的目标分支。 |
| 工作分支 | 当前工作区内实际产生改动的分支。 |
| Checkpoint | 用于保存或回退关键状态的检查点。 |
并行工作区与 Git Worktree
North Coder 支持多个 Agent 同时在同一个项目上工作，互不干扰。底层机制是 Git Worktree：每个工作区对应一份独立的工作目录和独立的分支，文件系统层面物理隔离。
| Agent | 任务 | 分支 |
|---|---|---|
| A | 修复认证 token 过期 bug | fix/auth-token-expire |
| B | 新增用户导出功能 | feat/user-export |
| C | 补充支付模块单元测试 | test/payment-module |
三个 Agent 并行施工时：
- 各自在独立目录里读写，不会覆盖彼此的文件。
- 分支名根据第一条消息自动生成，无需手动命名。
- 任务完成后可一键创建 PR。
- 合并后工作区自动归档，保持项目整洁。
这和"多开几个聊天窗口但在同一目录改来改去"有本质区别——后者在 Agent A 改文件时，Agent B 可能同时覆盖相同文件导致冲突。Git Worktree 从根本上消除了这个问题。
什么时候创建新工作区
建议为每个独立目标创建一个工作区：
- 一个功能改动。
- 一个 bug 修复。
- 一次文档更新。
- 一轮代码审查处理。
- 一次只读调研或排障。
避免在同一个工作区里混合多个无关目标，这会让改动审阅、测试和合并都变复杂。
选择 Source ref
创建工作区时，Source ref 决定任务从哪里开始：
- 使用主分支：适合常规新任务。
- 使用已有功能分支：适合继续处理未完成工作。
- 使用 commit id：适合复现某个历史状态。
- 使用 tag：适合基于已发布版本排查问题。
如果你不确定，通常选择当前主分支或正在协作的功能分支。
设置 Target branch
Target branch 用于表达最终合并目标。它不会自动替你完成合并，但会帮助后续 PR、diff 和 review 语义保持清晰。
常见选择：
main或master：常规产品改动。- 发布分支：针对特定版本的修复。
- 团队约定的集成分支：多人协作时使用。
管理工作区
常见操作包括：
- 打开工作区，继续已有会话。
- Fork 工作区，从当前状态创建新分支。
- 归档不再活跃的工作区。
- 使用 checkpoint 保存关键状态。
- 在外部 IDE 中打开工作区目录。
当 Agent 或你自己已经产生改动时，优先审阅现有变更，再决定继续修改、拆分任务或创建新工作区。
Git 状态
开始任务前建议确认：
- 当前分支是否正确。
- 是否存在未提交的本地改动。
- 远端分支是否需要更新。
- 是否已经有打开的 PR 或 review 线程。
North Coder 可以辅助处理这些状态，但你仍应把每个工作区的目标边界保持清楚。