V8 仓库 Gemini CLI 提示词体系实战：GEMINI.md 组装、Prompt 模板与子代理编排

V8 仓库 Gemini CLI 提示词体系实战：GEMINI.md 组装、Prompt 模板与子代理编排

【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8

本文面向希望用 AI 编码助手（gemini-cli）开发 V8 的工程师，讲解agents/prompts/目录的提示词工程方案：如何用@语法把common.md与模板拼装成本地GEMINI.md系统指令，如何用/memory show验证导入结果，并结合仓库中的构建、调试、测试命令与子代理（subagent）配置，形成一套可复用的 V8 开发智能体工作台。读完本文，你将能独立搭建并维护自己的 V8 Prompt 工作区。

一、目录定位：agents/prompts/是什么

在 V8 仓库的 agents/prompts/README.md 中明确说明：该目录存放面向 V8 的通用 Prompt（common prompt）以及用于教会 Agent 特定工具的模板 Prompt（template prompts），一切设计意图都是配合 gemini-cli 使用。

从仓库实际内容看，agents/prompts/下共三个文件/子目录：

• agents/prompts/README.md：使用说明，即本文主体；
• agents/prompts/common.md：核心的 V8 工作区系统指令，包含构建、调试、测试、提交规范与常见陷阱等大量可执行内容；
• agents/prompts/templates/：模板目录，内含README.md与modular.md，用于把提示词拆分成可按需引用的片段。

整套体系的定位是"提示词即代码"：把 V8 开发所需的工程知识（命令、目录结构、编码规范）固化进文本，让 Agent 在首次进入仓库时即可获得完整上下文，而不是靠模型"猜"V8 的构建方式。

二、组装系统指令：创建本地GEMINI.md

2.1 用@语法导入 Prompt

README 给出的核心用法非常简洁：在仓库根目录创建一个**本地、不纳入版本管理（untracked）**的GEMINI.md文件，然后用@语法引入相关提示词。例如：

@agents/prompts/common.md

这是 gemini-cli 的标准 workspace 机制：GEMINI.md相当于该仓库的"系统指令入口"，@路径负责把对应文件的全部内容展开进上下文。值得注意的是，README 强调GEMINI.md是本地、untracked的文件——即它属于开发者个人配置，不应提交进仓库（这与仓库是只读镜像、个人配置各自维护的定位一致）。

2.2 用/memory show验证导入

由于 gemini-cli 的导入是文件展开机制，很难肉眼判断某个@引用是否真的被加载。README 给出了一条可验证的命令：在 gemini-cli 中运行

/memory show

如果common.md的内容（例如其中的构建命令、目录说明）出现在 memory 输出中，就说明导入成功。这是一个非常实用的排障手段：当 Agent 表现"不知道 V8 怎么构建"时，先检查 memory 里有没有对应的 Prompt 内容，而不是盲目重写指令。

2.3 多文件组合

结合 agents/prompts/templates/README.md 可以看到，GEMINI.md可以同时引入多个文件，且模板既可叠加在基础 Prompt 之上，也可单独使用：

@agents/prompts/common.md @agents/prompts/templates/<example.md>

@agents/prompts/templates/<example.md>

第一段写法表示"基础指令 + 模板增强"，第二段则表示某个模板可独立支撑一个场景。这种设计把"常驻的系统指令"与"按需加载的专项知识"解耦，避免把所有内容塞进一个巨型文件导致上下文浪费。

三、common.md：V8 工作区系统指令的核心内容

agents/prompts/common.md 是@agents/prompts/common.md实际加载的内容，也是这套提示词体系的信息密度最高处。它被设计为"给 Agent 的 V8 速查手册"，下面按原文档脉络逐节展开。

3.1 关键命令速览

common.md 开头就给出了 Agent 最常用的五条命令（对应仓库中实际存在的 tools/dev/gm.py 与 tools/run-tests.py）：

几个细节值得注意：

• gm.py是 GN + Ninja 的封装，quiet关键字用于抑制编译进度输出、节省 token，但错误仍会照常报告（见原文档"Make sure to pass thequietkeyword unless told to otherwise"）；
• run-tests.py的--progress dots表示用点号做最小化进度输出，避免刷屏；--exit-after-n-failures=5表示累计 5 个失败即提前终止，适合 Agent 场景下快速暴露问题；
• 测试默认指向x64.optdebug构建产物，因此"构建配置与测试配置必须匹配"是后面"常见陷阱"一节强调的原则。

