| name | zoom |
| description | Zoom out before zooming in. Read the surrounding system before changing an unfamiliar piece of code. |
zoom — 改前先放眼
借鉴 mattpocock/skills 的 /zoom-out. 防止 ball-of-mud:每次改不熟的代码前,先理解它在系统里的位置。
When to invoke
- 你要改的文件,本仓库里你没碰过或上次碰已经超过 5 个 turn
- Task 涉及一个不熟的模块/包/服务
- 你刚开始要写代码但说不清"这个文件被谁调用、调用谁"
不需要 zoom:你已经在这块代码里跑了几个 turn、心里有图。
5 个回答(≤10 分钟)
把答案写到 CURRENT_TASK.md 里 ## Zoom-out 段,或者作为 grill 的补充。
1. 这块代码对外是谁?
- 调用方:
grep_search 找 import / call site,列前 5 个
- 它的"公共形状":导出函数、HTTP 路由、CLI 入口、事件名
2. 这块代码对内依赖谁?
- 它 import 了什么本仓库内部模块?外部 SDK?
- 关键的边界跨越点(DB、网络、文件系统、子进程)
3. 它属于哪个抽象层?
- domain / application / infra / presentation —— 用
state/reference/CONTEXT.md → Conventions 里的项目分层语言。
- 如果这个文件穿了多层,先记到 RISKS(漏抽象信号)。
4. 已有的"做法"是什么?
- 旁边的兄弟文件怎么处理类似问题?复制兄弟的形状,不要发明新形状。
- 命名、错误处理、日志、测试、配置——找一个最像的兄弟当模板。
5. 改完之后,断言是什么?
- "改完之后,调用方 X 不应该感知任何变化"
- "改完之后,新输入 Y 应该走 Z 分支"
- 写出可观察的断言,否则你不知道改对了没有。
Output
CURRENT_TASK.md 里追加:
## Zoom-out
- 上游调用方:[`auth/middleware.ts:42`](…), [`api/login.ts:18`](…)
- 下游依赖:sessionStore, cookies(), zod schema
- 抽象层:application(路由 handler)
- 兄弟文件:`auth/logout.ts` —— 复用其错误形状
- 改完断言:登录态丢失后访问受限路由 → 302 到 /login 且 next 参数被 origin-checked
反模式
- 跳过 zoom-out 直接编辑陌生文件 → 大概率违反隐式约定
- 把"看代码 30 分钟"当成 zoom-out → zoom 是写下 5 个答案,不是无目的浏览
- zoom 完不写 brother file 就动手 → 你会发明第 7 种错误处理