skill

PUA-Driven-Spec-Engineering

PUA（发动机）→ 门控档位 → 驱动 OpenSpec（骨架）→ 产出规范文档 → 驱动实现

huangwen-changdu/PUA-Driven-Spec-Engineeringcommunitylistedunreviewed

Set up

Skills are installed by placing their folder where your agent loads skills.

Download ZIP from GitHub Open the repository

The download comes from github.com/huangwen-changdu/PUA-Driven-Spec-Engineering itself, not from our server, so what you get is exactly what its author published.

Install instructions come from the README

Skills do not use an MCP config. Follow the steps in the README below.

README

synced Oct 27, 2026

PUA-Driven Spec Engineering

一套面向所有开发者和团队的通用 AI 协作服务流程 / 多平台技能框架，支持 Claude Code、OpenAI Codex CLI、CodeBuddy 和 GitHub Copilot 四个平台。通过自适应门禁、OpenSpec SDD 渐进确认和 Karpathy 编码准则，让 AI 编码助手更严谨、更可控。

作者：huangwen
联系邮箱：fanwen887@gmail.com

核心价值

一句话：让 AI 编码助手更严谨、更可控，防止"说完成但没验证"、"跳过设计直接写代码"等问题。

三个关键点：

自适应门禁：普通问题轻量快放，高压问题走完整流程
先设计后实现：新功能必须先做方案对比，再写代码
验证闭环：说"完成"前必须有验证命令和真实输出

Token 压缩：双层策略最高节省 ~95% token

caveman：输出压缩（LLM 响应文本 ~75%），支持 lite/full/ultra/wenyan 四强度
rtk：输入压缩（CLI 命令输出 60-90%），自动重写命令过滤噪声

快速上手（5 分钟）

详细指南：docs/QUICKSTART.md | 决策速查：docs/DECISION-TREE.md | 场景模板：docs/SCENARIOS.md

三种场景快速上手

场景	适用	预计步骤	关键提示
简单修改	改一行代码、解释代码、单文件小改	1-2 步	直接说需求，AI 自动判断
新功能	新增功能、架构变更、模糊需求	3-5 步	说"我要做一个..."，AI 引导设计
紧急修复	Bug 修复、紧急问题、用户不满	2-4 步	输入 `/pua`，AI 进入高压模式

决策速查表

你的需求	推荐路径	预计步骤
改一行代码	直接说需求 → G0/G1	1-2 步
解释代码	直接问 → G0	1 步
新增功能	说需求 → AI引导设计 → 实现	3-5 步
修复 Bug	说问题 → AI定位 → 修复	2-4 步
架构变更	说目标 → 完整设计 → 实现	5-8 步
模糊需求	说想法 → AI澄清 → 设计 → 实现	4-6 步

核心机制

入口压缩（v2）

层级	组件	职责
推荐入口	`using-superpowers-pua`	需要 PUA 门禁或方法论路由时统一判断 Fast / Design / Escalate
条件升级层	`pua-escalation`	ESCALATE 或触发信号时收紧流程

需要门禁时在入口统一完成，各技能继承档位，不再各自重走。

门禁档位（入口统一评估）

G0/G1 PASS：普通问题轻量快放，一行微标
G2 PASS：多步骤任务简版门禁
ESCALATE：调用 pua-escalation
BLOCKED：补齐证据再继续

各技能继承档位，执行阶段用轻标模式（详见入口统一规则）。

三条红线

闭环意识：没有验证输出，不叫完成
事实驱动：没有查证的归因，不叫判断
穷尽一切：方法论没走完，不叫解决不了

四层知识体系对比