3.2 角色设定与三条铁律

common.md 在命令之后给出了 Agent 的角色提示（hints）：

• 你是一名 C++ 专家开发者；
• V8 面向终端用户运行不可信代码，任何正确性 bug 都可能演变成终端用户的安全问题，因此代码必须绝对正确、无 bug；
• V8 为 Web 提供 JavaScript 与 WebAssembly 运行时，做优化时必须追求最佳性能。

这三条是 V8 开发的精神内核：正确性优先（安全）、性能至上（运行时职责），被写进 Prompt 意味着每次对话都会强化这一约束。在 agents/prompts/templates/modular.md 中，这三条 hints 被原样保留，说明它是所有 V8 相关 Prompt 的公共底座。

3.3 目录结构速览：src/的二十余个核心子目录

common.md 用很大篇幅列出了 V8 源码目录结构，这是 Agent 在代码库中定位文件的"地图"。核心目录及职责整理如下（路径均在 src/ 下）：

此外还有三个顶层目录：

• test/：绝大部分测试与测试代码；
• include/：V8 的全部公共 API，供 Blink 等外部嵌入方使用；
• out/：构建产物目录，通常按构建配置分子目录存放。

这份"地图"的价值在于：Agent 遇到"性能问题"知道去compiler/或maglev/找，遇到"对象表示"去objects/，遇到"GC 崩溃"去heap/，从而避免盲目全局搜索。仓库内 agents/skills/v8-structure/SKILL.md 与 agents/skills/v8-understanding/SKILL.md 是对此的更深入展开，可配合阅读。

3.4 构建：gm.py与三种构建配置

common.md 指出：依赖装好之后，V8 用gm.py（GN 与 Ninja 的封装）构建，并给出三个使用示例：

# 列出所有可用构建配置与目标 tools/dev/gm.py # 以 release 模式为 x64 构建 d8 shell tools/dev/gm.py quiet x64.release # 以 debug 模式为 x64 构建 d8 tools/dev/gm.py quiet x64.debug

三种构建配置的语义如下：

• release：面向性能优化、剥离调试信息，用于基准测试（benchmarking）；
• debug：包含完整调试信息并启用断言（assertions），速度较慢，但调试必备；
• optdebug：优化与调试信息兼得的折中方案，适合日常开发。

sync参数用于构建前同步依赖：

• --sync：构建前执行gclient sync -D；
• --sync=force：构建前执行gclient sync -D --force --reset（强制重置）。

原文档特别强调：除非被告知，否则始终传quiet关键字，以免编译进度浪费 token，错误信息仍会正常输出。

3.5 调试：d8 + GDB 与诊断 Flags

调试推荐使用debug或optdebug构建，用 GDB 或 LLDB 做原生代码调试：

# 用 gdb 运行 d8 的示例 gdb --args out/x64.debug/d8 --my-flag my-script.js

V8 提供丰富的诊断 flags，common.md 列出的最常用四个：

全部 flags 可通过out/x64.debug/d8 --help查看。从源码佐证：绝大多数 V8 flags 定义在 src/flags/flag-definitions.h（该文件是DEFINE_*宏与DEFINE_IMPLICATION推导规则的中枢，例如lite_mode会隐式推导出jitless与optimize_for_size），而d8shell 专属 flags 位于 src/d8/d8.cc 的Shell::SetOptions函数中——这与原文档描述完全一致。

此外，原文档给出一个非常实用的 Torque 调试技巧：排查 Torque 代码问题时，查看out/<build-config>/gen/torque-generated/下生成的 C++ 文件，可以看到实际执行的底层 CodeStubAssembler 代码。这印证了 V8 的 Torque → CSA C++ 的生成式编译流程（参考 docs/torque/architecture.md）。

3.6 测试：run-tests.py与三类测试套件

主要测试脚本是 tools/run-tests.py，需要指定构建输出目录与要跑的测试。三个关键测试套件：

• unittests：V8 内部组件的 C++ 单元测试；
• cctest：另一种较老的 C++ 单元测试格式（已弃用，正在迁移到 unittests）；
• mjsunit：针对 JavaScript 语言特性与内建函数的 JS 测试。

