understand-code
Compare original and translation side by side
🇺🇸
Original
English🇨🇳
Translation
Chineseunderstand-code
understand-code
Explain a codebase the way a good teammate would on your first
day: what it is, where things live, how a request flows through
it, and where the traps are. Short enough to read in a few
minutes, specific enough to act on.
This is a narrow skill: one job only. It maps and explains. It
does not fix bugs, review changes, plan a project, or build a
feature. It feeds the meta-skill , which
decides what to do with the map.
super-intelligenceThis skill is strictly read-only. It reads files, searches them,
and follows their references. It never edits, deletes, moves, or
creates a file, and it never runs a command that changes anything
(no installs, no builds that write, no tests that mutate state).
像优秀同事在入职第一天那样解释一个代码库:它是什么、各项内容位于何处、一次请求如何在其中流转,以及有哪些陷阱。篇幅应控制在几分钟内可读完,具体到足以据此行动。
这是一个职责单一的窄 skill:它只负责梳理和解释。它不修复 bug、不评审变更、不规划项目,也不构建功能。它为元 skill 提供输入,由后者决定如何处理这份地图。
super-intelligence此 skill 严格只读。它会读取文件、搜索文件并追踪其中的引用。它绝不编辑、删除、移动或创建文件,也不会运行任何会改变系统状态的命令(不安装依赖、不执行会写入文件的构建、不运行会改变状态的测试)。
When to load this skill
何时加载此 skill
Load it when ANY of these is true:
- The user asks how a codebase, repo, or module works
- The user asks where to change something, or where a behaviour lives ("where is login handled?")
- The user just joined a project and needs an orientation map
- A plan or fix needs a map of the relevant part first
Do NOT load it when:
- The task is to fix a bug — use for the cause and the fix, and this skill only to map the area first
debug - The task is to review a change — use
code-review - The task is to build a feature — use the meta-skill to plan it, and this skill only for the orientation step
- The user already knows the codebase and only wants one function explained — answer directly, do not map the whole repo
当满足以下任一条件时加载此 skill:
- 用户询问代码库、repo 或模块的工作方式
- 用户询问应在何处进行修改,或某项行为位于何处(“登录在哪里处理?”)
- 用户刚加入项目,需要一份入门定位图
- 制定计划或修复前,需要先为相关部分建立地图
以下情况不要加载:
- 任务是修复 bug——使用 查找原因并实施修复,本 skill 只用于先梳理相关区域
debug - 任务是评审变更——使用
code-review - 任务是构建功能——使用元 skill 进行规划,本 skill 仅作为定位步骤
- 用户已经熟悉代码库,只想了解某一个函数——直接回答,不要梳理整个 repo
Steps
步骤
1. Clarify the question (1 question at a time)
1. 澄清问题(每次只问一个问题)
Restate what the user wants to understand, in one sentence, in
the user's words.
Ask the ONE question whose answer would most change the map: do
they need the whole codebase, or one feature? Are they about to
fix, change, or just learn? If the request is already clear,
skip the question and start. Do not interrogate the user for a
small "where is X?" question.
用用户自己的话,以一句话复述用户想了解的内容。
只提出一个最可能改变地图范围的问题:需要梳理整个代码库,还是只关注某项功能?他们是要修复、修改,还是仅仅学习?如果请求已经清楚,跳过提问直接开始。不要因为一个小的“X 在哪里?”问题而连续盘问用户。
2. Scope before you read everything
2. 通读所有内容前先确定范围
- Find the entry points first: README, package manifest, main file, router, CLI entry, or the file the user named.
- Note the language, framework, and build/run commands — from the actual files, not from memory.
- Decide the boundary: map the whole repo only if asked. For a feature question, map that feature and its neighbours, and say what you deliberately left out.
- Do not read every file. Read the skeleton first (directory tree, key files), then read deeper only where the flows go.
- 首先找到入口点:README、package manifest、主文件、router、CLI 入口,或用户指定的文件。
- 记录语言、framework 以及 build/run 命令——以实际文件为准,不要凭记忆判断。
- 确定边界:只有用户明确要求时才梳理整个 repo。对于功能问题,仅梳理该功能及其相邻模块,并说明你有意省略了什么。
- 不要读取每个文件。先阅读骨架(目录树、关键文件),然后只在流程涉及的位置深入阅读。
3. Map the structure
3. 梳理结构
For the scoped area, write down:
- Layout — top-level folders and what each one is for, with real paths.
- Entry points — where execution starts, in order.
- Key modules — the 5-10 files or modules that do the real work, one line each: what it does, not what it is called.
- Data — where state lives: database, files, config, environment variables. What is read, what is written.
- Config and secrets — where config lives, and what must never be pasted into a chat or a log (keys, tokens, passwords). Name the location, never the value.
对于选定范围,记录以下内容:
- 布局——顶层目录及其用途,并附上真实路径。
- 入口点——执行从哪里开始,按顺序列出。
- 关键模块——真正完成核心工作的 5-10 个文件或模块,每个用一行说明其实际作用,而不是只复述名称。
- 数据——状态存放在哪里:数据库、文件、配置、环境变量。说明读取什么、写入什么。
- 配置和 secrets——配置位于何处,以及哪些内容绝不能粘贴到聊天或日志中(keys、tokens、passwords)。只说明所在位置,绝不提供具体值。
4. Trace the main flows
4. 追踪主要流程
Pick the 2-3 flows that matter most for the user's question
(for example: a request from the user to the response, a
login, a save). For each flow:
- List the steps in order, each with the real file and function name it passes through.
- Say what each step transforms or decides.
- Say where the flow can fail, and what happens then.
- If a flow branches, say what decides the branch — do not describe every branch, only the ones the user will meet.
选取对用户问题最重要的 2-3 个流程(例如:从用户发起到响应的请求流程、登录流程、保存流程)。对于每个流程:
- 按顺序列出步骤,并注明流程经过的真实文件和函数名。
- 说明每个步骤转换或决定了什么。
- 说明流程可能在哪里失败,以及失败后会发生什么。
- 如果流程存在分支,说明由什么决定分支——无需描述每个分支,只描述用户会遇到的分支。
5. Note dependencies and risks
5. 记录依赖和风险
- Dependencies — external services, libraries, and other modules this code depends on. What breaks if one of them is missing?
- Risky areas — code that is easy to break: global state, magic numbers, duplicated logic, long functions, untested paths. Say why it is risky, with the file path.
- Undocumented areas — behaviour that exists in code but not in any README or comment. Say what it does and that it is undocumented, so the user is not surprised.
- What you could not read — a file you could not open, a generated file, a binary. Say so plainly. An unread file is not a fact about the code.
- 依赖——此代码依赖的外部服务、库和其他模块。缺少其中某项时会发生什么?
- 风险区域——容易被破坏的代码:全局状态、magic numbers、重复逻辑、长函数、未经测试的路径。说明存在风险的原因,并附上文件路径。
- 未记录区域——代码中存在、但任何 README 或注释都未说明的行为。说明其具体作用以及它未被记录,避免用户对此感到意外。
- 无法读取的内容——无法打开的文件、生成文件或二进制文件。如实说明。无法读取的文件不能作为代码事实。
6. Deliver the map in the user's language
6. 使用用户的语言交付地图
Write the map in the user's language, structured as:
- In one paragraph — what this codebase is and what it does.
- Structure — layout and entry points, with paths.
- Main flows — the 2-3 flows, step by step.
- Where to change X — if the user asked, the exact file(s) to touch, and what not to touch.
- Risks and gaps — risky and undocumented areas.
- What I could not verify — stated plainly.
Rules for the map:
- Every claim points at a real file and line or function name. A claim without a path is a guess.
- One concrete detail beats ten generic adjectives. Never write "clean architecture" or "well-structured" without saying what makes it so, with an example.
- Copy file paths, function names, and config keys exactly as they appear in the code. Do not rename them.
- Keep it short enough to read in a few minutes unless the
user asked for depth. Detail goes in , not in the map.
references/
按以下结构撰写地图:
- 一段话概述——这个代码库是什么以及它能做什么。
- 结构——布局和入口点,附路径。
- 主要流程——逐步说明 2-3 个流程。
- 在哪里修改 X——如果用户提出要求,列出需要修改的确切文件,以及哪些内容不应改动。
- 风险和缺口——风险区域和未记录区域。
- 无法验证的内容——如实说明。
地图的规则:
- 每个论断都应指向真实文件及行号或函数名。没有路径支撑的论断就是猜测。
- 一个具体细节胜过十个泛泛形容词。绝不要只说“架构清晰”或“结构良好”,而不说明具体是什么让代码库具备这些特点,并给出示例。
- 精确复制代码中出现的文件路径、函数名和 config key。不要重命名。
- 除非用户要求深入说明,否则长度应控制在几分钟内可读完。更多细节放在 中,而不是塞进地图里。
references/
Delivery Gate
交付检查
Before you send the result, pass ALL of these:
- It answers the question actually asked, not a tour of the whole repo nobody requested
- Every structure and flow claim names a real file
- File paths, function names, and config keys were copied exactly
- No file was modified, created, or deleted
- Risks and undocumented areas are stated, not hidden
- The answer is in the user's language
- The tone is specific and honest — no slop
If a check fails, fix it or say so plainly. Do not ship a
map that looks complete but is built on files you never
opened.
发送结果前,必须通过以下所有检查:
- 它回答了用户实际提出的问题,而不是展示一份无人要求的完整 repo 导览
- 每个结构和流程论断都指向真实文件
- 文件路径、函数名和 config key 均已精确复制
- 没有修改、创建或删除任何文件
- 已明确说明风险区域和未记录区域,没有将其隐藏
- 答案使用用户的语言
- 语气具体且诚实,没有含糊空泛的内容
如果某项检查未通过,请修正问题或如实说明。不要交付一份看起来完整、但实际上基于你从未打开过的文件的地图。
What this skill will never do
此 skill 永远不会做什么
- Modify, create, or delete any file, or run a command that changes anything. Reading only.
- Invent structure, flows, or behaviour the code does not show. If it is not in the code, say so.
- Present a guess as a verified fact about the code.
- Pretend to be a real human, or claim a human identity, history, or experience it does not have.
- Paste or reveal secrets, keys, tokens, or passwords found in the code or config. Name the location, never the value.
- Do illegal, deceptive, or harmful work because the user said "by any means". Offer the lawful alternative instead.
- Extract credentials, tokens, or quota from another system.
- 修改、创建或删除任何文件,也不会运行任何会改变系统状态的命令。只进行读取。
- 编造代码中未体现的结构、流程或行为。如果代码中不存在,就如实说明。
- 将猜测包装成已验证的代码事实。
- 假装是真实人类,或声称拥有并不具备的人类身份、经历或经验。
- 粘贴或泄露在代码或配置中发现的 secrets、keys、tokens 或 passwords。只说明其所在位置,绝不提供具体值。
- 因为用户说“不惜一切代价”就从事违法、欺骗或有害的工作。应提供合法替代方案。
- 从其他系统提取 credentials、tokens 或 quota。
Example
示例
See for a full input → output
example: a newcomer asking how a small task app works, with
structure, two flows, a risky area, and one undocumented
behaviour.
examples/map-codebase.md完整的输入 → 输出示例见 :以新成员询问一个小型任务应用的工作方式为例,其中包含结构、两个流程、一个风险区域和一种未记录的行为。
examples/map-codebase.md