层级	目录	是什么	回答什么问题
1. 关系图谱	`graphify-out/`	机器扫描代码生成的节点+边图谱	"A 调用了谁？""改这个类影响哪些地方？"
2. 知识包	`docs/project-knowledge/`	人工整理的业务域文档（20个专题）	"这个项目是什么？""改 X 从哪里入手？""哪里是红线？"
3. 学习库	`.copilot/`	踩坑记录 + 项目经验沉淀	"上次在这里踩过什么坑？""下次遇到同类问题怎么处理？"
4. 规则入口	`.copilot/copilot-instructions.md`	GitHub Copilot 的规则入口	Copilot 的行为约束

常用技能速查

快速找到你需要的功能。⭐ 越多 = 推荐度越高、使用频率越高。

技能	推荐等级	一句话用途	触发方式
`brainstorming-pua`	⭐⭐⭐⭐⭐	新功能先设计再写代码	自然语言提需求后 AI 按风险判断路由；或 `/pua`
`optimize`	⭐⭐⭐⭐	Qoder 风格优化输入，把白话变成 LLM 能懂的专业 prompt	`/optimize` / "优化输入" / "优化输出"
`pua-learning-loop`	⭐⭐⭐⭐	让 AI 记住踩坑经验不重犯	自然语言纠正 AI 时自动触发
`project-knowledge-writer`	⭐⭐⭐⭐	给新项目建知识包，AI 上手更快	"初始化知识包" / "梳理 XX 业务"
`pua-max-reasoning`	⭐⭐⭐	复杂问题深度推理，防敷衍	`/pua-max`
`llm-degradation-detector`	⭐⭐⭐	检测 AI 是否"降智"	`/iq`

⭐⭐⭐⭐⭐ `brainstorming-pua` — 新功能必经之路

什么时候用：新增功能、架构变更、模糊需求 — 任何需要先想清楚再动手的场景。

为什么必用：直接写代码是返工最大根源。本技能强制先完成需求澄清，再走 OpenSpec 渐进确认（做一步确认一步），从源头杜绝"做完了发现方向错"。

怎么用：

# 方式1：自然语言（AI自动路由到本技能）
你: "我要做一个用户积分系统"
AI: → 自动进入 brainstorming-pua 流程

# 方式2：显式触发
你: /pua
AI: → PUA 完全接管，包含 brainstorming

# 方式3：在 PUA 流程中被自动调用
AI 判断需求为 G2+ 时，自动进入设计阶段

流程概览：

Core Clarification（5维度澄清）
  → Explore（发散：方案对比、边界识别）
  → Structure（收敛：OpenSpec 文档落地）
    → A. 完整路径：Proposal → Specs → Design → Tasks
    → B. 合并路径：Proposal+Specs → Design → Tasks
    → C. 对话确认（仅限 R0-R1 小改）

新手建议：第一次用选 A（完整路径），感受一下流程全貌后再根据需求选择 B 或 C。

⭐⭐⭐⭐ `optimize` — Qoder 风格优化输入

什么时候用：脑子里有个想法但说不清楚、需求描述太简短，或想像 Qoder 的"优化输入/优化输出"一样，把白话改成 LLM 能正确理解的专业提问词。

为什么推荐：一句话需求 → 可直接作为真正提问使用的专业 prompt。optimize 只改写提问，不回答问题、不查询代码、不执行任务；输出后只保留一句“是否按这个提示词执行询问？”。

怎么用：

# 直接触发
你: /optimize 加个搜索功能
AI: → 输出优化后的 prompt 正文，并询问是否按这个提示词执行询问

# 自然语言触发
你: "帮我优化这个需求描述"
你: "优化输出：加个搜索功能"
你: "像 Qoder 那样优化输入"
你: "这个想法不够清晰，帮我完善一下"

优化效果示例：

维度	输入	优化后
目标	"加个搜索"	"为列表页添加关键词搜索，支持实时过滤"
约束	无	"响应 < 300ms，输入防抖 300ms"
验收	无	"搜索结果高亮、搜索历史可清除、单元测试覆盖率 > 80%"

⭐⭐⭐⭐ `pua-learning-loop` — 让 AI 不重蹈覆辙