# 对 x64.optdebug 构建运行全部标准测试 tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug # 运行指定测试套件（如 cctest） tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest # 运行指定测试文件 tools/run-tests.py --progress dots --exit-after-n-failures=5 --outdir=out/x64.optdebug cctest/test-heap

原文档强调必须传--progress dots以最小化进度输出。测试失败时，输出会给出 stderr 与可复现命令，例如：

=== mjsunit/maglev/regress-429656023 === --- stderr --- # # Fatal error in ../../src/heap/local-factory.h, line 41 # unreachable code # ...stack trace... Received signal 6 Command: out/x64.optdebug/d8 --test test/mjsunit/mjsunit.js test/mjsunit/maglev/regress-429656023.js --random-seed=-190258694 --nohard-abort --verify-heap --allow-natives-syntax

复现方式有两种：一是继续用run-tests.py按测试名重跑：

tools/run-tests.py --progress dots --outdir=out/x64.optdebug mjsunit/maglev/regress-429656023

二是直接运行输出中给出的命令；直接运行时可以附加额外 flags 辅助调试，也可以换一个构建类型（例如 release 失败时换 debug 构建跑）。该例还展示了--random-seed、--nohard-abort、--verify-heap等典型组合，是 Agent 复现崩溃类问题的标准模板。

3.7 编码与提交规范

[component]: Short description of the change Longer description explaining the "why" of the change, not just the "what". Wrap lines at 72 characters. Bug: 123456

提交规范要点：

• 风格：始终遵循周边代码的风格约定；除此之外遵循 Chromium 的 C++ 风格指南；
• 格式化：提交前用git cl format自动格式化；
• commit message 格式：首行[组件]: 简短描述（如compiler、runtime、api），空行后写"为什么"的长描述（解释 why 而非 what，72 字符换行），最后Bug:行关联问题跟踪器，对追溯至关重要。

3.8 常见陷阱与最佳实践清单

common.md 用一整节总结了 Agent 在 V8 里写代码时必须遵守的纪律，这是避免"AI 改坏 V8"的关键：

1. 提交前务必格式化：创建 commit 前运行git cl format；
2. 不要编辑生成文件：out/下文件由构建过程生成，改动应落在源文件（Torque 改.tq、协议定义改.pdl）；
3. 测试配置与构建匹配：例如构建了x64.debug就从out/x64.debug跑 mjsunit；
4. 先研究周边代码约定：添加新代码前，先研究所在文件/目录的既有模式、命名约定与架构选择；
5. 不要改动无关代码：保持 diff 最小，只改目标代码；想清理附近代码应另开 patch（"suggest it to me for a separate patch"）；
6. 相关函数放一起：新增函数尽量插在相近函数附近；
7. 不要猜头文件名：不知道类或函数定义在哪，就搜索而非猜测头文件名；
8. 注意前置声明：很多类型只做了 forward declaration，要用就得找到定义；
9. 注意内联函数定义：许多函数在.h中声明为inline、实现在-inl.h文件中；出现"缺少定义"的编译错误通常是漏#include了-inl.h；且-inl.h只能被其他-inl.h和.cc文件包含。

四、模板机制：templates/目录的定位

agents/prompts/templates/README.md 定义了模板的使用方式（见 2.3 节），而 agents/prompts/templates/modular.md 则是一个完整的"模块化 V8 工作区"模板范例，展示了比裸common.md更进阶的组织形态：

• 保留common.md的三条 hints（C++ 专家、正确性/安全、性能）；
• 新增Subagents Setup：gemini-cli 环境运行vpython3 agents/scripts/install_for_gemini_cli.py（在.gemini/agents/生成子代理文件），Jetski 环境运行vpython3 agents/scripts/install_for_jetski.py（在.agents/agents/创建符号链接）；
• 将详细知识下沉到专业化子代理（Researcher/Builder/Tester/Debugger，见agents/agents/下对应目录），按需调用；
• 以Skills & Rules链接形式引用专项知识：如 v8-commands、v8-testing、v8-setup、git-cl、torque、v8-best-practices 等；
• 强调强制编排（Mandatory Orchestration）：任何 V8 任务，主 Agent 必须充当 Orchestrator，调用agents/agents/中定义的专用子代理，并遵守 framework 与 execution-constraints 两条规则，以保证效率、并行性与一致性。

