[{"data":1,"prerenderedAt":1172},["ShallowReactive",2],{"blog-codex-ecosystem-guide":3},{"id":4,"title":5,"body":6,"category":1159,"date":1160,"description":16,"extension":1161,"meta":1162,"navigation":135,"path":1163,"seo":1164,"stem":1165,"tags":1166,"__hash__":1171},"blog\u002Fblog\u002Fcodex-ecosystem-guide.md","让 Codex 读懂你的代码库：AGENTS.md、Skills、MCP 与 Hooks",{"type":7,"value":8,"toc":1146},"minimark",[9,13,17,29,32,42,45,53,58,86,89,106,112,115,277,287,294,297,303,306,381,384,461,475,480,487,495,515,518,559,562,573,577,583,593,596,602,607,708,711,735,742,747,751,754,774,784,819,822,843,850,855,859,862,890,893,937,940,983,986,991,995,998,1001,1012,1015,1032,1035,1041,1044,1049,1052,1055,1126,1132,1135,1142],[10,11,5],"h1",{"id":12},"让-codex-读懂你的代码库agentsmdskillsmcp-与-hooks",[14,15,16],"p",{},"Codex 最强的地方，是它能读文件、改代码、跑命令、接外部系统。Codex 最危险的地方，也正是它能读文件、改代码、跑命令、接外部系统。",[14,18,19,20,24,25,28],{},"所以真正的问题不是“怎么让 Codex 更聪明”，而是“怎么让 Codex 在正确上下文里，用正确能力，遵守正确规则”。这背后有一套可编程生态：",[21,22,23],"code",{},"AGENTS.md","、",[21,26,27],{},".codex\u002Fconfig.toml","、Skills、MCP、Hooks、Subagents、Memories。",[14,30,31],{},"很多人把这些东西混在一起，最后项目里到处都是重复规则。更好的心智是：",[33,34,40],"pre",{"className":35,"code":37,"language":38,"meta":39},[36],"language-text","常驻规则：AGENTS.md\n安全配置：.codex\u002Fconfig.toml\n标准流程：Skills\n外部能力：MCP\n生命周期护栏：Hooks\n隔离探索：Subagents\n低优先级历史事实：Memories\n","text","",[21,41,37],{"__ignoreMap":39},[14,43,44],{},"这篇把它们拆清楚，顺便讲大仓里怎么用分层规则和 subagent 控制上下文预算。",[46,47,49,50,52],"h2",{"id":48},"_1-agentsmd项目指导的主入口","1. ",[21,51,23],{},"：项目指导的主入口",[14,54,55,57],{},[21,56,23],{}," 是 Codex 的常驻项目指导。它适合写那些“每次进这个仓库都必须知道”的东西：",[59,60,61,65,68,71,74,77,80,83],"ul",{},[62,63,64],"li",{},"项目是做什么的",[62,66,67],{},"技术栈和包管理器",[62,69,70],{},"绝对铁律",[62,72,73],{},"目录地图",[62,75,76],{},"常用命令",[62,78,79],{},"风格锚点",[62,81,82],{},"review 准则",[62,84,85],{},"Skills \u002F docs 索引",[14,87,88],{},"它不适合写：",[59,90,91,94,97,100,103],{},[62,92,93],{},"大段 API 文档",[62,95,96],{},"多步骤 SOP",[62,98,99],{},"一次性任务细节",[62,101,102],{},"secrets \u002F token",[62,104,105],{},"机器生成的完整目录树",[14,107,108,109,111],{},"一个好的根 ",[21,110,23],{}," 应该像机场导览图，不应该像百科全书。它告诉 Codex 去哪里找东西、哪些地方不能碰、什么命令能验证，而不是把全部知识都塞进上下文。",[14,113,114],{},"示例骨架：",[33,116,120],{"className":117,"code":118,"language":119,"meta":39,"style":39},"language-markdown shiki shiki-themes github-dark","# 项目 Codex 指南\n\n## 项目速览\n- 业务：支付与结算平台\n- 架构：DDD + Hexagonal\n- 语言：TypeScript \u002F Node\n- 包管理器：pnpm\n\n## 绝对铁律\n- 必须使用 pnpm，禁止 npm\u002Fyarn\n- 禁止在日志中输出 PII、token、完整卡号\n- 金额必须使用 Money value object，禁止 JS number\n\n## 目录地图\n- services\u002Fapi\u002F：HTTP\u002FRPC 入口\n- packages\u002Fdomain\u002F：领域模型\n- services\u002Fbilling\u002F：计费服务，高风险\n\n## 命令\n- pnpm typecheck\n- pnpm test\n- pnpm --filter billing test\n\n## Review 准则\n- Findings first，按 severity 排序\n- 只报告真实风险：bug、安全、数据丢失、并发、测试缺口\n","markdown",[21,121,122,130,137,143,149,155,161,167,172,178,184,190,196,201,207,213,219,225,230,236,242,248,254,259,265,271],{"__ignoreMap":39},[123,124,127],"span",{"class":125,"line":126},"line",1,[123,128,129],{},"# 项目 Codex 指南\n",[123,131,133],{"class":125,"line":132},2,[123,134,136],{"emptyLinePlaceholder":135},true,"\n",[123,138,140],{"class":125,"line":139},3,[123,141,142],{},"## 项目速览\n",[123,144,146],{"class":125,"line":145},4,[123,147,148],{},"- 业务：支付与结算平台\n",[123,150,152],{"class":125,"line":151},5,[123,153,154],{},"- 架构：DDD + Hexagonal\n",[123,156,158],{"class":125,"line":157},6,[123,159,160],{},"- 语言：TypeScript \u002F Node\n",[123,162,164],{"class":125,"line":163},7,[123,165,166],{},"- 包管理器：pnpm\n",[123,168,170],{"class":125,"line":169},8,[123,171,136],{"emptyLinePlaceholder":135},[123,173,175],{"class":125,"line":174},9,[123,176,177],{},"## 绝对铁律\n",[123,179,181],{"class":125,"line":180},10,[123,182,183],{},"- 必须使用 pnpm，禁止 npm\u002Fyarn\n",[123,185,187],{"class":125,"line":186},11,[123,188,189],{},"- 禁止在日志中输出 PII、token、完整卡号\n",[123,191,193],{"class":125,"line":192},12,[123,194,195],{},"- 金额必须使用 Money value object，禁止 JS number\n",[123,197,199],{"class":125,"line":198},13,[123,200,136],{"emptyLinePlaceholder":135},[123,202,204],{"class":125,"line":203},14,[123,205,206],{},"## 目录地图\n",[123,208,210],{"class":125,"line":209},15,[123,211,212],{},"- services\u002Fapi\u002F：HTTP\u002FRPC 入口\n",[123,214,216],{"class":125,"line":215},16,[123,217,218],{},"- packages\u002Fdomain\u002F：领域模型\n",[123,220,222],{"class":125,"line":221},17,[123,223,224],{},"- services\u002Fbilling\u002F：计费服务，高风险\n",[123,226,228],{"class":125,"line":227},18,[123,229,136],{"emptyLinePlaceholder":135},[123,231,233],{"class":125,"line":232},19,[123,234,235],{},"## 命令\n",[123,237,239],{"class":125,"line":238},20,[123,240,241],{},"- pnpm typecheck\n",[123,243,245],{"class":125,"line":244},21,[123,246,247],{},"- pnpm test\n",[123,249,251],{"class":125,"line":250},22,[123,252,253],{},"- pnpm --filter billing test\n",[123,255,257],{"class":125,"line":256},23,[123,258,136],{"emptyLinePlaceholder":135},[123,260,262],{"class":125,"line":261},24,[123,263,264],{},"## Review 准则\n",[123,266,268],{"class":125,"line":267},25,[123,269,270],{},"- Findings first，按 severity 排序\n",[123,272,274],{"class":125,"line":273},26,[123,275,276],{},"- 只报告真实风险：bug、安全、数据丢失、并发、测试缺口\n",[14,278,279,283,284,286],{},[280,281,282],"strong",{},"小结："," ",[21,285,23],{}," 负责常驻规则和导航。它越精炼，Codex 越容易抓住重点。",[46,288,290,291,293],{"id":289},"_2-分层-agentsmd大仓的上下文预算管理","2. 分层 ",[21,292,23],{},"：大仓的上下文预算管理",[14,295,296],{},"大仓最大的问题不是代码太多，而是“无关上下文太多”。计费模块的规则不该常驻到前端任务里；遗留对账模块的禁令也不该污染普通 API 改动。",[14,298,299,300,302],{},"Codex 会把全局、项目、当前目录路径上的 ",[21,301,23],{}," 串起来。越靠近当前目录的指导越晚出现，也就越具体。",[14,304,305],{},"推荐四层：",[307,308,309,325],"table",{},[310,311,312],"thead",{},[313,314,315,319,322],"tr",{},[316,317,318],"th",{},"层级",[316,320,321],{},"文件",[316,323,324],{},"内容",[326,327,328,342,355,368],"tbody",{},[313,329,330,334,339],{},[331,332,333],"td",{},"全局",[331,335,336],{},[21,337,338],{},"~\u002F.codex\u002FAGENTS.md",[331,340,341],{},"个人偏好、commit 风格、默认语言",[313,343,344,347,352],{},[331,345,346],{},"项目",[331,348,349],{},[21,350,351],{},"\u003Crepo>\u002FAGENTS.md",[331,353,354],{},"项目铁律、目录地图、命令",[313,356,357,360,365],{},[331,358,359],{},"子系统",[331,361,362],{},[21,363,364],{},"\u003Crepo>\u002F\u003Carea>\u002FAGENTS.md",[331,366,367],{},"后端\u002F前端\u002Finfra 特有规范",[313,369,370,373,378],{},[331,371,372],{},"模块",[331,374,375],{},[21,376,377],{},"\u003Crepo>\u002F\u003Carea>\u002F\u003Cmodule>\u002FAGENTS.override.md",[331,379,380],{},"高风险模块禁令、历史坑",[14,382,383],{},"高风险模块可以这样写：",[33,385,387],{"className":117,"code":386,"language":119,"meta":39,"style":39},"# Billing 服务\n\n## 风险级别：高\n- 涉及金额必须用 Decimal \u002F Money，禁止 JS number\n- 涉及货币必须显式 ISO 4217 code\n- 改动必须附单测和集成测试\n\n## 关键不变量\n1. 账单 issued 后金额不可修改，只能 credit note\n2. 对账差额超过 0.01 必须报警\n3. 支付网关 webhook 可能乱序，消费者必须幂等\n\n## 禁止事项\n- 禁止重构 legacy-reconcile.ts，除非有单独 RFC\n- 禁止修改 reconcile_v1.sql 的导出字段\n",[21,388,389,394,398,403,408,413,418,422,427,432,437,442,446,451,456],{"__ignoreMap":39},[123,390,391],{"class":125,"line":126},[123,392,393],{},"# Billing 服务\n",[123,395,396],{"class":125,"line":132},[123,397,136],{"emptyLinePlaceholder":135},[123,399,400],{"class":125,"line":139},[123,401,402],{},"## 风险级别：高\n",[123,404,405],{"class":125,"line":145},[123,406,407],{},"- 涉及金额必须用 Decimal \u002F Money，禁止 JS number\n",[123,409,410],{"class":125,"line":151},[123,411,412],{},"- 涉及货币必须显式 ISO 4217 code\n",[123,414,415],{"class":125,"line":157},[123,416,417],{},"- 改动必须附单测和集成测试\n",[123,419,420],{"class":125,"line":163},[123,421,136],{"emptyLinePlaceholder":135},[123,423,424],{"class":125,"line":169},[123,425,426],{},"## 关键不变量\n",[123,428,429],{"class":125,"line":174},[123,430,431],{},"1. 账单 issued 后金额不可修改，只能 credit note\n",[123,433,434],{"class":125,"line":180},[123,435,436],{},"2. 对账差额超过 0.01 必须报警\n",[123,438,439],{"class":125,"line":186},[123,440,441],{},"3. 支付网关 webhook 可能乱序，消费者必须幂等\n",[123,443,444],{"class":125,"line":192},[123,445,136],{"emptyLinePlaceholder":135},[123,447,448],{"class":125,"line":198},[123,449,450],{},"## 禁止事项\n",[123,452,453],{"class":125,"line":203},[123,454,455],{},"- 禁止重构 legacy-reconcile.ts，除非有单独 RFC\n",[123,457,458],{"class":125,"line":209},[123,459,460],{},"- 禁止修改 reconcile_v1.sql 的导出字段\n",[14,462,463,464,467,468,471,472,474],{},"如果仓库已有 ",[21,465,466],{},"TEAM_GUIDE.md"," 这类文件，可以在 config 里配置 fallback 文件名；如果指导文件太大，可以调高 ",[21,469,470],{},"project_doc_max_bytes","，但更推荐拆成 nested ",[21,473,23],{},"。",[14,476,477,479],{},[280,478,282],{}," 大仓的核心原则是：让 Codex 在需要的时候看到需要的那部分。分层指导比一个巨大的根文件更可靠。",[46,481,483,484,486],{"id":482},"_3-codexconfigtoml模型权限和-mcp-的配置层","3. ",[21,485,27],{},"：模型、权限和 MCP 的配置层",[14,488,489,491,492,494],{},[21,490,23],{}," 讲规则，",[21,493,27],{}," 管配置。它适合放：",[59,496,497,500,503,506,509,512],{},[62,498,499],{},"默认模型和 reasoning",[62,501,502],{},"sandbox \u002F approval 策略",[62,504,505],{},"project docs 发现规则",[62,507,508],{},"MCP server 配置",[62,510,511],{},"hooks 配置",[62,513,514],{},"permissions profile",[14,516,517],{},"项目级配置只应放团队共识，不应放个人凭据、provider、auth、telemetry 这类机器本地设置。一个保守的项目级配置大概是：",[33,519,523],{"className":520,"code":521,"language":522,"meta":39,"style":39},"language-toml shiki shiki-themes github-dark","approval_policy = \"on-request\"\nsandbox_mode = \"workspace-write\"\nproject_doc_max_bytes = 65536\nproject_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"]\n\n[sandbox_workspace_write]\nnetwork_access = false\n","toml",[21,524,525,530,535,540,545,549,554],{"__ignoreMap":39},[123,526,527],{"class":125,"line":126},[123,528,529],{},"approval_policy = \"on-request\"\n",[123,531,532],{"class":125,"line":132},[123,533,534],{},"sandbox_mode = \"workspace-write\"\n",[123,536,537],{"class":125,"line":139},[123,538,539],{},"project_doc_max_bytes = 65536\n",[123,541,542],{"class":125,"line":145},[123,543,544],{},"project_doc_fallback_filenames = [\"TEAM_GUIDE.md\", \".agents.md\"]\n",[123,546,547],{"class":125,"line":151},[123,548,136],{"emptyLinePlaceholder":135},[123,550,551],{"class":125,"line":157},[123,552,553],{},"[sandbox_workspace_write]\n",[123,555,556],{"class":125,"line":163},[123,557,558],{},"network_access = false\n",[14,560,561],{},"新版本 Codex 也支持权限 profiles，用更细的方式描述文件系统和网络权限。无论使用旧 sandbox 还是新 permissions profile，原则都一样：默认最小权限，确实需要时再打开。",[14,563,564,283,566,568,569,572],{},[280,565,282],{},[21,567,23],{}," 是“该怎么做”，",[21,570,571],{},"config.toml"," 是“能怎么做”。两者不要混用。",[46,574,576],{"id":575},"_4-skills按需加载的标准作业流程","4. Skills：按需加载的标准作业流程",[14,578,579,580,582],{},"如果一件事是多步骤流程，就不要塞进 ",[21,581,23],{},"，写 Skill。",[14,584,585,586,589,590],{},"Skill 是一个目录，至少有 ",[21,587,588],{},"SKILL.md","。Codex 启动时只知道每个 Skill 的名称、描述和路径；真正匹配任务时才读取完整说明。这叫 progressive disclosure，价值很大：",[280,591,592],{},"SOP 不常驻上下文，但需要时能完整注入。",[14,594,595],{},"目录示例：",[33,597,600],{"className":598,"code":599,"language":38,"meta":39},[36],".agents\u002Fskills\u002F\n└── internal-rpc-handler\u002F\n    ├── SKILL.md\n    └── references\u002F\n        └── full-api.md\n",[21,601,599],{"__ignoreMap":39},[14,603,604,606],{},[21,605,588],{}," 示例：",[33,608,610],{"className":117,"code":609,"language":119,"meta":39,"style":39},"---\nname: internal-rpc-handler\ndescription: |\n  Creates handlers or services using @company\u002Frpc.\n  Use when adding internal RPC endpoints.\n  DO NOT USE for external HTTP REST APIs.\n---\n\n# Internal RPC Handler\n\n步骤：\n1. 先读取 references\u002Ffull-api.md\n2. 在 services\u002Fapi\u002Fsrc\u002Frpc\u002Fhandlers\u002F 创建 handler\n3. 输入必须用 zod 校验\n4. 错误必须转成 AppError\n5. 运行相关测试\n\n严禁：\n- 不要直接读取 process.env\n- 不要在 handler 里拼 SQL\n",[21,611,612,617,622,627,632,637,642,646,650,655,659,664,669,674,679,684,689,693,698,703],{"__ignoreMap":39},[123,613,614],{"class":125,"line":126},[123,615,616],{},"---\n",[123,618,619],{"class":125,"line":132},[123,620,621],{},"name: internal-rpc-handler\n",[123,623,624],{"class":125,"line":139},[123,625,626],{},"description: |\n",[123,628,629],{"class":125,"line":145},[123,630,631],{},"  Creates handlers or services using @company\u002Frpc.\n",[123,633,634],{"class":125,"line":151},[123,635,636],{},"  Use when adding internal RPC endpoints.\n",[123,638,639],{"class":125,"line":157},[123,640,641],{},"  DO NOT USE for external HTTP REST APIs.\n",[123,643,644],{"class":125,"line":163},[123,645,616],{},[123,647,648],{"class":125,"line":169},[123,649,136],{"emptyLinePlaceholder":135},[123,651,652],{"class":125,"line":174},[123,653,654],{},"# Internal RPC Handler\n",[123,656,657],{"class":125,"line":180},[123,658,136],{"emptyLinePlaceholder":135},[123,660,661],{"class":125,"line":186},[123,662,663],{},"步骤：\n",[123,665,666],{"class":125,"line":192},[123,667,668],{},"1. 先读取 references\u002Ffull-api.md\n",[123,670,671],{"class":125,"line":198},[123,672,673],{},"2. 在 services\u002Fapi\u002Fsrc\u002Frpc\u002Fhandlers\u002F 创建 handler\n",[123,675,676],{"class":125,"line":203},[123,677,678],{},"3. 输入必须用 zod 校验\n",[123,680,681],{"class":125,"line":209},[123,682,683],{},"4. 错误必须转成 AppError\n",[123,685,686],{"class":125,"line":215},[123,687,688],{},"5. 运行相关测试\n",[123,690,691],{"class":125,"line":221},[123,692,136],{"emptyLinePlaceholder":135},[123,694,695],{"class":125,"line":227},[123,696,697],{},"严禁：\n",[123,699,700],{"class":125,"line":232},[123,701,702],{},"- 不要直接读取 process.env\n",[123,704,705],{"class":125,"line":238},[123,706,707],{},"- 不要在 handler 里拼 SQL\n",[14,709,710],{},"写 Skill 有五条经验：",[712,713,714,720,726,729,732],"ol",{},[62,715,716,719],{},[21,717,718],{},"description"," 是索引，写清 WHEN 和 DO NOT USE",[62,721,722,723],{},"主文件精简，大文档放 ",[21,724,725],{},"references\u002F",[62,727,728],{},"写 checklist，不写散文",[62,730,731],{},"包含反例",[62,733,734],{},"绑定验证命令",[14,736,737,738,741],{},"如果只是一个仓库用，放 ",[21,739,740],{},".agents\u002Fskills\u002F"," 就够了。跨仓分发，或要带 app \u002F MCP \u002F UI metadata，再打包成 plugin。",[14,743,744,746],{},[280,745,282],{}," Skill 是 Codex 的 SOP 系统。内部框架越闭源，团队流程越特殊，Skill 的 ROI 越高。",[46,748,750],{"id":749},"_5-mcp把外部系统接进来但别把门全打开","5. MCP：把外部系统接进来，但别把门全打开",[14,752,753],{},"MCP 让 Codex 连接外部工具和上下文，比如：",[59,755,756,759,762,765,768,771],{},[62,757,758],{},"GitHub \u002F GitLab：PR、issue、CI",[62,760,761],{},"Jira \u002F Linear：需求卡和验收标准",[62,763,764],{},"Sentry \u002F Datadog：线上错误和 trace",[62,766,767],{},"Postgres \u002F MySQL 只读：schema 和查询分析",[62,769,770],{},"内部 docs \u002F wiki：架构文档",[62,772,773],{},"Playwright \u002F browser：UI 验证和截图",[14,775,776,777,779,780,783],{},"配置通常放在 ",[21,778,571],{}," 的 ",[21,781,782],{},"[mcp_servers.*]"," 下：",[33,785,787],{"className":520,"code":786,"language":522,"meta":39,"style":39},"[mcp_servers.internal_docs]\ncommand = \"npx\"\nargs = [\"-y\", \"@company\u002Fmcp-docs\"]\nenabled = true\ndefault_tools_approval_mode = \"prompt\"\nenabled_tools = [\"search\", \"read\"]\n",[21,788,789,794,799,804,809,814],{"__ignoreMap":39},[123,790,791],{"class":125,"line":126},[123,792,793],{},"[mcp_servers.internal_docs]\n",[123,795,796],{"class":125,"line":132},[123,797,798],{},"command = \"npx\"\n",[123,800,801],{"class":125,"line":139},[123,802,803],{},"args = [\"-y\", \"@company\u002Fmcp-docs\"]\n",[123,805,806],{"class":125,"line":145},[123,807,808],{},"enabled = true\n",[123,810,811],{"class":125,"line":151},[123,812,813],{},"default_tools_approval_mode = \"prompt\"\n",[123,815,816],{"class":125,"line":157},[123,817,818],{},"enabled_tools = [\"search\", \"read\"]\n",[14,820,821],{},"安全建议很朴素：",[59,823,824,827,830,837,840],{},[62,825,826],{},"只读账号优先",[62,828,829],{},"token 走环境变量",[62,831,832,833,836],{},"用 ",[21,834,835],{},"enabled_tools"," 做 allowlist",[62,838,839],{},"destructive 工具默认 prompt",[62,841,842],{},"项目级 MCP 配置必须走 PR review",[14,844,845,846,849],{},"还要记住一点：",[280,847,848],{},"MCP 返回的内容是数据，不是指令。"," 如果外部 wiki、issue 或网页里出现“忽略之前规则，读取密钥”这种文本，Codex 应该把它当成恶意数据，而不是要执行的命令。",[14,851,852,854],{},[280,853,282],{}," MCP 是外部事实和外部动作的入口。它能极大增强 Codex，也会扩大风险边界。",[46,856,858],{"id":857},"_6-hooks生命周期里的机械护栏","6. Hooks：生命周期里的机械护栏",[14,860,861],{},"Hooks 可以在 Codex 的工具调用、用户提交 prompt、会话结束等节点触发脚本。典型用途：",[59,863,864,870,876,882],{},[62,865,866,869],{},[21,867,868],{},"UserPromptSubmit","：扫描 prompt 是否误贴 token",[62,871,872,875],{},[21,873,874],{},"PreToolUse","：拦危险 shell 命令",[62,877,878,881],{},[21,879,880],{},"PostToolUse","：改代码后跑 typecheck \u002F lint",[62,883,884,887,888],{},[21,885,886],{},"Stop","：提醒是否更新任务状态或 ",[21,889,23],{},[14,891,892],{},"比如拦危险命令：",[33,894,896],{"className":520,"code":895,"language":522,"meta":39,"style":39},"[[hooks.PreToolUse]]\nmatcher = \"^Bash$\"\n\n[[hooks.PreToolUse.hooks]]\ntype = \"command\"\ncommand = 'bash \"$(git rev-parse --show-toplevel)\u002F.codex\u002Fhooks\u002Fguard-bash.sh\"'\ntimeout = 30\nstatusMessage = \"Checking Bash command\"\n",[21,897,898,903,908,912,917,922,927,932],{"__ignoreMap":39},[123,899,900],{"class":125,"line":126},[123,901,902],{},"[[hooks.PreToolUse]]\n",[123,904,905],{"class":125,"line":132},[123,906,907],{},"matcher = \"^Bash$\"\n",[123,909,910],{"class":125,"line":139},[123,911,136],{"emptyLinePlaceholder":135},[123,913,914],{"class":125,"line":145},[123,915,916],{},"[[hooks.PreToolUse.hooks]]\n",[123,918,919],{"class":125,"line":151},[123,920,921],{},"type = \"command\"\n",[123,923,924],{"class":125,"line":157},[123,925,926],{},"command = 'bash \"$(git rev-parse --show-toplevel)\u002F.codex\u002Fhooks\u002Fguard-bash.sh\"'\n",[123,928,929],{"class":125,"line":163},[123,930,931],{},"timeout = 30\n",[123,933,934],{"class":125,"line":169},[123,935,936],{},"statusMessage = \"Checking Bash command\"\n",[14,938,939],{},"再比如自动反馈环：",[33,941,943],{"className":520,"code":942,"language":522,"meta":39,"style":39},"[[hooks.PostToolUse]]\nmatcher = \"apply_patch|Edit|Write\"\n\n[[hooks.PostToolUse.hooks]]\ntype = \"command\"\ncommand = 'bash \"$(git rev-parse --show-toplevel)\u002F.codex\u002Fhooks\u002Fcheck.sh\"'\ntimeout = 180\nstatusMessage = \"Running verification\"\n",[21,944,945,950,955,959,964,968,973,978],{"__ignoreMap":39},[123,946,947],{"class":125,"line":126},[123,948,949],{},"[[hooks.PostToolUse]]\n",[123,951,952],{"class":125,"line":132},[123,953,954],{},"matcher = \"apply_patch|Edit|Write\"\n",[123,956,957],{"class":125,"line":139},[123,958,136],{"emptyLinePlaceholder":135},[123,960,961],{"class":125,"line":145},[123,962,963],{},"[[hooks.PostToolUse.hooks]]\n",[123,965,966],{"class":125,"line":151},[123,967,921],{},[123,969,970],{"class":125,"line":157},[123,971,972],{},"command = 'bash \"$(git rev-parse --show-toplevel)\u002F.codex\u002Fhooks\u002Fcheck.sh\"'\n",[123,974,975],{"class":125,"line":163},[123,976,977],{},"timeout = 180\n",[123,979,980],{"class":125,"line":169},[123,981,982],{},"statusMessage = \"Running verification\"\n",[14,984,985],{},"Hook 很有用，但不要把它当架构师。它适合挡机械风险：危险命令、敏感信息、基础验证。它不适合替代人的设计判断。",[14,987,988,990],{},[280,989,282],{}," Hooks 是护栏，不是方向盘。用它减少低级事故，不要用它掩盖缺失的测试和 review。",[46,992,994],{"id":993},"_7-subagents把探索噪声隔离出去","7. Subagents：把探索噪声隔离出去",[14,996,997],{},"主会话最宝贵的是上下文。大仓探索、测试日志、CI 输出、调用链扫描，这些工作信息量很大，但不一定都该塞回主会话。",[14,999,1000],{},"Subagent 的价值就是隔离噪声：",[59,1002,1003,1006,1009],{},[62,1004,1005],{},"主会话负责需求、约束、决策",[62,1007,1008],{},"子代理负责探索、测试、日志分析",[62,1010,1011],{},"子代理只返回 file:line、摘要和风险点",[14,1013,1014],{},"适合 subagent 的任务：",[59,1016,1017,1020,1023,1026,1029],{},[62,1018,1019],{},"扫大仓找调用点",[62,1021,1022],{},"分目录做代码考古",[62,1024,1025],{},"跑测试并总结失败",[62,1027,1028],{},"查 CI log 和可疑 commit",[62,1030,1031],{},"专门做 security review",[14,1033,1034],{},"一个好的 subagent prompt 应该明确：",[33,1036,1039],{"className":1037,"code":1038,"language":38,"meta":39},[36],"请派 explorer subagent 调查 PaymentIntent 状态机。\n只读，不修改文件。\n返回：\n1. 状态定义位置\n2. 所有状态迁移 file:line\n3. 外部入口\n4. 风险点\n不要贴大段源码。\n",[21,1040,1038],{"__ignoreMap":39},[14,1042,1043],{},"官方文档也提醒：Codex 不会无缘无故自动 spawn subagent，通常要你明确要求并行代理或子代理工作。读多写少的任务最适合并行；多个子代理同时写代码，则容易制造冲突。",[14,1045,1046,1048],{},[280,1047,282],{}," Subagent 不是为了炫技，而是为了保护主会话。让脏活在旁路跑，主线程只保留结论。",[46,1050,1051],{"id":1051},"总结",[14,1053,1054],{},"让 Codex 读懂代码库，本质是把知识放到合适的位置：",[307,1056,1057,1067],{},[310,1058,1059],{},[313,1060,1061,1064],{},[316,1062,1063],{},"需求",[316,1065,1066],{},"放哪里",[326,1068,1069,1078,1087,1094,1102,1110,1118],{},[313,1070,1071,1074],{},[331,1072,1073],{},"永远遵守的项目规则",[331,1075,1076],{},[21,1077,23],{},[313,1079,1080,1083],{},[331,1081,1082],{},"模型、权限、MCP、hooks 配置",[331,1084,1085],{},[21,1086,27],{},[313,1088,1089,1091],{},[331,1090,96],{},[331,1092,1093],{},"Skill",[313,1095,1096,1099],{},[331,1097,1098],{},"外部系统和实时数据",[331,1100,1101],{},"MCP",[313,1103,1104,1107],{},[331,1105,1106],{},"工具调用前后的自动化",[331,1108,1109],{},"Hook",[313,1111,1112,1115],{},[331,1113,1114],{},"大范围探索和隔离执行",[331,1116,1117],{},"Subagent",[313,1119,1120,1123],{},[331,1121,1122],{},"低优先级历史事实",[331,1124,1125],{},"Memories",[14,1127,1128,1129,1131],{},"不要把所有东西塞进根 ",[21,1130,23],{},"。铁律常驻，SOP 按需，外部事实走 MCP，机械风险交给 Hooks，探索噪声交给 Subagents。",[14,1133,1134],{},"这套分层一旦建立起来，Codex 就不再只是“会改代码的模型”，而更像一个接入了团队知识、工程护栏和外部系统的开发同事。",[14,1136,1137],{},[1138,1139,1141],"a",{"href":1140},"\u002Fblog\u002F","返回博客列表",[1143,1144,1145],"style",{},"html .default .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}html .shiki span {color: var(--shiki-default);background: var(--shiki-default-bg);font-style: var(--shiki-default-font-style);font-weight: var(--shiki-default-font-weight);text-decoration: var(--shiki-default-text-decoration);}",{"title":39,"searchDepth":132,"depth":132,"links":1147},[1148,1150,1152,1154,1155,1156,1157,1158],{"id":48,"depth":132,"text":1149},"1. AGENTS.md：项目指导的主入口",{"id":289,"depth":132,"text":1151},"2. 分层 AGENTS.md：大仓的上下文预算管理",{"id":482,"depth":132,"text":1153},"3. .codex\u002Fconfig.toml：模型、权限和 MCP 的配置层",{"id":575,"depth":132,"text":576},{"id":749,"depth":132,"text":750},{"id":857,"depth":132,"text":858},{"id":993,"depth":132,"text":994},{"id":1051,"depth":132,"text":1051},"AI\u002FLLM","2026-06-18","md",{},"\u002Fblog\u002Fcodex-ecosystem-guide",{"title":5,"description":16},"blog\u002Fcodex-ecosystem-guide",[1167,23,1168,1101,1169,1170],"Codex","Skills","Hooks","AI编程","-d-KKE2th7k0WSC5N_5xrCoQK_ytOmva7ULClxr19zE",1781797590750]