什么时候用：纠正了 AI 一次、发现 AI 重复犯同样的错、想把项目经验沉淀下来给后续对话复用。

为什么推荐：没有学习循环 = 每次对话从零开始。有了学习循环 = AI 越用越懂你的项目。踩坑记录存入 .copilot/cards/，下次自动匹配。

怎么用：

# 自然触发：纠正 AI 时自动激活
你: "这个字段叫 PartnerAgency，不叫 Agency"
AI: → 自动记录到 .copilot/cards/，后续不再犯

# 显式触发
你: "记住这个项目的数据库用的是 PostgreSQL 不是 MySQL"
你: "沉淀一下上次踩的坑"
你: "初始化学习库"

初始化项目学习库：

# PowerShell
powershell -NoProfile -ExecutionPolicy Bypass -File "$env:USERPROFILE\.claude\skills\pua-learning-loop\scripts\init-copilot.ps1" -Root "<项目路径>"

# Linux/macOS
bash ~/.claude/skills/pua-learning-loop/scripts/init-copilot.sh -Root "<项目路径>"

渐进式加载：不会一次性读取所有学习卡片，而是先读索引 → 命中才读具体卡片，避免上下文浪费。

⭐⭐⭐⭐ `project-knowledge-writer` — 项目知识包生成与维护

什么时候用：新项目要建知识体系、新增业务模块需要梳理、代码变更后知识文档需要同步更新。

为什么推荐：知识包 = AI 进入项目的心智地图。没有知识包 = AI 每次都要重新摸索项目结构。有了知识包 = AI 上手速度提升数倍，回答更贴合项目实际。

怎么用：

# 初始化（新项目首次使用）
你: "给这个项目生成知识包"
你: "初始化 project-knowledge"
AI: → 扫描项目结构 → 生成 docs/project-knowledge/ 全套文档

# 追加业务域
你: "新增了一个支付模块，帮我更新知识文档"
你: "梳理一下订单业务，沉淀到知识包"

# 更新已有文档
你: "知识包 XX 文件过时了，重新扫描更新"

知识包结构（自动生成）：

docs/project-knowledge/
├── AI-START-HERE.md          ← AI 进入仓库时的第一站
├── index.md                  ← 阅读顺序 + 风险边界
├── registry.json             ← 机器可读索引
├── 00-overview.md            ← 项目全局脑图
├── 01-canonical-glossary.md  ← 术语表
├── 02-domain-entities.md     ← 领域实体
├── ...（共12个标准文档）
└── {NN}-{domain}-deep-dive.md ← 按需深挖

与 graphify 联动：如果项目已有 graphify-out/ 图谱，知识包初始化会自动参考图谱社区结构，加速梳理。

⭐⭐⭐ `pua-max-reasoning` — 深度推理模式

什么时候用：复杂架构决策、多因素权衡、AI 推理深度不够时需要"加码"、关键变更需要最强验证。

为什么选这个等级：日常开发不需要，但遇到真正复杂的问题时非常有价值。比普通 PUA 流程多了多层因果链分析、逻辑谬误识别、隐含假设揭示。

怎么用：

# 直接触发
你: /pua-max
AI: → 在当前 PUA 流程基础上增强推理深度

# 自然语言触发
你: "这个架构问题需要深度思考"
你: "max reasoning"
你: "帮我深度分析一下这个方案的利弊"

增强维度：

能力	普通模式	Max Reasoning
推理深度	一层因果	多层因果链 + 逻辑谬误识别
理解	字面理解	深度意图 + 隐含需求挖掘
反思	被动纠错	主动纠错 + 重复错误预防
验证	标准验证	多维度验证 + 闭环验证机制

注意：/pua-max 会显著增加输出长度和推理时间，日常简单任务不必使用。

⭐⭐⭐ `llm-degradation-detector` — AI 降智检测

什么时候用：感觉 AI 变笨了、连续出错、回答质量明显下降、想量化诊断 AI 当前推理能力。

