security

Codex 兼容性说明：

• 在 Codex 中使用 $skill-name 调用仓库技能；此镜像副本会改写旧版 Claude /skill-name 引用。
• 任务跟踪要求：执行任何工作流或技能步骤之前，先为所有步骤创建/更新任务跟踪，并随着进度变化保持同步。
• 用户问题提示表示要在 Codex 中直接询问用户。
• 出现 Claude 专属的模式切换指令时，请忽略。
• 严格执行约定：用户明确调用某项技能时，按原样执行该技能协议。
• 子 Agent 授权：用户调用或 AI 检测到某项技能，且其协议要求使用子 Agent 时，该技能的激活即授权为该任务使用所需的 spawn_agent 子 Agent。
• 除非用户事先明确批准偏离，否则不得跳过、重排或合并协议步骤。
• 对于工作流技能，明确执行列出的每个子技能步骤，并逐步提供证据。
• 如果所需步骤/工具在此环境中无法运行，请停止并在调整方案前询问用户。

Codex 项目参考资料加载（无 Hooks）

Codex 不会接收基于 Claude Hook 的文档注入。 进行编码、规划、调试、测试或审查时，请按照以下路由明确打开项目文档。

始终阅读：

• docs/project-config.json（项目专属路径、命令、模块以及工作流/测试设置）
• docs/project-reference/docs-index-reference.md（指向完整 docs/project-reference/* 目录）
• docs/project-reference/lessons.md（始终适用的防护措施和反模式）

根据具体情况阅读文档：

• 后端/CQRS/API/领域/实体变更：backend-patterns-reference.md、domain-entities-reference.md、project-structure-reference.md
• 前端/UI/样式/设计系统：frontend-patterns-reference.md、scss-styling-guide.md、design-system/README.md
• 规范/测试用例规划或 TC 映射：feature-docs-reference.md
• 集成测试实现/审查：integration-test-reference.md
• E2E 测试实现/审查：e2e-test-reference.md
• 代码审查/审计工作：code-review-rules.md，以及根据变更文件选择的领域文档

不要盲目阅读所有文档。从 docs-index-reference.md 开始，然后只打开与任务相关的文件。

[BLOCKING] 按照规定顺序执行技能步骤。未经用户明确批准，绝不跳过、重排或合并步骤。 [BLOCKING] 每个步骤或子技能调用之前，更新任务跟踪：步骤开始时设为 in_progress，结束时设为 completed。 [BLOCKING] 每个已完成/已跳过的步骤都必须附上简要证据或明确的跳过原因。 [BLOCKING] 如果 Task 工具不可用，请创建并维护等效的逐步计划跟踪，并使用相同的状态转换。

快速摘要

目标： 按照 OWASP Top 10 和项目授权模式执行安全审查。

工作流：

1. 界定范围 — 确定安全敏感的代码区域
2. 审计 — 根据 OWASP 类别和平台安全模式进行审查
3. 报告 — 记录发现的问题及其严重程度和修复方法

关键规则：

• 分析思维：系统化审查，不靠猜测
• 检查后端和前端攻击面
• 使用项目授权属性和实体级访问表达式（参见 docs/project-reference/backend-patterns-reference.md）

$ARGUMENTS

分析思维（不可妥协）

保持怀疑，运用批判性思维和顺序思维。每项结论都需要追溯证据，并给出置信度百分比（判断应高于 80%）。

• 阅读实际实现来验证安全性——绝不可仅凭表面判断代码安全
• 每项漏洞发现都必须附上 file:line 证据
• 如果无法通过代码追踪证实漏洞，请说明“潜在风险，尚未确认”
• 质疑假设：“这真的可以被利用吗？”→ 追踪输入路径以确认
• 质疑完整性：“还有其他攻击向量吗？”→ 检查所有输入边界
• 没有证据就不要说“看起来安全”——说明你验证了什么，以及如何验证

启用 arch-security-review 技能并遵循其工作流。

重要： 提交安全发现后，等待用户明确批准，再实施修复。

子 Agent 类型覆盖

强制要求： 安全审查的第 2 轮必须启用 security-auditor 子 Agent，而非 code-reviewer。 理由： security-auditor 配备专门的 OWASP 协议、身份验证流程分析、注入风险追踪、依赖项 CVE 检查和微服务边界安全上下文，而 code-reviewer 不具备这些能力。

递归质量循环

1. 第 1 轮： 主 Agent（或 arch-security-review 技能）执行分析 → 起草发现报告
2. 第 2 轮： 启用全新的 security-auditor 子 Agent（agent_type: "security-auditor"）——不保留第 1 轮的任何记忆。在提示词中加入：OWASP Top 10 检查清单、身份验证流程、注入风险、依赖项 CVE、微服务边界安全。
3. 发现问题 → 修复 → 第 3 轮启用全新的 security-auditor 子 Agent
4. 最多 3 轮 → 通过直接提问升级给用户
5. 第 1 轮未发现问题时，审查即结束。 发现问题时，先修复，再启用全新的子 Agent 进行第 2 轮——主 Agent 可能会为自己的工作辩解，而新的审查者能发现被忽略的问题。

运行 python .claude/scripts/code_graph query callers_of <function> --json 以追踪进入敏感函数的所有入口点。

图分析智能（如果 graph.db 存在，建议使用）

如果 .code-graph/graph.db 存在，请通过结构化查询增强分析：

• 追踪流向敏感函数的数据流： python .claude/scripts/code_graph query callers_of <function> --json
• 此函数会调用什么？ python .claude/scripts/code_graph query callees_of <function> --json
• 批量分析： python .claude/scripts/code_graph batch-query file1 file2 --json

图查询模式请参见上方的 `` 代码块。

使用图追踪进行数据流分析

如果图数据库可用，请使用 trace 分析安全审查中的数据流路径：

• python .claude/scripts/code_graph trace <entry-point> --direction downstream --json — 从输入追踪数据流向所有使用方（找出不可信数据的流向）
• python .claude/scripts/code_graph trace <sensitive-file> --direction upstream --json — 找出所有能到达敏感代码的入口点
• 追踪可揭示跨服务的 MESSAGE_BUS 流程，其中数据会跨越信任边界

---

工作流建议

强制、重要、必须注意——无一例外： 如果你当前不在工作流中，必须通过直接提问来询问用户。不要判断任务是否复杂，也不要决定任务“足够简单，可以跳过”——是否使用工作流由用户决定，而不是由你决定：

1. 启用 quality-audit 工作流（推荐）——安全 → sre-review → 测试
2. 直接执行 $security——单独运行此技能

---

阶段 1：Why-Review 自我验证关卡（存在发现时必须执行）

目的： 在移交前对自己的发现进行对抗性验证。在源头发现过度标记为 High、误报和严重性夸大的问题，而不是任由它们传播到下游。

触发条件： 产生任何发现（Critical、High、Medium 或 Low）。仅当报告结论为无条件 PASS 且确实没有任何发现时，才可跳过。

流程：

1. 从 plans/reports/{skill}-{date}-{slug}.md 读取自己定稿的报告
2. 调用 $why-review 技能，参数为：validate findings in plans/reports/{skill}-{date}-{slug}.md — verify each finding has file:line proof, steel-man each rejected interpretation, and stress-test severity classifications
3. 从 plans/reports/why-review-{date}.md 读取 why-review 输出
4. 如果 why-review 下调或移除了任何发现： 更新自己定稿的报告，修订严重性、移除误报，并添加 ## Why-Review Validation Notes 部分，说明发生了哪些更改以及原因
5. 如果 why-review 确认了所有发现： 在自己的报告中追加 ## Why-Review Validation 行，注明“所有 N 项发现均已根据实际代码重新验证；严重性没有变化。”

跳过条件（跳过时须记录明确原因）：

• 结论为无条件 PASS 且没有任何发现 → 记录“已跳过 — 没有需要验证的发现”
• why-review 技能本身就是当前活动上下文（避免递归）

设立原因： AI 子 Agent 报告会继承确认偏误——协调器会将严重性判断视为事实。2026-05-09 的审查事件产生了 5 项 High；对抗性验证将其中 3 项下调。将此规范化为标准实践。

---

后续步骤

完成此技能后必须注意——绝无例外，你必须通过直接询问用户来提供这些选项。不要因为任务看起来“简单”或“显而易见”而跳过——由用户决定：

• "$sre-review（推荐）" — 生产就绪性审查
• "$performance" — 接下来分析性能
• "跳过，继续手动处理" — 由用户决定

[IMPORTANT] 开始前必须使用任务跟踪，将所有工作拆分为小任务——包括为每个文件的读取创建任务。这可以防止因文件过长而丢失上下文。对于简单任务，AI 必须询问用户是否跳过。

• docs/project-reference/domain-entities-reference.md — 领域实体目录、关系、跨服务同步（任务涉及业务实体/模型时阅读）（在相关时直接阅读；不要依赖由钩子注入的对话文本）

外部记忆： 对于复杂或耗时较长的工作（研究、分析、扫描、审查），将中间发现和最终结果写入 plans/reports/ 中的报告文件，以防上下文丢失并作为交付物。

证据关卡： 必须注意——每项声明、发现和建议都需要 file:line 证明或可追溯证据，并标注置信度百分比（>80% 才可采取行动，<80% 必须先核实）。

子 Agent 选择 — 完整路由规范：.claude/skills/shared/sub-agent-selection-guide.md 规则： 将专业领域（架构、安全、性能、DB、E2E、集成测试、git）路由给相应的专业 Agent（见上方指南）——绝不要将这些领域交给 code-reviewer。原因：code-reviewer 缺少各领域的检查清单，因此专业问题会被遗漏。 图辅助调查 — 当 .code-graph/graph.db 存在时，必须执行。

硬性门槛： 在结束任何调查前，必须注意至少对关键文件运行一条图命令。

模式： Grep 查找文件 → trace --direction both 揭示完整系统流程 → Grep 验证细节

任务	最低图操作
调查/侦察	对 2-3 个入口文件运行 trace --direction both
修复/调试	对有问题的函数运行 callers_of，并运行 tests_for
功能/增强	对要修改的文件运行 connections
代码审查	对已更改的函数运行 tests_for
影响范围	运行 trace --direction downstream

CLI： python .claude/scripts/code_graph {command} --json。先使用 --node-mode file（噪声减少 10-30 倍），然后使用 --node-mode function 查看详情。

增量结果持久化 — 所有处理超过 3 个文件的子 Agent 或繁重的内联步骤都必须执行。

1. 开始前： 创建报告文件 plans/reports/{skill}-{date}-{slug}.md
2. 每审阅完一个文件/部分后： 立即将发现追加到报告中——绝不要只保留在内存里
3. 返回主 Agent： 仅提供摘要（遵循 SYNC:subagent-return-contract），并附上 Full report: 路径
4. 主 Agent： 仅在解决具体阻塞问题时读取报告文件

原因： 执行过程中上下文被截断会导致所有内存中的发现丢失。每次写入磁盘都能在压缩后保留。部分结果胜过毫无结果。

报告命名： plans/reports/{skill-name}-{YYMMDD}-{HHmm}-{slug}.md

子 Agent 返回约定 — 当此技能启动子 Agent 时，子 Agent 必须仅返回以下结构。主 Agent 只读取此摘要——绝不要求子 Agent 在内联内容中返回完整输出。

## 子 Agent 结果：[skill-name]

状态：✅ 通过 | ⚠️ 部分完成 | ❌ 失败
置信度：[0-100]%

### 发现（仅严重/高优先级——最多 10 条）

- [严重程度] [文件:行号] [发现]

### 已采取的操作

- [已更改的文件] [更改内容]

### 阻塞问题（如有）

- [阻塞问题描述]

完整报告：plans/reports/[skill-name]-[date]-[slug].md

仅在以下情况，主 Agent 才会读取 Full report 文件：(a) 解决具体阻塞问题，或 (b) 制定修复计划。 子 Agent 按增量方式写入完整报告（遵循 SYNC:incremental-persistence）——不将内容仅保留在内存中。

批判性思维 — 运用批判性思维和顺序思维。每项断言都需要可追溯的证据，置信度需高于 80% 才能采取行动。 反幻觉： 绝不要将猜测说成事实——每项断言都要引用来源，坦诚承认不确定性，自检输出是否有误，独立交叉核验，并对自己的判断保持怀疑——没有证据的确定性是所有幻觉的根源。

基于证据的推理 — 禁止臆测。每项断言都必须有证据。

1. 每项断言都要引用 file:line、grep 结果或框架文档
2. 声明置信度：>80% 可直接行动，60-80% 先验证，<60% 不得提出建议
3. 架构变更必须进行跨服务验证
4. “我没有足够的证据”是有效且预期的输出

满足以下条件前不得继续： - [ ] 证据文件路径（file:line）- [ ] 已执行 Grep 搜索 - [ ] 已找到 3 个以上类似模式 - [ ] 已声明置信度

没有证据时禁止使用： “显然”“我认为”“应该是”“很可能”“这是因为” 如果未完成 → 输出："证据不足。已验证：[...]. 未验证：[...]。" 源码／测试偏差检查。 对于编码、修复、调试、调查、测试或审查工作：当源码行为发生变化时，检查受影响的单元／集成／E2E 测试，并根据证据判断是应修改测试以匹配预期行为，还是源码变更引入了需要修复的意外缺陷。不要为迁移代码编写测试；架构／数据迁移是一次性执行路径，不属于核心应用逻辑。

防止 AI 出错 — 每项任务都要避免以下失误模式：

删除前检查下游引用。 删除组件会导致文档和代码逐步过时。删除前先梳理所有引用该组件的文件。 依据实际代码验证 AI 生成的内容。 AI 会捏造 API、类名和方法签名。记录或引用之前，务必用 grep 确认它们确实存在。 编辑后追踪完整依赖链。 更改定义时，容易遗漏由其派生的下游变量和使用方。务必追踪完整依赖链。 验证正确性时追踪所有代码路径。 确认代码存在，不代表它会执行。务必追踪提前退出、错误分支和条件跳过，而不只是顺利执行的路径。 调试时，先问“谁应负责？”，再着手修复。 追查缺陷是在调用方（数据错误）还是被调用方（处理错误）。在责任所在的层修复，绝不要只修补症状出现的位置。 假定现有值是有意设置的——更改前先问“为什么”。 更改任何常量、限制、标志或模式之前：阅读注释、检查 git blame，并查看相关代码。 验证所有受影响的输出，而不只是第一个。 涉及多个技术栈的变更，需要验证每一项输出。一个检查通过，不代表所有检查都通过。 整体优先的调试方式——避免只关注最近引起注意的问题。 调查任何故障时，先列出所有前置条件（配置、环境变量、数据库名称、端点、依赖注入注册、数据前置条件），再逐一根据证据验证，之后才能对代码层面的问题形成假设。 精准修改——应用差异检验。 修复缺陷时，每一行改动都必须能直接追溯到该缺陷。不要顺手重排样式或改进相邻代码。增强任务：实现改进，并明确说明改进内容。 编码前明确歧义——不要默默做出选择。 如果请求有多种解读方式，列出每种解读及其工作量估算，并询问用户。绝不要擅自假定要处理所有记录、采用基于文件的路径或选择更复杂的方案。

重要：必须注意 每项声明都要引用 file:line 作为证据。置信度 >80% 才能采取行动，<60% = 不要提出建议。

重要：必须注意 当 graph.db 存在时，至少对关键文件运行一个图命令。模式：grep → trace → verify。

必须注意 运用批判性思维——每项声明都需要经过追踪的证据，置信度 >80% 才能采取行动。防止幻觉：绝不要把猜测说成事实。

必须注意 运用防止 AI 出错的原则——整体优先调试、在责任所在的层修复、编码前明确歧义、上下文压缩后重新阅读文件。

Prompt-Enhance 收尾锚点

重要：必须注意 遵循此技能声明的步骤顺序；未经用户明确同意，绝不跳过、重排或合并步骤 重要：必须注意 对每个步骤／子技能调用：执行前设为 in_progress，执行后设为 completed 重要：必须注意 每个跳过的步骤都必须说明明确原因；每个已完成的步骤都必须附上简洁证据 重要：必须注意 如果 Task 工具不可用，则维护一个等效的逐步计划跟踪器，并同步更新状态

收尾提醒

强制重要必须注意 开始前，使用任务跟踪将工作拆分为小型待办任务。 强制重要必须注意 通过直接向用户提问来验证决策——绝不自动做决定。 强制重要必须注意 添加一项最终审查待办任务，以验证工作质量。 强制重要必须注意 开始前阅读以下文件：

[TASK-PLANNING] 行动前，分析任务范围，并使用任务跟踪系统地将其拆分为小型待办任务和子任务。

[重要] 开始前分析任务规模，并系统地将其拆分为多个小型待办任务——这一点非常重要。

无 Hook 提示词协议镜像（自动同步）

来源：.claude/hooks/lib/prompt-injections.cjs + .claude/.ck.json

[WORKFLOW-EXECUTION-PROTOCOL] [BLOCKING] 工作流执行协议——强制重要必须关键。无论出于何种原因都不得跳过。

通用可移植性边界： 可复用技能和协议文本应保持项目中立；项目特定约定应从 docs/project-config.json 和 docs/project-reference/ 中查找。应用共享 AI-SDD，参见 shared/sdd-artifact-contract.md。阅读 docs/project-config.json 和 docs/project-reference/docs-index-reference.md，然后打开其中列出的项目参考文档。只要具备此共享上下文和本地文档，任何受支持的 AI 工具均可执行。

1. 检测： 将提示词与工作流目录进行匹配
2. 分析： 找出最匹配的工作流，并评估自定义步骤组合是否更合适
3. 询问（必需格式）： 使用直接面向用户的问题，并采用以下结构；如果用户明确调用了工作流／技能，且本地协议将明确调用视为确认，则无需询问：
   • 问题：“你想启用哪个工作流？”
   • 选项 1：“启用 [最佳匹配工作流]（推荐）”
   • 选项 2：“启用自定义工作流：[步骤 1 → 步骤 2 → …]”（附上一句话说明理由）
4. 启用（确认后）： 标准工作流调用 $workflow-start <workflowId>；自定义步骤则手动依次执行
5. 创建任务： 使用任务跟踪，为所有工作流步骤创建任务
6. 执行： 按顺序执行每个步骤 [CRITICAL-THINKING-MINDSET] 运用批判性思维和顺序思维。每项主张都必须有可追溯的证据，且置信度高于 80% 才能采取行动。 反幻觉原则： 绝不将猜测当作事实——每项主张都要引用来源；坦然承认不确定性；自行检查输出是否有误；独立交叉验证；对自己的判断保持审慎——缺乏证据的确信是所有幻觉的根源。 AI 注意力原则（首因—近因效应）： 对于较长的提示词／协议，应在开头和结尾都放置 3 条最关键的规则，以确保在较长上下文中仍能遵循指令。 目标驱动执行： 首先定义成功标准；循环执行直至验证完成；只有在可观察的检查全部通过后才停止。 测试验证意图： 测试必须保护业务规则／不变量，并在受保护的意图遭到破坏时失败，而不只是复现当前行为。

[LESSON-LEARNED-REMINDER] [BLOCKING] 任务规划与持续改进 — 必须遵守。请勿跳过。

开始前将工作拆分为小任务（任务跟踪）。添加最后一项任务：“分析 AI 错误与经验教训”。

提取经验教训——只分析根本原因，不要只修复症状：

1. 指明失败模式（推理或假设错误），而不是症状——“假设 API 存在，却没有阅读源代码”，而不是“使用了错误的枚举值”。
2. 通用性测试：此失败模式是否适用于 ≥3 种情境或代码库？如果不适用，就再抽象一个层次。
3. 将其写成普遍规则——去掉特定于项目的名称、路径和类。确保规则适用于任何代码库。
4. 合并：多个错误若具有相同的失败模式，则合并为一条经验教训。
5. 复发检查：“如果没有此提醒，这种情况会在未来的会话中再次发生吗？”——不会 → 跳过 $learn。
6. 自动修复检查：“$code-review/$code-simplifier/$security/$lint 能否发现此问题？”——能 → 改进审查技能。
7. 两项检查均通过 → 请用户运行 $learn。 [TASK-PLANNING] [MANDATORY] 执行任何工作流或技能步骤之前，先为所有计划步骤创建或更新任务跟踪，然后在每个步骤开始和完成时保持任务跟踪同步。