Clairvoyance

Clairvoyance

AI Agent 可以编写可用的代码，但除非有人提出要求，否则它们不会停下来思考如何有效地设计。Clairvoyance 是一组灵感源自 John Ousterhout 的 《软件设计哲学》 的技能。每项技能都能让你的 Agent 获得软件设计方面的超感知视角，并提供具体的测试，帮助它在实现和评审过程中预见障碍。

工作原理

技能会自动激活，并促使你的 Agent 提出这样的问题：

• 这个接口隐藏了真正的复杂性，还是只是在传递内容？
• 不阅读另一个文件中的其他方法，能理解这个方法吗？
• 错误处理是否把模块本身能够处理的工作推给了调用方？

你也可以直接调用这些技能。使用 /clairvoyance:red-flags 扫描设计异味，使用 /clairvoyance:deep-modules 检查接口深度，使用 /clairvoyance:design-it-twice 在做出决定前比较不同方案。（在 skills.sh 等不安装插件命名空间的平台上，去掉 clairvoyance: 前缀。）

安装

为你的 Agent 安装 Clairvoyance：Claude Code、skills.sh、Codex、Cursor、OpenCode、Antigravity、Factory Droid、GitHub Copilot CLI、Kimi Code、Pi。

**注意：**各平台的安装方式有所不同。如果你使用多个平台，请分别为每个平台安装 Clairvoyance。

Claude Code

/plugin marketplace add codybrom/clairvoyance
/plugin install clairvoyance@clairvoyance-plugins

skills.sh

npx skills add codybrom/clairvoyance --skill '*'

Codex

需要 Codex CLI ≥ 0.142.0（codex --version）。Codex App 和 CLI 共用同一份配置，因此安装后 Clairvoyance 也会显示在 App 的 Plugins 面板中。

codex plugin marketplace add codybrom/clairvoyance
codex plugin add clairvoyance@clairvoyance

较旧版本的 Codex 只能通过手动创建符号链接来获取这 16 项技能——此备用方案和完整故障排查说明请参见 .codex/INSTALL.md。

Cursor

Cursor 目前还不支持通过一行命令从 GitHub URL 安装未列出的插件，因此请将仓库克隆（或创建符号链接）到 Cursor 的本地插件文件夹，然后重启：

git clone https://github.com/codybrom/clairvoyance.git ~/.cursor/plugins/local/clairvoyance

然后检查侧边栏中的 Customize 面板，确认 Clairvoyance 及其 16 项技能已列出。

OpenCode

将 Clairvoyance 添加到 opencode.json（全局或项目级）的 plugin 数组中：

{
  "plugin": ["clairvoyance@git+https://github.com/codybrom/clairvoyance.git"]
}

重启 OpenCode 即可——无需符号链接或手动指定技能路径。有关版本固定、故障排查，以及从旧的基于符号链接的安装方式迁移的说明，请参见 .opencode/INSTALL.md。

Antigravity

agy plugin install https://github.com/codybrom/clairvoyance

Factory Droid

Droid 会自动转换 Claude Code 插件格式——无需创建任何 Clairvoyance 专用文件。

droid plugin marketplace add https://github.com/codybrom/clairvoyance
droid plugin install clairvoyance@clairvoyance-plugins

GitHub Copilot CLI

copilot plugin marketplace add codybrom/clairvoyance
copilot plugin install clairvoyance@clairvoyance-plugins

Kimi Code

在 Kimi Code 的插件管理器（/plugins）中选择 Custom，或直接运行：

/plugins install https://github.com/codybrom/clairvoyance

由于这不是官方精选来源，Kimi Code 会显示第三方信任提示；确认后即可继续。

Pi

pi install git:github.com/codybrom/clairvoyance

Pi 会自动发现 skills/ 目录，无需额外配置。

llms.txt

面向大模型 Agent 的机器可读技能索引：

• clairvoyance.fyi/llms.txt — 含描述的目录
• clairvoyance.fyi/llms-full.txt — 所有技能的完整内容

MCP 服务

如果你的 Agent 无法安装插件或技能，但可以连接 MCP 服务，请使用 Clairvoyance 的只读 MCP 服务：https://clairvoyance.fyi/mcp（Streamable HTTP，无需登录）。每项技能都是一个工具，其名称和描述与插件中的相同；支持 MCP 提示词的客户端还会将每项技能作为斜杠命令提供。请求只会指定技能，因此服务永远不会收到你的代码、文件路径或提示词。