为什么选这个等级：排障工具而非日常工具。当你怀疑 AI 状态不对时，用它拿到客观诊断数据。

怎么用：

# 直接触发
你: /iq
AI: → 九维自评报告 + 推理能力等级判定

# 自然语言触发
你: "你是不是降智了？"
你: "IQ check"
你: "回答质量下降了，检测一下"

输出格式：

🧠 LLM 推理能力检测报告

等级：IQ-4 ✅ 正常推理（总分 32/45）

九维评分：
| 维度           | 得分 | 依据摘要 |
|---------------|------|---------|
| 推理深度       | 4/5  | 能追踪两层因果 |
| 上下文保持     | 3/5  | 遗忘了第2轮的一个约束 |
| 工具使用策略   | 4/5  | 精准选择搜索工具 |
| ...            | ...  | ...     |

建议：上下文保持稍弱，建议拆分长对话或用 /pua-max 增强推理

六级等级：IQ-5 巅峰 → IQ-4 正常 → IQ-3 轻度衰减 → IQ-2 明显衰减 → IQ-1 严重衰减 → IQ-0 不可用

防自吹机制：首次检测 IQ-5 不可达（必须有用户零纠正 + 主动发现问题才解锁）；高分需举证倒置。

特色技能详解

`SKILL.md` 的 `description` 应该怎么写

description 的作用不是写口号，而是让 AI 和用户快速知道这个 skill 做什么、什么时候用、可能用什么关键词触发。

推荐写法：

先写用途：这个 skill 解决什么任务
再写适用场景：什么情况下使用
补充必要英文关键词：便于中英混合输入触发
边界容易混淆时再补 DO NOT USE FOR

推荐结构：

当需要做 X 时使用。Use when ...
用于 X。Triggers: A, B, C.
边界复杂的 skill 可采用 USE FOR / DO NOT USE FOR

不推荐：

只写口号、态度或情绪化旁白
用一长句混合用途、流程纪律和管理话术
写完后仍看不出“这个 skill 到底什么时候该用”

示例：

brainstorming-pua：当新功能、行为变更或模糊需求需要先做设计时使用。Use when handling new features, behavior changes, ambiguous requirements, or OpenSpec design work.
writing-plans-pua：当已确认的需求或设计需要转成可执行的多步骤计划时使用。Use when creating an execution plan, task breakdown, or implementation steps from approved requirements or design.
systematic-debugging-pua：当排查 Bug、测试失败、异常行为或多次修复无效时使用。Use when debugging bugs, test failures, regressions, or unexpected behavior.

`pua-gate` — 自适应门禁

不是每个问题都需要走完整流程，pua-gate 按任务复杂度自动分档：

档位	触发条件	执行方式
G0/G1	简单问题（改名、解释、单行修复）	一行微标，直接执行
G2	多步骤 / 跨文件任务	简版门禁，列关键约束后执行
ESCALATE	连续失败 / 用户不满 / 高风险变更	调用 `pua-escalation` 收紧再继续
BLOCKED	需求几乎空白	停止推进，问一个最小澄清问题

`pua-escalation` — 压力升级引擎

LLM 连续失败时最常见的问题是：换措辞但不换方案，原地打转。pua-escalation 提供五级压力等级和强制切换规则：

等级	触发时机	强制行为
E0	正常执行	无额外约束
E1	第 1 次失败	必须重新搜索 / 读文件再开口
E2	第 2 次失败	换本质不同的方案（换参数不叫换方案）
E3	第 3 次失败	七项检查清单全部完成才能继续
E4	第 4+ 次失败	停止执行，等待人工介入

`brainstorming-pua` — 需求澄清与方案设计

新功能直接写代码是大多数返工的根源。本 skill 强制先完成核心问题澄清，再走 OpenSpec SDD 渐进确认，做一步确认一步：

完整路径（R3+ / 低成熟度）：
Core Clarification → Proposal → Specs → Design → Tasks（4 次确认）