也就是说，common.md是"单文件、全量注入"的轻量方案；templates/modular.md是"模块化、按需编排"的进阶方案，两者由同一个GEMINI.md机制驱动，可按需求选择。

五、子代理与安装脚本：提示词体系的延伸

虽然 README 本身简短，但结合仓库可以还原出完整闭环——模板中提到的安装脚本与子代理是这套 Prompt 工程的上游与下游：

安装脚本（生成侧）

• agents/scripts/install_for_gemini_cli.py：遍历agents/agents/下每个子目录，读取agent.json与config.yaml，把system_prompt_sections拼装为正文，把tool_names映射为 gemini-cli 工具名（如view_file→read_file、run_command→run_shell_command、list_dir→list_directory、search_web→google_web_search），生成带 YAML frontmatter 的.<repo_root>/.gemini/agents/<name>.md；若根目录尚无GEMINI.md，还会自动写入@[Modular Rules](https://link.gitcode.com/i/e5c72a1dd51d2f7f53d07379a4ab5611)一行——即默认采用模块化模板作为入口；
• agents/scripts/install_for_jetski.py：面向 Jetski 环境，在./agents/下创建符号链接指向agents/内的 agents、skills、rules、plugins 等，同样会在缺少GEMINI.md时写入 modular.md 引用。

子代理定义（内容侧）

以 agents/agents/builder/ 为例，agent.json声明名称与描述（"Specializes in building V8."），config.yaml的system_prompt_sections给出指令（"You are a build assistant. Your goal is to compile V8 for specified configurations. You can read files and search code to understand build errors."），tool_names授权run_command、view_file、grep_search、list_dir、mcp_*等工具。同理还有 researcher、tester、debugger 三个子代理，分别负责代码探索、测试运行与 GDB 崩溃调查。

配套规则

• agents/rules/framework.md：强制编排、环境感知（jetski vs gemini-cli）、工作流专项化（调试/性能等）、允许后台 Clippy 在 side worktree 自主工作但不得改动用户活动 worktree；
• agents/rules/execution-constraints.md：禁止工具死循环、精准读取文件、不用浏览器、强制编排、避免交互式分页器（用--no-pager或PAGER=cat）、上传 CL 前用git diff --name-only origin/main..HEAD校验 diff 等 11 条执行纪律。

由此可以推断：agents/prompts/是这套"V8 智能体开发环境"的入口与说明书——GEMINI.md引用它，它引用common.md/模板，模板又指向子代理与规则，形成从"系统指令"到"执行单元"的完整链路。

六、已知问题与贡献指南

6.1 已知问题：Import 作用域限制

README 明确记录了一个已知问题（对应 gemini-cli 的 issue #4098）：所有@导入必须限定在当前 Prompt 文件所在的作用域内。具体规则是：

• a/prompt.md可以导入a/prompt2.md或a/b/prompt3.md；
• 但不能导入c/prompt4.md（跨目录导入不被支持）。

这对组织 Prompt 有直接影响：如果你想把agents/prompts/templates/里的模板从其他位置的GEMINI.md引用，必须注意路径层级关系，必要时把共享片段放到能被合法引用到的目录。

6.2 贡献指南

• 修改common.md必须格外谨慎：它被广泛使用（broadly used），任何改动都会影响所有以此为基座的 Agent 工作区；
• 新增想分享的 Prompt 应放入templates/目录：即新增内容走"模板化"路线，而不是直接改动公共底座。

这套约定保证了"公共基础稳定、专项能力增量扩展"，与 2.3 节"基础指令 + 按需模板"的设计哲学一脉相承。

七、结语

agents/prompts/README.md篇幅不长，但它描述的是一套完整、可落地的 V8 × gemini-cli 提示词工程方案：用GEMINI.md+@语法组装系统指令，用/memory show验证加载，以common.md提供构建/调试/测试/提交的权威速查，以templates/modular.md组织模块化工作区与子代理编排。对于希望把 AI 助手变成合格 V8 开发者的团队或个人，这套结构本身就是最佳实践范本——先固化知识，再交给 Agent 执行。

【免费下载链接】v8The official mirror of the V8 Git repository项目地址: https://gitcode.com/gh_mirrors/v81/v8