AI 工具的正确姿势：plan mode 与 note-it 的边界

Fen9Pi2026/8/10大约 9 分钟

开篇：AI 工具普及后的新问题

AI 工具已经成了很多开发者的日常。

Codex、OpenClaw、Cursor、Cline……这些工具让写代码变得更轻松。但同时，一个新问题出现了：

我们应该如何正确使用这些 AI 工具？ " 不是"能不能用"，而是"什么时候用、怎么用、用到什么程度"。

最近看到一段关于 Codex/OpenClaw 使用经验的分享，非常精辟。它总结了三个关键工具的使用边界：

plan mode：精密手术刀，不是万能钥匙
Task List：会话级轻量，持久化慎重
note-it：5 分钟记录，换 3 个月不考古

今天聊聊这三个工具的正确使用姿势。

一、plan mode：精密手术刀，不是万能钥匙

常见误区

很多人有个习惯：不管什么活，先开 plan mode。

改个单文件的 bug？先 plan。加个简单的 feature？先 plan。重构一个小函数？还是先 plan。

问题来了：plan mode 会做什么？

它会探仓库、分析代码、理解上下文、生成计划、等你确认。这一套下来，可能已经过去了几分钟。

结果你一看计划：嗯，改三行代码，加个 if 判断。

这几分钟的规划时间，值吗？

判断标准：改动的"分量"

经验法则：只在改动有分量、或者需求还含糊的时候开 plan mode。

什么是有"分量"的改动？

1. 动公共 API

# 改之前
def process_data(data: List[Dict]) -> Dict:
    ...

# 改之后——签名都变了
def process_data(data: DataFrame) -> DataFrame:
    ...

这种改动影响所有调用方，需要计划。

2. 跨多个文件

# 不只是改一个函数
src/service/api.py          # API 层
src/service/business.py     # 业务逻辑层
src/repository/database.py  # 数据访问层
tests/test_api.py            # 测试

跨文件改动需要协调，需要计划。

3. 自己都还没想清楚

需求模糊，需要探索
多种方案，需要比较
风险较高，需要验证

这种时候，plan mode 能帮你梳理思路。

什么时候不用 plan mode？

单文件小修

# 改之前
if user.age > 18:
    return True

# 改之后
if user.age >= 18:
    return True

这种改动，直接改就是了。

已知 bug 的修复

日志里明确说了哪行报错
堆栈清晰，原因明确
修复方案简单直接

简单的 feature add

加个配置项
改个默认值
调整个顺序

这种时候，plan mode 反而是负担。

Codex 官方的态度

Codex 官方也是这么讲的：

plan mode 是精密的手术刀。问题真含糊时值回票价，改个单文件的小 bug 时反而碍事。

核心思想：工具应该为你服务，而不是你为工具服务。

实践建议

快速决策树：

改动涉及公共 API？
├─ 是 → plan mode
└─ 否 → 继续

改动跨多个文件？
├─ 是 → plan mode
└─ 否 → 继续

需求是否含糊？
├─ 是 → plan mode
└─ 否 → 直接改

自己是否还没想清楚？
├─ 是 → plan mode
└─ 否 → 直接改

记住：plan mode 的目的是降低风险，不是增加流程。

二、Task List：会话级轻量，持久化慎重

两种 Task List

AI 工具里的 Task List 有两种：

1. 会话级 Task List

当前会话的 todo
会话结束就失效
工具自动维护

2. 持久化 Task List（Issue）

跨会话、跨天、跨人
落到 GitHub/GitLab Issue
需要手动管理

什么时候用会话级？

大部分时候，让工具自己维护。

## Task List
- [x] 分析代码结构
- [ ] 重构 API 层
- [ ] 更新测试
- [ ] 提交 PR

扫一眼确认它没拆歪就行。

为什么？

轻量：不需要切换上下文
实时：随对话动态调整
无需维护：会话结束自动失效

什么时候落成 Issue？

只有当一个功能要跨好几天、或者要交给别人接着做。

场景 1：跨天的工作

# Issue: 重构用户认证系统

## Day 1
- [x] 分析现有认证流程
- [x] 设计新的认证架构

## Day 2
- [ ] 实现新的认证中间件
- [ ] 更新所有 API 端点

## Day 3
- [ ] 编写测试
- [ ] 部署到 staging
- [ ] 性能测试

场景 2：跨人协作

# Issue: 实现 payment webhook

## TODO
- [ ] @alice 设计 webhook schema
- [ ] @bob 实现接收端点
- [ ] @charlie 编写测试
- [ ] @alice 部署和监控

为什么不轻易落 Issue？

Issue 有维护成本。

需要同步状态
需要协调优先级
需要跟踪进度