• VS Code： code --add-mcp '{"name":"clairvoyance","type":"http","url":"https://clairvoyance.fyi/mcp"}'
• Cursor： 在 ~/.cursor/mcp.json 的 "mcpServers" 下添加 "clairvoyance": { "url": "https://clairvoyance.fyi/mcp" }
• Claude Code： claude mcp add --transport http clairvoyance https://clairvoyance.fyi/mcp
• Codex： codex mcp add clairvoyance --url https://clairvoyance.fyi/mcp
• 其他客户端： 将 https://clairvoyance.fyi/mcp 添加为远程（HTTP）MCP 服务。

它已列入官方 MCP Registry，名称为 fyi.clairvoyance/mcp。VS Code 和 Cursor 的一键安装按钮位于 clairvoyance.fyi/install。如果你的 Agent 支持插件或技能，请改为安装这些内容：插件还会强制执行每项技能的工具限制，并自行运行 design-it-twice 子 Agent。

内容一览

结构与模块

技能	涵盖内容
deep-modules	模块深度、浅模块、类泛滥、直通方法、接口与实现
module-boundaries	合并与拆分、紧密关联的方法、方法拆分、依赖最小化
information-hiding	信息泄漏、时间分解、部分隐藏、虚假封装
pull-complexity-down	调用方负担、配置参数、核心不对称性

抽象与通用性

技能	涵盖内容
abstraction-quality	真正与虚假的抽象、层边界、装饰器
general-vs-special	接口通用性、通用与特殊的混杂、消除边缘情况
error-design	让错误不复存在、异常屏蔽、聚合、直接崩溃

清晰度与沟通

技能	涵盖内容
naming-obviousness	隔离测试、作用域长度原则、一致性、避免多余词语
comments-docs	注释类型、先写注释的工作流、跨模块文档

流程与演进

技能	涵盖内容
strategic-mindset	战略与战术、投资原则、战术旋风
design-it-twice	生成备选方案、按标准比较、综合
code-evolution	“按此方式设计”的标准、重复、技术债务
complexity-recognition	变更放大、认知负担、未知的未知

诊断

技能	涵盖内容
red-flags	设计异味扫描，涵盖结构、边界、文档、命名和流程
design-review	结构化评审流程，从复杂度分流到结构、接口和表层检查
diagnose	通过决策树，将模糊症状或抱怨引导至最相关的技能

致谢

这些技能部分改编自斯坦福大学计算机科学教授 John Ousterhout 的课程内容及其著作 A Philosophy of Software Design。本项目与 John Ousterhout、斯坦福大学或 A Philosophy of Software Design 的出版商均无关联，也未获得其认可或赞助。

如果你觉得这些技能有用，真的应该买来读一读这本书。 本仓库中的技能绝不能替代阅读原书。它是对这些理念的权威阐述，也是一本值得每位开发者阅读的好书。可在 Amazon 购买（无联盟链接）。另有德文版（O'Reilly，2021 年）和中文版（人民邮电出版社，2024 年）。

本项目中的技能和代码均由项目贡献者独立创作。为评论、批评和教育目的，有时会引用书中的简短内容，并注明完整出处。所有商标和版权均归其各自所有者所有。

贡献

欢迎提交超出灵感素材范围的贡献，但应当体现关于软件设计的战略性思考这一核心理念。

贡献步骤：

1. Fork 此仓库
2. 创建一个分支
3. 按照 Superpowers 中的 writing-skills 技能来创建和测试技能
4. 在 skills/<skill-name>/SKILL.md 中添加你的技能，并可选添加 references/ 文件
5. 提交更改并发起 PR

更新

• Claude Code： /plugin update clairvoyance
• skills.sh： npx skills update codybrom/clairvoyance
• Codex： codex plugin marketplace upgrade clairvoyance && codex plugin add clairvoyance@clairvoyance
• Cursor： cd ~/.cursor/plugins/local/clairvoyance && git pull，然后重启
• OpenCode： 除非固定了标签，否则重启时不会自动刷新；请参阅 .opencode/INSTALL.md
• Antigravity： 重新运行 agy plugin install https://github.com/codybrom/clairvoyance
• Factory Droid： droid plugin marketplace update clairvoyance-plugins && droid plugin update clairvoyance@clairvoyance-plugins
• GitHub Copilot CLI： copilot plugin update clairvoyance
• Kimi Code： 在 Custom 选项卡中重新运行安装命令
• Pi： pi update --extensions（如果固定了某个 ref，则使用新的 ref 重新运行安装命令）
• MCP 服务： 始终提供最新技能，因此无需更新。
• llms.txt： 始终保持最新，地址为 clairvoyance.fyi/llms-full.txt。

请参阅 CHANGELOG.md 或 GitHub releases，了解各个版本的更改内容。

许可证

MIT License © 2026 Cody Bromley