# https://github.com/AlexZio00/sovereign-skills 项目说明书

生成时间：2026-06-27 08:38:43 UTC

## 目录

- [Overview, Installation & System Architecture](#page-1)
- [Setup & Initialization Skills (project-init, setup)](#page-2)
- [Daily Workflow & Discipline Skills (scope, freeze, goal-lock, pre-push, stepback)](#page-3)
- [Quality, Review & Session Management (code-autopsy, project-check, collab-audit, session-start, session-checkpoint)](#page-4)

<a id='page-1'></a>

## Overview, Installation & System Architecture

### 相关页面

相关主题：[Setup & Initialization Skills (project-init, setup)](#page-2), [Daily Workflow & Discipline Skills (scope, freeze, goal-lock, pre-push, stepback)](#page-3), [Quality, Review & Session Management (code-autopsy, project-check, collab-audit, session-start, session-checkpoint)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
- [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md)
- [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml)
- [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md)
- [project-init/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/agents/openai.yaml)
- [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md)
- [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml)
- [code-autopsy/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/SKILL.md)
- [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md)
- [freeze/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/agents/openai.yaml)
- [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md)
</details>

# Overview, Installation & System Architecture

## 1. 项目概述

`sovereign-skills` 是一个面向 Claude Code 的「主权技能」(sovereign-skills) 集合，提供从项目初始化到代码审查的完整 AI 协作工作流。该项目遵循"访谈优于模板、验证优于信任、范围先于代码、诚实报告、会话连续性"五大设计原则。资料来源：[README.md:1-30]()

截至最新版本 v6.2，本仓库收录了 10 余个技能（Skill），按生命周期被划分为四类：**Setup**（一次性基础设施）、**Daily Loop**（每日循环）、**On Demand**（按需调用）和 **Quality**（质量审计）。资料来源：[README.md:30-60]()

每个技能都是一个独立的目录，包含 `SKILL.md`（或 `skill.md`）作为主指令文件，以及可选的 `agents/openai.yaml` 用于多代理路由。例如 `scope` 技能定义任务范围与依赖关系，资料来源：[scope/agents/openai.yaml:1-4]()；`project-init` 技能初始化新项目结构，资料来源：[project-init/agents/openai.yaml:1-4]()；`setup` 技能配置运行时环境与依赖，资料来源：[setup/agents/openai.yaml:1-4]()。

## 2. 安装与配置

### 2.1 作为 Marketplace 插件安装

本仓库在 `.claude-plugin/marketplace.json` 中注册为 Claude Code 的 Marketplace 插件源。安装流程：

1. 在 Claude Code 中添加 Marketplace 仓库地址：`AlexZio00/sovereign-skills`
2. 选择目标项目目录运行 `/setup` 或 `/project-init`
3. 技能自动从仓库内对应子目录加载

### 2.2 `/project-init` — 新项目引导

该技能通过一次一问的访谈生成 `CLAUDE.md`、`ROADMAP`、`.gitignore`、`.env.example` 等基础文件。访谈覆盖 Q1–Q7：项目一句话描述、语言/运行时、数据层、接口、部署、时间线与团队规模、Hard Rules。资料来源：[project-init/skill.md:1-60]()

> **Discard 规则**：已运行的产线项目若要替换 Hard Rules，应改用 `/setup`，而非 `/project-init`。资料来源：[project-init/skill.md:30-50]()

生成的文件结构依据语言不同而变化，例如 Kotlin Spring Boot 项目会生成 `controller/service/repository/domain` 包结构，Go CLI 项目会生成 `cmd/[app]/main.go`。资料来源：[project-init/skill.md:100-160]()

### 2.3 `/setup` — 基础设施与代理团队

`/setup` 在 `/project-init` 之上配置 Claude Code 的 harness 层——rules、hooks、memory、routing。它根据"项目规模"（Standard+、review gates 等条件）决定生成哪些文件。资料来源：[setup/SKILL.md:1-30]()

关键产物包括 `~/.claude/rules/project rules`、`~/.claude/settings.json`（合并 hooks）、`memory/MEMORY.md` 与 `memory/session-handoff-LATEST.md`。该技能的 **Dominant Variable** 是"生成的项目规则 Tier 0 规则能否通过违规测试"——没有测试的规则只是装饰。资料来源：[setup/SKILL.md:30-60]()

## 3. 系统架构

### 3.1 技能目录结构

每个技能是一个自包含的子目录，统一使用 `SKILL.md` 承载主指令、`agents/*.yaml` 承载代理元数据。这种"一个技能一个目录"的约定使得技能可以独立分发、独立升级。

```mermaid
graph TD
    A[sovereign-skills 仓库] --> B[Setup 类]
    A --> C[Daily Loop 类]
    A --> D[On Demand 类]
    A --> E[Quality 类]
    B --> B1[project-init]
    B --> B2[setup]
    C --> C1[session-start]
    C --> C2[scope]
    C --> C3[freeze]
    C --> C4[goal-lock]
    C --> C5[pre-push]
    C --> C6[session-checkpoint]
    D --> D1[stepback]
    D --> D2[adr]
    D --> D3[brief]
    E --> E1[code-autopsy]
    E --> E2[project-check]
    E --> E3[collab-audit]
```

资料来源：[README.md:30-80]()、[scope/SKILL.md:1-20]()、[freeze/agents/openai.yaml:1-4]()、[goal-lock/SKILL.md:1-30]()

### 3.2 技能元数据规范

`agents/openai.yaml` 描述了技能的多代理路由信息，字段包括 `name`、`description`、`instructions`（指向 `../SKILL.md`）。例如：

```yaml
name: scope
description: "Define and document task scope, dependencies, and architectural boundaries."
instructions: "../SKILL.md"
```

资料来源：[scope/agents/openai.yaml:1-4]()

### 3.3 生命周期流

README 中给出了完整的工作流图：Setup（一次性）→ 每日循环 → 按需调用 → 质量审计。每日循环的核心路径是 `session-start → scope → freeze → goal-lock → work → stepback → code-autopsy → pre-push → session-checkpoint`。资料来源：[README.md:40-70]()

## 4. 核心技能一览

| 类别 | 技能 | 关键能力 |
|------|------|---------|
| 范围定义 | `/scope` | Quick/Full 双模式；Quick 输出 `BRIEF.md`，Full 输出 L0→L4 层链 `spec.md`。资料来源：[scope/SKILL.md:1-30]() |
| 范围冻结 | `/freeze` | 将输入分类为 editable / frozen / read-only 并停止代码生成。资料来源：[freeze/agents/openai.yaml:1-4]() |
| 目标锁定 | `/goal-lock` | 强制 `PLAN→DO→VERIFY→FINALIZE→OUTPUT` 循环；检测 11 种成功伪装模式（如删除测试、包裹 mock、阈值放松）。资料来源：[goal-lock/SKILL.md:1-40]() |
| 视角重置 | `/stepback` | 输出 ≤10 行，1 个抽象重述问题 + 3 项快速检查（scope drift / side effects / better approach）。资料来源：[stepback/SKILL.md:1-60]() |
| 代码审查 | `/code-autopsy` | 12 问量化评审，4 轴加权（Security × 0.35 + Stability × 0.30 + Robustness × 0.20 + Operability × 0.15），输出部署裁定 SHIP/FIX/RISKY/BLOCK。资料来源：[code-autopsy/SKILL.md:1-50]() |

## See Also

- 技能索引与最新发布说明：参考 `README.md` 中分类表
- 各技能详细指令：进入对应子目录的 `SKILL.md`
- 项目模板生成器：`/project-init` 的 Phase 3 文件模板
- 基础设施配置：`/setup` 的 7 行文件生成矩阵

---

<a id='page-2'></a>

## Setup & Initialization Skills (project-init, setup)

### 相关页面

相关主题：[Overview, Installation & System Architecture](#page-1), [Daily Workflow & Discipline Skills (scope, freeze, goal-lock, pre-push, stepback)](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md)
- [project-init/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/agents/openai.yaml)
- [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md)
- [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml)
- [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
- [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md)
- [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md)

</details>

# Setup & Initialization Skills (project-init, setup)

## 概述与定位

sovereign-skills 仓库提供 12 个面向 Claude Code 完整生命周期的技能,位于项目启动阶段的有两个:`project-init` 与 `setup`。它们承担的职责截然不同却互相衔接——`project-init` 用于在空目录或早期原型中,通过采访式问答生成项目业务层的脚手架(CLAUDE.md、ROADMAP、.gitignore、.env.example);`setup` 用于在已有项目根目录之上装配 Claude Code 的 AI 编排层(rules、hooks、memory、agent routing)。README 明确指出两者都属于 `skill_type: infrastructure` 类别,并体现「interview over template」的核心设计原则:技能通过提问采集决策,再生成带有真实内容的文件,而非空骨架 资料来源:[README.md]()。

## project-init — 项目脚手架设计采访

`project-init` 的核心变量是「采访收集的决策是否准确反映到生成文件中」,若采访回答与最终生成的 CLAUDE.md/ROADMAP 内容不一致,项目便会基于错误前提启动 资料来源:[project-init/skill.md]()。其执行流程分四个阶段:

- **Phase 0 — 上下文检查**:检测当前工作目录是否存在 `CLAUDE.md`。若已存在,询问用户「更新 / 重新写入 / 取消」,避免覆盖既有内容 资料来源:[project-init/skill.md]()。
- **Phase 1 — 采访**:逐题询问语言/运行时、数据层、交互接口、部署目标、项目规模与团队、Hard Rules 等关键决策。每题附带决策指引,例如 Python 适合数据/ML/自动化,TypeScript 适合 Web/API 全栈统一,Go 适合高性能服务与 CLI 工具 资料来源:[project-init/skill.md]()。
- **Phase 2 — 栈决策摘要**:汇总采访答案并要求用户显式确认,确认后方可进入生成阶段,避免在未对齐时即落盘 资料来源:[project-init/skill.md]()。
- **Phase 3 — 文件生成**:按语言生成定制化的 CLAUDE.md、`docs/DEVELOPMENT_ROADMAP.md`、`.gitignore` 与(按需)`.env.example`;目录布局也按 Python、TypeScript、Kotlin-后端、Kotlin-Android、Go 等分别给出 资料来源:[project-init/skill.md]()。

触发词涵盖 `/project-init`、韩语「새 프로젝트」「프로젝트 셋업」、英语 `project setup`、`new project` 等 资料来源:[project-init/skill.md]()。OpenAI 端代理元数据通过 `instructions: "../SKILL.md"` 复用同一份技能定义,使 Codex 与 Claude 共享行为契约 资料来源:[project-init/agents/openai.yaml]()。

## setup — Claude Code 基础设施与代理团队配置

`setup` 的核心变量是「初始化后的 harness 能否在下一会话立即生效」,rules/hooks/memory/routing 必须从安装后的第一个 session 起即可用,否则视为失败 资料来源:[setup/SKILL.md]()。与 `project-init` 关注业务脚手架不同,`setup` 装配的是 AI 协作层:

- 生成 `~/.claude/rules/project rules`、`agents.md`(Standard+ 项目)、`output-style.md`、`development-workflow.md`(含 review gates 的项目)等规则文件。其中 Tier 0 规则必须通过违规测试,未测试的规则仅是装饰 资料来源:[setup/SKILL.md]()。
- 合并 `~/.claude/settings.json` 中的 hooks,并初始化 `memory/MEMORY.md` 与 `memory/session-handoff-LATEST.md`,为后续 `session-start` / `session-checkpoint` 提供上下文载体 资料来源:[setup/SKILL.md]()。
- 通过领域预设(domain presets)输出预填充规则,确保 rules 不是空壳 资料来源:[setup/SKILL.md]()。

其触发词包含 `/setup`、`setup`、`harness setup`、`agent team setup` 等;OpenAI 代理描述补充了「运行时环境配置、依赖安装、项目初始化校验」 资料来源:[setup/agents/openai.yaml]()。

## 关键差异与协作流程

下表对二者边界做精确切分,并衔接 README 中 Quick Start 给出的执行序列 资料来源:[README.md]()。

| 维度 | project-init | setup |
|------|--------------|-------|
| 适用阶段 | 新建空目录或早期原型 | 任意已有项目根目录 |
| 输出对象 | 业务脚手架(CLAUDE.md、ROADMAP、目录布局) | AI 编排层(rules、hooks、memory、routing) |
| 决策来源 | 用户采访 + 栈建议 | 用户采访 + 领域预设 |
| 失败模式 | 采访回答与生成文件不一致 | 规则未做违规测试 / hooks 未合并 |
| 后续动作 | 进入日常 `/session-start` 工作流 | 与 `project-init`、`scope`、`goal-lock` 串联 |

README 推荐的序列是:新建项目先执行 `/project-init`,再执行 `/setup`,之后才进入 `/session-start`、`/scope`、`/freeze`、`/goal-lock`、`/stepback`、`/code-autopsy`、`/pre-push`、`/session-checkpoint` 的日常循环 资料来源:[README.md]()。

## 常见边界条件与失效模式

- `project-init` 不适用于「在已上线生产项目中替换 Hard Rules」——该技能专为初始设计而设计,混用会破坏既有上下文 资料来源:[project-init/skill.md]()。
- `setup` 在已有完整 harness 的项目中应谨慎使用,新增单一规则即可的场景不应触发全流程重装 资料来源:[setup/SKILL.md]()。
- 若 `Write` 工具不可用,`project-init` 只能回退为「输出文件内容、由用户手动保存」 资料来源:[project-init/skill.md]()。
- `stepback` 是定位完全不同的辅助技能,输出上限 10 行、只产生 1 个抽象重构问题,且明确不会写入代码或调用代理,因此不应与 `project-init`/`setup` 混用为长流程 资料来源:[stepback/SKILL.md]()。
- `goal-lock` 的 PLAN→DO→VERIFY→FINALIZE→OUTPUT 循环在初始化完成后才生效——它解决执行期纪律,而非初始化期缺失 资料来源:[goal-lock/SKILL.md]()。

## See Also

- 项目整体生命周期与 Quick Start:[README](README.md)
- 范围与边界冻结:`/freeze` 技能([freeze/SKILL.md](freeze/SKILL.md))
- 执行期纪律引擎:`/goal-lock` 技能([goal-lock/SKILL.md](goal-lock/SKILL.md))
- 视角重置:`/stepback` 技能([stepback/SKILL.md](stepback/SKILL.md))

---

<a id='page-3'></a>

## Daily Workflow & Discipline Skills (scope, freeze, goal-lock, pre-push, stepback)

### 相关页面

相关主题：[Overview, Installation & System Architecture](#page-1), [Setup & Initialization Skills (project-init, setup)](#page-2), [Quality, Review & Session Management (code-autopsy, project-check, collab-audit, session-start, session-checkpoint)](#page-4)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
- [scope/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/SKILL.md)
- [scope/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/scope/agents/openai.yaml)
- [freeze/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/freeze/agents/openai.yaml)
- [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md)
- [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md)
- [stepback/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/agents/openai.yaml)
</details>

# Daily Workflow & Discipline Skills（每日工作流与纪律技能）

## 概述与设计目标

`sovereign-skills` 是一套覆盖 Claude Code 项目完整生命周期的技能集。本页聚焦于「日常开发流」中用于约束 AI 行为、防止范围蔓延与目标漂移的五个纪律技能：`/scope`、`/freeze`、`/goal-lock`、`/pre-push`、`/stepback`。

这些技能共享一套核心设计哲学：「面谈优于模板」、「验证优于信任」、「范围先于代码」、「诚实汇报」、「会话连续性」。 资料来源：[README.md]()

它们按典型开发节奏串行工作：会话开始 → `/session-start`；每个特性前 → `/scope` 定义 IN/OUT/退出准则；实现前 → `/freeze` 锁定可编辑区；开发过程中 → `/goal-lock` 强制 PLAN→DO→VERIFY 循环；任意时刻 → `/stepback` 视角重置；推送前 → `/pre-push` 密钥扫描 + 代理评审。资料来源：[README.md]()

## 技能矩阵

| 技能 | 主要职责 | 关键产出 | 典型触发词 |
|------|----------|----------|------------|
| `/scope` | 定义任务范围（IN/OUT 锁定） | `BRIEF.md`（Quick）或 `spec.md`（Full） | `/scope`、`/brief`、`/specify` |
| `/freeze` | 冻结范围、暂停实施 | `FROZEN SCOPE` 块 | `/freeze`、`freeze the scope` |
| `/goal-lock` | 锁定目标，强制 PLAN→DO→VERIFY→FINALIZE→OUTPUT | GOAL + DONE EVIDENCE 输入表 | `/goal-lock`、`lock the goal` |
| `/pre-push` | 推送前安全与质量检查 | 扫描 + 多代理评审汇总 | `/pre-push`、`pre-push 检查` |
| `/stepback` | 一次性视角重置 | ≤10 行输出 + 3 项检查 | `/stepback`、`zoom out`、`big picture` |

资料来源：[scope/SKILL.md]() [stepback/SKILL.md]() [README.md]()

## 详细工作机制

### /scope — 范围定义引擎

`/scope` 在写代码前回答「做什么 / 不做什么」。它提供两种模式：

- **Quick（默认）**：三段式 `IN / OUT / exit criteria`，输出至 `BRIEF.md`
- **Full（`/scope full`）**：执行 L0→L4 分层规格链，输出至 `spec.md`

其「支配变量」是 OUT 项是否被显式写出 —— 仅声明 IN 项会导致实现过程中范围膨胀。Full 模式下则额外以 L2 决策清晰度作为支配变量。资料来源：[scope/SKILL.md]()

不应触发场景：bug 修复、单文件改动、已有规格、脑暴。资料来源：[scope/SKILL.md]()

### /freeze — 范围冻结

`/freeze` 在实施前对输入进行解析，将文件分类为可编辑 / 冻结 / 只读，然后输出 `FROZEN SCOPE` 块并立即停止 —— 不生成代码，也不派生子代理。当输入存在歧义时，先发出一个澄清问题；若仍模糊，则冻结更大的范围以保证安全。资料来源：[freeze/agents/openai.yaml]()（release notes v5.0）

### /goal-lock — 代理纪律引擎

`/goal-lock` 强制 `PLAN → DO → VERIFY → FINALIZE → OUTPUT` 五阶段循环，并检测 11 类「成功伪装」模式（删除测试、Mock 包裹、阈值放宽等）。资料来源：[README.md]()

提供两种模式：**Quick 模式**（3 字段，适用于小改动）与 **Full 模式**（7 字段，适用于其他所有情况）。资料来源：[README.md]()

在 DO 阶段开始前，需对照 RISK 表进行风险检查（破坏性变更、竞态、过期状态、数据丢失、安全、性能回归、向后兼容）。任一风险命中即返回 PLAN 并附加规避策略。资料来源：[goal-lock/SKILL.md]()

VERIFY 阶段必须「真正执行」验证命令，按栈自动选择配方：`pytest -q` + `ruff check`（Python）、`npm test` + `npx eslint .`（JS）、`npx tsc --noEmit` + `npm test`（TS）、`go test ./...` + `go vet ./...`（Go）、`cargo test` + `cargo clippy`（Rust）。未验证项标记为 `NOT RUN: [reason]`，绝不容忍「应该没问题」式假设；同时还需进行 `GroundEval`，确认验证命令本身确实执行过。资料来源：[goal-lock/SKILL.md]()

### /stepback — 一次性视角重置

`/stepback` 是只读、零副作用技能，用于在深度实现中重新校准方向。

**架构流程**（PARSE → STEP-BACK → CHECK → OUTPUT）：

```mermaid
flowchart LR
    A[最近对话上下文] --> B[PARSE<br/>提取当前方向与意图]
    B --> C[STEP-BACK<br/>生成 1 个抽象重框问题]
    C --> D[CHECK<br/>3 项检查:<br/>范围漂移 / 副作用 / 更优方案]
    D --> E[OUTPUT<br/>≤10 行,立即返回]
```

阶段说明：
- **PARSE**：抽取当前方向、原始意图、范围信号
- **STEP-BACK**：采用 DeepMind step-back 模式，从具体主题抽象到一般原则或系统
- **CHECK**：执行 3 项检查 —— 范围漂移、副作用、更优方案

**严格不变式**（任一违反即失败）：

1. **10 行上限** —— 超出即视为过度解释，稀释了视角重置效果
2. **1 个问题限制** —— 多问题会分散焦点
3. **立即返回** —— 不附加后续动作或菜单，让用户决定下一步

资料来源：[stepback/SKILL.md]()

不应触发场景：工作已完成（用回顾工具）、请求代码评审（用代码评审工具）、需要具体变更影响分析（用范围定义工具）。资料来源：[stepback/SKILL.md]()

## 集成模式与失败应对

五个技能构成顺序门禁链：`scope` 定义 → `freeze` 锁定 → `goal-lock` 守护 → `stepback` 校准 → `pre-push` 验收。每个阶段都强制产出「可验证产物」（文档 / 块 / 检查表），避免「应该通过」式幻觉。

在 v4.7 中，`pre-push` 引入了代理失败恢复机制：代理超时或出错时重试一次；仍失败则在汇总中标记 `⚠️ SKIPPED (agent unavailable — {agent})` 并继续流程；绝不会把失败的代理静默视为 PASS。这一原则与 `goal-lock` 中「验证必须实际执行」的纪律一脉相承。资料来源：[README.md]()

## 参见

- Code Review & Analysis（`code-autopsy`）
- Session Management（`session-start` / `session-checkpoint`）
- Project Setup（`project-init` / `setup`）

---

<a id='page-4'></a>

## Quality, Review & Session Management (code-autopsy, project-check, collab-audit, session-start, session-checkpoint)

### 相关页面

相关主题：[Overview, Installation & System Architecture](#page-1), [Daily Workflow & Discipline Skills (scope, freeze, goal-lock, pre-push, stepback)](#page-3)

<details>
<summary>相关源码文件</summary>

以下源码文件用于生成本页说明：

- [code-autopsy/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/SKILL.md)
- [code-autopsy/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/code-autopsy/agents/openai.yaml)
- [stepback/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/stepback/SKILL.md)
- [goal-lock/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/goal-lock/SKILL.md)
- [setup/SKILL.md](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/SKILL.md)
- [project-init/skill.md](https://github.com/AlexZio00/sovereign-skills/blob/main/project-init/skill.md)
- [project-check/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/project-check/agents/openai.yaml)
- [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
- [setup/agents/openai.yaml](https://github.com/AlexZio00/sovereign-skills/blob/main/setup/agents/openai.yaml)
</details>

# Quality, Review & Session Management (code-autopsy, project-check, collab-audit, session-start, session-checkpoint)

## 概述

`sovereign-skills` 把"质量保证"拆成三个层次：**单次代码评审**（`code-autopsy`）、**项目级成熟度审计**（`project-check`）、**协作行为模式审计**（`collab-audit`）；再用两个会话生命周期技能（`session-start` / `session-checkpoint`）保证上下文在多次会话之间可恢复。五个技能在 README 的 Daily Loop 中被编排为标准工作流的一部分 资料来源：[README.md:1-50]()。

`code-autopsy` 在 v6.2 中首次发布，定位为可独立运行的提示词，不绑定 Claude Code；`project-check` 与 `collab-audit` 已在 README 分类表中列出；`session-start` / `session-checkpoint` 自 v4.0 起作为会话开闭的固定节点 资料来源：[README.md:25-70]()。

## code-autopsy — 12 问量化代码评审

### 设计目标与作用域

`code-autopsy` 自称 "12 Questions + Quantified Severity + Deployment Verdict + 4-Axis Scoring"，身份被声明为 "Staff Security Engineer (20yr experience)"，使命是 "Trust nothing" 资料来源：[code-autopsy/SKILL.md:42-48]()。它采用白名单（allow-list）约束：仅允许 12Q 分析、严重度评分、diff 建议、审计工具执行、部署裁决与复合得分；推测、空泛赞美、虚构 CVE 等行为被显式禁止 资料来源：[code-autopsy/SKILL.md:48-58]()。

### 12 个评估维度

评审问题分为 Q1–Q12，覆盖设计、简洁性、缺陷、功能、安全、重复、性能、通用化、死代码、测试质量、错误弹性、可观测性 资料来源：[code-autopsy/SKILL.md:1-28]()。其中安全相关问题被加粗强调（API 向后兼容、嵌套 ≤3、注释仅解释 "why"、竞态/死锁/共享状态、依赖与许可证、供应链等），体现了对 OWASP 与工程实践的硬性要求 资料来源：[code-autopsy/SKILL.md:1-20]()。

### 4 轴加权与部署裁决

四个评估轴及权重：Security × 0.35、Stability × 0.30、Robustness × 0.20、Operability × 0.15 资料来源：[code-autopsy/SKILL.md:1-10]()。Severity Anchor Table 给出 7–8 / 5–6 / 3–4 / 1–2 四档严重度，并按 Impact、Probability、Fix Cost、Detectability 四个属性做矩阵 资料来源：[code-autopsy/SKILL.md:30-38]()。最终输出 SHIP / FIX / RISKY / BLOCK 四档部署裁决，并在标注 🔴 CRITICAL 之前强制走 **CRITICAL Reachability Gate**——若不可达或触发不现实，必须降级并标记 `[theoretical]` 资料来源：[code-autopsy/SKILL.md:36-42]()。

### 反作弊机制

为防止 LLM 抬高分数，`code-autopsy` 引入两条元检测规则：

| 机制 | 用途 | 来源 |
|------|------|------|
| CapCode Ceiling Metric | 限制每个类别的"合法性能上限"，超出即降级为 FIX FIRST | 资料来源：[code-autopsy/SKILL.md:42-50]() |
| CEF Fabrication Detection | 验证错误码是否真实存在于后端 schema，识别"系统错误"敷衍式 catch-all | 资料来源：[code-autopsy/SKILL.md:48-58]() |

另外，**静默失败**通过 grep 模式直接抓取（空 `except` / `except pass`、日志报错但调用方无感知、宽 catch 吞错、`or default` 隐藏回退），并赋予 CRITICAL 或 HIGH 严重度 资料来源：[code-autopsy/SKILL.md:58-70]()。

## project-check 与 collab-audit — 项目与协作维度

`project-check` 扫描已有项目，按 4 个维度输出缺口排序：Infrastructure、Security、Quality、Harness 资料来源：[README.md:30-50]()。其 agent 注册文件则描述为 "Audit project harness maturity across 6 axes and 58-item checklist with static and behavioral analysis"，意味着它同时做静态与行为分析 资料来源：[project-check/agents/openai.yaml:1-3]()。

`collab-audit` 是 14 节 AI 协作审计，与问卷调查不同，它**分析用户真实的工作模式**——生成行为画像、盲点与成长方向 资料来源：[README.md:30-50]()。两者的区别在于：`project-check` 评估"项目自身"，`collab-audit` 评估"人与 AI 协作的方式"。

## Session Management — 上下文延续

会话类技能解决"跨会话记忆丢失"问题。`session-start` 在会话打开时加载 handoff、回顾 lessons、发出 ready 信号；`session-checkpoint` 在会话关闭前抽取实体、重写 handoff、保存 memory 资料来源：[README.md:50-70]()。v5.0 之后 `session-checkpoint` 吸收了 `retro` 的反思能力，作为 Phase 1.7 Reflexion 步骤内置 资料来源：[README.md:60-80]()。

## 整体工作流

```mermaid
flowchart LR
    A[session-start] --> B[scope / freeze]
    B --> C[goal-lock]
    C --> D[work + stepback]
    D --> E[code-autopsy]
    E --> F[pre-push]
    F --> G[session-checkpoint]
    G -.handoff.-> A
```

`stepback` 在工作过程中随时触发，作用是生成 1 个抽象重述问题 + 3 项快速检查（scope drift / side effects / better approach），并以 10 行内输出立即返回 资料来源：[stepback/SKILL.md:1-30]()。`goal-lock` 提供 PLAN→DO→VERIFY→FINALIZE→OUTPUT 循环，并在 VERIFY 阶段依据栈自动选择验证命令（pytest / jest / tsc / go test / cargo test / git diff --stat） 资料来源：[goal-lock/SKILL.md:1-50]()。

## 失败模式与边界

- **评审超出范围**：`code-autopsy` 限定白名单，凡未列入 12Q 与裁决流程的判断一律 fail-closed 资料来源：[code-autopsy/SKILL.md:48-58]()。
- **会话中断**：若无 `session-checkpoint` 写入 handoff，下次 `session-start` 无法恢复实体与教训。
- **LLM 策略性逃避**：CEF Fabrication 与 CapCode 是 `code-autopsy` 的两道防线，遇到"系统错误"或分数异常跳升必须复核 资料来源：[code-autopsy/SKILL.md:42-58]()。
- **视角漂移**：进入实现深水区时应主动调用 `stepback` 触发 10 行内的重置 资料来源：[stepback/SKILL.md:1-30]()。

## See Also

- 项目结构与生命周期入口：参见 [README.md](https://github.com/AlexZio00/sovereign-skills/blob/main/README.md)
- Agent 团队与基础设施初始化：`setup/SKILL.md`
- 目标锁定与执行循环：`goal-lock/SKILL.md`
- 视角重置与盲点检查：`stepback/SKILL.md`

---

<!-- evidence_pipeline_checked: true -->
<!-- evidence_injected: true -->

---

## Doramagic 踩坑日志

项目：AlexZio00/sovereign-skills

摘要：发现 8 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。

## 1. 身份坑 · 仓库名和安装名不一致

- 严重度：medium
- 证据强度：runtime_trace
- 发现：仓库名 `sovereign-skills` 与安装入口 `skills` 不完全一致。
- 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。
- 复现命令：`npx skills`
- 证据：identity.distribution | https://github.com/AlexZio00/sovereign-skills | repo=sovereign-skills; install=skills

## 2. 配置坑 · 可能修改宿主 AI 配置

- 严重度：medium
- 证据强度：source_linked
- 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
- 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
- 证据：capability.host_targets | https://github.com/AlexZio00/sovereign-skills | host_targets=claude_code, claude, cursor

## 3. 能力坑 · 能力判断依赖假设

- 严重度：medium
- 证据强度：source_linked
- 发现：README/documentation is current enough for a first validation pass.
- 对用户的影响：假设不成立时，用户拿不到承诺的能力。
- 证据：capability.assumptions | https://github.com/AlexZio00/sovereign-skills | README/documentation is current enough for a first validation pass.

## 4. 维护坑 · 维护活跃度未知

- 严重度：medium
- 证据强度：source_linked
- 发现：未记录 last_activity_observed。
- 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
- 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | last_activity_observed missing

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 证据：downstream_validation.risk_items | https://github.com/AlexZio00/sovereign-skills | no_demo; severity=medium

## 6. 安全/权限坑 · 存在评分风险

- 严重度：medium
- 证据强度：source_linked
- 发现：no_demo
- 对用户的影响：风险会影响是否适合普通用户安装。
- 证据：risks.scoring_risks | https://github.com/AlexZio00/sovereign-skills | no_demo; severity=medium

## 7. 维护坑 · issue/PR 响应质量未知

- 严重度：low
- 证据强度：source_linked
- 发现：issue_or_pr_quality=unknown。
- 对用户的影响：用户无法判断遇到问题后是否有人维护。
- 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | issue_or_pr_quality=unknown

## 8. 维护坑 · 发布节奏不明确

- 严重度：low
- 证据强度：source_linked
- 发现：release_recency=unknown。
- 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
- 证据：evidence.maintainer_signals | https://github.com/AlexZio00/sovereign-skills | release_recency=unknown

<!-- canonical_name: AlexZio00/sovereign-skills; human_manual_source: deepwiki_human_wiki -->