会话级 Task List 扛不住跨天跨人。

会话结束就失效
无法共享给他人
无法持久化状态

实践建议

决策树：

这个功能能今天完成吗？
├─ 是 → 会话级 Task List
└─ 否 → 继续

需要别人接手吗？
├─ 是 → Issue
└─ 否 → 继续

需要跨多天吗？
├─ 是 → Issue
└─ 否 → 会话级 Task List

记住：Task List 的目的是跟踪进度，不是增加管理负担。

三、note-it：5 分钟记录，换 3 个月不考古

为什么省不得 note-it？

很多人有个习惯：做的时候心里门儿清，懒得记。

为什么绕开某个方案？ 性能不好。 为什么在这儿偏离 spec？ 兼容性问题。 为什么用这个算法？ 时间复杂度最优。

三个月后：

bug 找上门了，你看着代码发呆：我当时为啥这么写？ 同事问了："这儿当初为啥这么写？" 你：额……我想想……

这就是代码考古。

note-it 的价值

note-it 是我一开始最想省、后来最舍不得省的一步。

为什么？

因为那份 issue#XXXX.html 是唯一还记得答案的地方。

例子：

# 为什么不用缓存？
# note-it: Redis 在这个环境里不可用，跨云部署成本太高。
# 暂时用内存缓存，等基础设施到位再迁移。

def get_user(user_id: int) -> User:
    # 直接查数据库，不用缓存
    return db.query(User).filter_by(id=user_id).first()

三个月后，有人问：为什么不用 Redis 缓存？

你不用考古，note-it 里有答案。

成本对比

记下来：5 分钟

为什么选 A 方案不选 B？
- A 方案性能更好（O(n) vs O(n²)）
- B 方案需要引入新依赖，增加维护成本
- A 方案代码更简单，易于理解

不记：3 个月后考古

翻 Git log：10 分钟
看当时的讨论：20 分钟
重新分析代码：30 分钟
还可能想不起来

成本比：5 分钟 vs 60 分钟

什么时候一定要 note-it？

1. 偏离 spec 的地方

# spec 要求返回 List[Dict]
# note-it: 改成返回 DataFrame 是因为下游需要用 pandas 处理
# 如果其他调用方不需要，可以考虑加个 adapter
def process_data() -> DataFrame:
    ...

2. 绕开某个方案

# 为什么不用多线程？
# note-it: 这里的数据库连接池不支持并发，多线程会导致连接泄漏
# 等升级到支持 asyncio 的驱动再考虑并行化

3. 技术债务

# note-it: 这是一个临时的 workaround
# 根本问题是第三方 API 的 bug，已经提了 issue
# 等 API 修复后需要移除这段代码
def workaround_api_bug():
    ...

4. 性能关键点

# note-it: 这里用 C 扩展是因为 Python 版本太慢（100ms vs 5ms）
# 如果有更快的纯 Python 实现，可以考虑替换
import fast_c_extension

note-it 的最佳实践

记什么？

为什么：为什么这么做
为什么不：为什么不用其他方案
权衡：选择了什么，放弃了什么
风险：有什么潜在问题

记在哪？

代码注释里（最重要）
Issue 描述里
文档里
commit message 里

怎么记？

简洁：3-5 句话
具体：提到具体的数据、事实
可追踪：如果有讨论，附上链接

实践建议

note-it 检查清单：

## 做这个决定时，我记了吗？

- [ ] 为什么选这个方案？
- [ ] 为什么不用其他方案？
- [ ] 有什么权衡？
- [ ] 有什么风险？
- [ ] 未来需要改进吗？

记住：note-it 不是给别人看的，是给未来的自己看的。

四、方法论总结：如何正确使用 AI 工具

核心原则

1. 工具为你服务，不是你为工具服务

plan mode 是工具，不是流程
Task List 是跟踪，不是负担
note-it 是投资，不是浪费

2. 轻量优先，持久化慎重

能会话解决的，不跨会话
能自动维护的，不手动管理
能快速记录的，不拖延

3. 记录决策，不是记录代码

代码自己会说话
决策需要记录
理由需要追溯

决策树

这个改动需要 plan mode 吗？
├─ 公共 API？→ 需要
├─ 跨多个文件？→ 需要
├─ 需求含糊？→ 需要
├─ 自己没想清楚？→ 需要
└─ 否 → 直接改

这个任务需要落 Issue 吗？
├─ 跨天？→ Issue
├─ 跨人？→ Issue
└─ 否 → Task List

这个决策需要 note-it 吗？
├─ 偏离 spec？→ 需要
├─ 绕开方案？→ 需要
├─ 技术债务？→ 需要
├─ 性能关键？→ 需要
└─ 否 → 可选