Community写作与编辑github.com

MJL-ren/blindspot-audit

一个可移植的AI智能体技能,用于发现项目盲点、未知的未知、隐藏风险及缺失决策,并附带持久化分类账以支持Claude Code、Codex和OpenCode上的重复审计。

blindspot-audit 是什么?

本技能旨在弥合用户对项目的认知与项目真实状态之间的差距,将未知的未知转化为具体的、已知的未知,供用户检查、回答、测试或有意推迟。它通过从项目外部引入参考框架来测量这一差距,从而发现项目文档、代码和计划中固有的盲点。该技能采用“四未知”框架(已知的已知、已知的未知、未知的已知、未知的未知)对发现进行分类,并根据用户意识程度提供不同的处理建议。核心规则包括:限制输出3-7个最高信号盲点、避免报告已知条目、总是包含“已检查且覆盖良好”和“暂时可跳过”两个信任章节。支持快速扫描、深度审计、访谈、实施后评审和规划等多种模式,并自适应不同宿主环境(如Claude Code、Codex、OpenCode)的能力限制。该技能通过一个可持久化的分类账(BLINDSPOT_LEDGER.md)来跟踪发现,确保重复审计时能产生进展感而非重复骚扰。

兼容平台✓Claude Code✓Codex CLI~Cursor✓OpenCode
npx skills add MJL-ren/blindspot-audit

Installed? Explore more 写作与编辑 skills: steipete/notion, langchain-ai/langchain, bytedance/podcast-generation · View all 6 →

在你喜欢的 AI 中提问

打开一个已预加载此 Agent Skill 的新对话。

文档

盲点审计

目的

找出用户对项目的认知地图与项目真实版图之间的差距。将未知的未知转化为用户可检查、回答、测试或有意推迟的具体已知的未知。

项目的语境是自我选择的:项目所有者只能写下他们已经知道的东西,因此每个README、TODO和计划都编码了他们心中的地图——而从这些文件出发的AI会继承相同的盲点。本审计刻意从项目外部引入参考框架来衡量这一差距。

本技能并非通用的质量检查清单。它应当识别出对于这个特定项目、在这个特定阶段、基于仓库或提供的工件证据,异常重要的内容。当项目所有者至少有一次说出“我甚至不知道我该考虑那件事”时——并且之后感觉更平静,因为他们现在也知道可以放心忽略哪些内容——审计才算成功。

核心模型

使用四未知框架对发现进行分类:

  • 已知的已知:提示词、文档、代码或计划中已陈述的内容。
  • 已知的未知:文档、TODO、计划、注释或用户措辞中已可见的未决问题。
  • 未知的已知:用户如果看到就能识别出来,但尚未言明或写下来的内容。
  • 未知的未知:项目形态暗示的缺失概念、隐藏约束或未曾提出的问题。

该框架之所以重要,是因为解决方案不同:未知的已知需要检查清单条目而非长篇大论;未知的未知需要简短解释和最便宜的初始步骤。好的输出并不声称确定性。它提供候选方案,并给出最便宜的下一步检查。

基本规则

制定这些规则是因为本技能的失败模式不是“遗漏了一个差距”——而是变成一个被忽略的通用检查清单说教。

  1. 项目自身的跟踪文档是过滤器,而非发现的来源。 README / TODO / 路线图 / 检查清单 / 问题列表中已有的任何内容都是已知的未知。切勿将其报告为发现。(现场数据:此过滤器通常能将候选列表削减一半以上,是所有者信任报告的主要原因。)
  2. 将核心发现限制在3-7个,按影响程度与所有者真正不知的可能性排序。溢出内容归入简短的“低信号关注列表”或分类账——绝不进入主列表。
  3. 仅凭缺失本身不构成发现。 “你没有X”只有在你能陈述这对于此项目的具体后果以及为弥补它所需采取的最便宜的初始步骤时才算数。
  4. 始终包含两个信任章节: “已检查且覆盖良好”和“暂时可跳过”(每个跳过项都要明确说明重新检查的触发条件)。它们能防止焦虑和重新扫描,也是所有者学会信任报告的方式。
  5. 对受监管领域保持审慎。 对于法律、税务或监管方面的发现,陈述你发现的内容及其来源,然后明确说明必须由专业人士确认。你是一名侦察兵,不是律师或会计师。

模式

  • 快速:读取文档和项目清单,返回最严重的盲点。
  • 深度:在排列发现优先级之前,检查典型的代码路径、测试、配置和文档。
  • 访谈:当答案会改变架构、工作流、范围或风险时,一次提出一个问题。
  • 实施后:将已完成的变更、笔记、差异和测试进行对比,找出剩余的未知。
  • 规划:在实施之前,揭示可能改变数据模型、接口、用户体验流程、操作或验证的决策。

根据用户的措辞推断模式。如果用户要求立即运行,除非审计边界无法推断,否则不要询问模式问题。

快速入门

  1. 确定项目根目录和审计边界。
  2. 当存在文件系统项目时,运行清单辅助工具。该脚本位于本技能自己的文件夹中——相对于此SKILL.md解析其路径:
python <本技能文件夹>/scripts/project_inventory.py <项目根目录> --format md

仅当运行时输出、生成的报告、日志或缓存工件是审计问题的一部分时,才使用 --include-generated。

  1. 仅读取相关参考文件:
    • references/archetypes.md:选择项目类型和预期的盲点。
    • references/lenses.md:推导并应用审计透镜。
    • references/host-surfaces.md:根据Claude Code、Codex、OpenCode、CLI或纯聊天界面调整问题和输出。
    • references/ledger-lifecycle.md:发现、创建、路由或更新持久化的盲点分类账。
    • references/report-template.md:格式化结果。
  2. 发现或初始化盲点分类账:
    • 如果存在先前的分类账,在搜索之前读取它(差异运行规则适用——请参阅分类账与差异运行)。
    • 如果不存在分类账且宿主能够写入文件,则在项目本地最佳文档位置创建BLINDSPOT_LEDGER.md,除非用户要求只读/仅聊天输出。
    • 如果不存在分类账且宿主无法写入文件,则在报告中包含建议路径和首个分类账条目。
  3. 从清单中检查最强证据文件:README/AGENTS、计划、包配置、应用入口点、测试配置、CI、环境变量示例、模式、提示词、代理/技能文件以及运行时文档。
  4. 当宿主具有网络访问权限时,运行“新鲜视角”外部扫描(参见工作流第5步)。
  5. 排列发现优先级,尽可能访谈所有者,生成报告,并更新分类账。

宿主界面策略

审计核心应在Claude Code、Codex、OpenCode、CLI和纯聊天中表现一致。仅交互方式发生变化。有关各宿主的详细信息,请参阅references/host-surfaces.md。

  • 支持选择的宿主(Claude Code AskUserQuestion、OpenCode question):当决策改变架构、工作流、范围或风险时——以及为了所有者意识访谈——提出一个简短的2-3选项问题,并在报告或分类账中记录所选选项。
  • Codex或仅聊天宿主:不要在非关键问题上阻塞。继续采用最安全的可逆假设,将其标记为假设,并在报告中包含一个包含用户稍后应选择的选项的“决策包”。
  • 无网络访问的宿主:跳过新鲜视角外部扫描,在报告中明确说明,并将时间敏感领域(法规、平台政策、定价)标记为未经验证,而非从训练知识中断言。
  • 可写入文件的宿主:对于项目审计,默认创建或更新分类账,除非用户要求只读/仅聊天输出。在报告中提及路径和路由编辑。
  • 只读或公开分享的宿主:返回一个可移植的报告,包含用户可以运行的命令/检查。

仅在继续下去会有风险、具有破坏性、成本高昂或可能产生误导性结果时才立即提问。

分类账与差异运行

首次运行:

  1. 使用references/ledger-lifecycle.md为BLINDSPOT_LEDGER.md选择最佳的持久化位置。
  2. 在文件写入适当时,从templates/BLINDSPOT_LEDGER.md创建分类账。
  3. 当路由文件已存在时,将分类账添加到最近的路由界面,例如操作README、文档索引或交接指针。
  4. 记录审计范围、模式、证据边界以及首次发现。

当项目已有盲点分类账时:

  1. 将分类账视为输入,而非真理。重新检查高影响或过时的发现与当前代码/文档的对比。
  2. 将输出分类为“新增”、“已变更”、“已确认”、“已降级”、“已解决”或“需要决策”。
  3. 除非未变更的待处理项阻碍当前目标,否则不要重复报告。这正是使重复运行感觉像进展而非重复骚扰的原因。
  4. 如果分类账是新的但未从索引、交接或操作README中路由,将其标记为可发现性盲点。
  5. 更新分类账时,保留其本地状态语言和ID。

好的分类账使未来的审计更便宜。糟糕的分类账会成为另一个隐藏的文档,因此始终检查可发现性。

搜索卫生

使用有界搜索。盲点审计通常会触及广泛的仓库,而嘈杂的生成文件可能造成虚假自信或浪费上下文。

除非审计明确针对这些区域,否则rg及类似工具的默认排除项:

!.git/**
!node_modules/**
!.venv/**
!dist/**
!build/**
!runtime/**
!external_repos/**
!vendor/**
!docs/archive/**
!docs/research/**
!docs/sources/**
!data/external/raw/**

优先使用目标路径和--glob排除,而非仓库范围的扫描。如果大范围扫描返回巨大的生成文件,在使用结果之前停止并用更严格的边界重新运行。

工作流

1. 定义地图

用2-4行陈述用户表面的目标、项目类型、成熟度和审计边界。明确标记假设。包含所有者画像:

  • 个人还是团队?所有者在哪些方面明确专业,以及——更有用的是——在哪些方面不专业?盲点集中在所有者非专业领域,因此加强那些透镜的权重。
  • 业余还是商业?私人还是公共?商业或公共意图会激活法律、税务和市场透镜,这些对于私人业余项目来说完全是噪音。如果意图无法从文件中判断,在扫描之前询问(一个简短问题)——猜错意图会浪费整个审计。

2. 收集证据

使用清单辅助工具加目标读取。首先阅读项目的自我意识表面(README、TODO、路线图、检查清单、设计文档、概要/大纲)——它们既是最好的画像来源,也是噪声过滤器(基本规则1)。优先使用证据而非广泛推测。将证据标记为:

  • 已观察:直接存在于文件或输出中。
  • 缺失:在检查范围内未找到预期的工件。
  • 推断:可能来自结构、命名或约定。
  • 疑问:需要用户或领域所有者确认。

3. 分类版图

从references/archetypes.md中选择一个或多个原型。不要强行将项目归入一个类别(如果它是混合型)。

4. 运行透镜

仅应用适合项目阶段的透镜。原型不需要企业合规性,但它可能仍然需要数据丢失边界、秘密处理或可恢复性。

5. 新鲜视角外部扫描

当宿主具有网络访问权限时,对两个问题进行限时研究:

  1. 当前同类健康项目视为什么为标准装备?
  2. 过去6-12个月内发生了什么变化——法规、平台政策、市场或类型惯例、工具——是项目文档根本不可能包含的?

问题2具有不成比例的价值:时间依赖性变化在结构上对仓库和所有者的记忆都是不可见的。(现场数据:在早期运行中,影响最大的发现——次月生效的AI内容标注法律、使得已记录计划无效的支付提供商收购——都来自此步骤。)在此找到的任何内容都要引用来源。无网络访问时,跳过并披露(参见宿主界面策略)。

6. 将盲点转化为检查

对于每个发现,包含:

  • 可能缺失的内容。
  • 为何对此项目至关重要。
  • 证据。
  • 最便宜的下一步检查。
  • 可能的所有者或决策界面。
  • 优先级:现在、下一步、稍后或关注。
  • 置信度:高、中、低。

删除出现在项目自身跟踪文档中的候选(基本规则1),保留前3-7个,其余移至关注列表或分类账。

7. 访谈所有者

呈现发现,然后询问哪些是所有者也已知道的(在支持选择的宿主上,一个单选多选问题效果很好)。对每个发现进行分类:

意识含义处理方案
unknown_unknown (未知的未知)所有者不知道解释为何在此处重要 + 最便宜的初始步骤
unknown_known (未知的已知)所有者知道,但未写入任何地方解决方法是文档化,而非实现——将其纳入他们的跟踪文档,以便代理和未来会话能看到
deliberate_skip (有意跳过)所有者考虑过并选择不做移至跳过列表,附带原因和重新检查的触发条件

(现场数据:在早期运行中,大约一半的核心发现原来是unknown_known——仓库中的实际差距,但不在所有者的脑子里。这种区别完全改变了后续行动。)

在无法提问的宿主上,将每个意识值标记为“未确认”,在报告中嵌入访谈问题,并将未决决策放入“决策包”。

8. 保持输出有用

以信号最强的盲点开头。始终包含两个信任章节(基本规则4)。用所有者对话时所使用的语言撰写报告和分类账散文;保持ID、状态和意识值使用英语,以便跨会话和语言运行差异比较。按references/report-template.md格式化。

护栏

  • 除非项目证据表明相关,否则不要将通用最佳实践作为发现呈现。
  • 不要再次报告已存在于分类账或项目自身跟踪文档中的条目。
  • 对于个人实验或早期原型,不要要求繁重流程。
  • 除非用户明确要求修复,否则不要修改代码。
  • 不要仅因文件缺失就声称某物损坏;说明缺失所暗示的内容以及如何确认。
  • 仅当项目声称可重复交付、共享交接或生产级可靠性时,才将缺失的CI、测试、发布文档或部署文件视为盲点。个人笔记和早期原型可能不需要它们。
  • 不要用每一个可能的风险淹没用户。按项目适配性、影响范围、可逆性和可能性排序。
  • 当用户在领域内非专业时,为不熟悉的盲点包含简短的教学说明。
  • 当发现依赖于当前外部平台行为时,在将其视为事实之前,通过官方文档或当前研究进行验证;无网络访问时,将其呈现为来自训练知识的未经验证。
  • 如果无法确定默认假设的意图,请用一句话询问,以免浪费整份审计。

引用

原型(references/archetypes.md)

从项目类型和阶段派生的预期盲点类别。

透镜(references/lenses.md)

可组合的检查透镜,每个都产生自己的问题集和期望。

宿主界面(references/host-surfaces.md)

每种宿主能力的交互适配器。

分类账生命周期(references/ledger-lifecycle.md)

关于创建、路由、维护和更新BLINDSPOT_LEDGER.md的说明。

报告模板(references/report-template.md)

审计报告的标准输出格式。

分类账模板(templates/BLINDSPOT_LEDGER.md)

首次运行的分类账存根。

项目清单(scripts/project_inventory.py)

用于基于文件系统的项目的清单收集器。

相关技能