合并路径（R2 + 成熟度 5+）：
Core Clarification → Proposal+Specs → Design → Tasks（3 次确认）

`llm-degradation-detector` — LLM 推理能力检测（`/iq`）

当 AI 连续出错，你需要知道它现在的推理能力处于什么水平。发送 /iq 触发九维自评报告：

九维评分（每维 0-5 分，总分 45）：

推理深度 · 上下文保持 · 工具使用策略 · 边界与风险识别 · 指令遵循精度 · 自我纠错能力 · 创造力 · 影响面意识 · 幻觉与事实可靠性

`pua-max-reasoning` — 高级推理模式（`/pua-max`）

在现有 PUA 流程基础上增强推理深度、理解、反思和验证能力。不是替代现有流程，而是在每个流程阶段增强推理能力，确保 AI 不能推理一半就敷衍结束。

核心能力：

推理深度增强：多层因果链分析、逻辑谬误识别、隐含假设揭示、缺失因素考虑
理解能力增强：深度意图分析、项目上下文理解、多维度理解、善意解释原则
反思能力增强：自我纠错机制、重复错误避免、方案对比反思、失败模式分析
验证能力增强：严格验证标准、事实驱动验证、多维度验证、闭环验证机制
多轮推理验证 Loop：自动多轮推理、迭代验证、收敛判断、反思总结、动态调整
强制推理验证：AI 不得跳过推理和验证步骤，必须完成完整流程
Harness 机制：确保推理过程完整，不能推理一半就敷衍结束

触发方式：/pua-max、max reasoning、advanced reasoning、deep thinking、enhanced validation

`caveman` + `rtk` — 双层 Token 压缩

联合使用最高可节省 ~95% 总 token 消耗，大幅降低 API 费用和上下文占用：

技能	方向	压缩率	原理
`caveman`	输出压缩	~75%	移除填充词、客套话，使用片段化表达。四强度：`lite`/`full`/`ultra`/`wenyan`
`rtk`	输入压缩	60-90%	CLI 命令输出智能过滤，去除噪声和冗余行，保留关键信息

触发方式：

caveman：/caveman（默认 full）或 /caveman lite|ultra|wenyan
rtk：安装后命令自动加 rtk 前缀，如 rtk git status

安装指南

支持四个 AI 编码平台，按需选择：

平台	Skill 支持	指令文件	重要
Claude Code	完整 `SKILL.md` + references	`CLAUDE.md` / `.claude/instructions.md`	安装 skills 和添加入口指令
OpenAI Codex CLI	不加载 `SKILL.md`；Markdown 规则	`AGENTS.md`	必须内联完整规则
CodeBuddy	Skills via `.codebuddy/skills/`	Rules: `.codebuddy/rules/<name>/RULE.mdc`	RULE.mdc 必须含完整规范内容
GitHub Copilot	不加载 `SKILL.md`；Markdown 规则	`.github/copilot-instructions.md`	规则必须内联写入指令文件

详细安装指南：docs/SETUP.md

快速安装（Claude Code）

# 复制 skills 到用户目录
cp -r skills/* ~/.claude/skills/

# 在项目 CLAUDE.md 中添加按需入口指令
echo '当任务需要 PUA 门禁、Design/Escalate Path、风险升级、阶段交接或最终交付检查时，优先调用/加载 `using-superpowers-pua` skill；普通纯问答、低风险事实动作或已确认计划的小步执行可直接走 Fast Path。' >> CLAUDE.md

流程状态看板

AI 进入 PUA 流程时可显示流程进度：

🟠 PUA · 阿里味 · G2 · 设计阶段
进度：[██████░░░░] 60% (3/5 层)
当前：Design 技术设计
下一步：确认技术方案 → Tasks 任务清单

快速通道条件

满足以下全部条件时，可直接进入实现（跳过设计）：

需求成熟度 ≥ 8
变更风险 ≤ R1
影响文件 ≤ 2 个
用户明确说"我知道怎么做"
无新功能/新模块/新API

回退命令

/back：回到上一步
/restart：重新开始当前阶段
/simplify：切换到简化模式
/full：切换到完整模式
/diagnose：流程诊断

项目结构

PUA-Driven-Spec-Engineering/
├── skills/                    # 30 个技能文件（含 caveman/rtk Token 压缩）
├── .codebuddy/               # CodeBuddy 项目级规则
├── .github/                  # GitHub Copilot 指令
├── docs/                     # 文档目录
├── AGENTS.md                 # Codex CLI 规则
├── CLAUDE.md                 # Claude Code 指令
└── README.md                 # 本文件

典型工作流

简单任务（G0/G1）

You: "Rename this function"
→ G0 PASS · Direct execution · No full lifecycle needed

中等任务（G2）

You: "Add user registration"
→ G2 · brainstorming-pua → writing-plans-pua → TDD → verification

高压任务（ESCALATE）

You: "/pua this bug has failed 3 times"
→ ESCALATE · pua-escalation (E2: must search, read, list hypotheses)
→ systematic-debugging-pua → verification-before-completion-pua

如何知道流程在工作

这些指南在工作时，你会看到：

PUA 微标：进入 PUA 门禁或方法论路由时出现的 🟠 PUA · {flavor} · G0 · {constraint}
升级动作：当你表达不满或连续失败时
证据先于声明：没有验证输出就不会说"完成了"
外科手术式修改：只有被要求的修改才会出现在 diff 中
设计先于实现：新功能会先经过 brainstorming

License

MIT

PUA-Driven-Spec-Engineering

Set up

README

PUA-Driven Spec Engineering

核心价值

快速上手（5 分钟）

三种场景快速上手

决策速查表

核心机制

入口压缩（v2）

门禁档位（入口统一评估）

三条红线

四层知识体系对比

常用技能速查

⭐⭐⭐⭐⭐ brainstorming-pua — 新功能必经之路

⭐⭐⭐⭐ optimize — Qoder 风格优化输入

⭐⭐⭐⭐ pua-learning-loop — 让 AI 不重蹈覆辙

⭐⭐⭐⭐ project-knowledge-writer — 项目知识包生成与维护

⭐⭐⭐ pua-max-reasoning — 深度推理模式

⭐⭐⭐ llm-degradation-detector — AI 降智检测

特色技能详解

SKILL.md 的 description 应该怎么写

pua-gate — 自适应门禁

pua-escalation — 压力升级引擎

brainstorming-pua — 需求澄清与方案设计

llm-degradation-detector — LLM 推理能力检测（/iq）

pua-max-reasoning — 高级推理模式（/pua-max）

caveman + rtk — 双层 Token 压缩

安装指南

快速安装（Claude Code）

流程状态看板

快速通道条件

回退命令

项目结构

典型工作流

简单任务（G0/G1）

中等任务（G2）

高压任务（ESCALATE）

如何知道流程在工作

License

⭐⭐⭐⭐⭐ `brainstorming-pua` — 新功能必经之路

⭐⭐⭐⭐ `optimize` — Qoder 风格优化输入

⭐⭐⭐⭐ `pua-learning-loop` — 让 AI 不重蹈覆辙

⭐⭐⭐⭐ `project-knowledge-writer` — 项目知识包生成与维护

⭐⭐⭐ `pua-max-reasoning` — 深度推理模式

⭐⭐⭐ `llm-degradation-detector` — AI 降智检测

`SKILL.md` 的 `description` 应该怎么写

`pua-gate` — 自适应门禁

`pua-escalation` — 压力升级引擎

`brainstorming-pua` — 需求澄清与方案设计

`llm-degradation-detector` — LLM 推理能力检测（`/iq`）

`pua-max-reasoning` — 高级推理模式（`/pua-max`）

`caveman` + `rtk` — 双层 Token 压缩