diff --git a/AGENTS.md b/AGENTS.md index 3f29d01..dd3e219 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -145,9 +145,8 @@ git push origin develop │ ├── README.md # docs 总索引 │ ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 │ ├── concepts/ # 核心概念、方法论与底层模型 -│ ├── guides/ # 操作指南预留区 │ ├── playbooks/ # 工具方法与专项实践文档 -│ ├── references/ # 清单、约束、常见坑、审查标准 +│ ├── references/ # 清单、约束、常见坑、模板 │ └── faq.md # 高频问题 │ ├── prompts/ # 提示词库入口（指向云端表格） @@ -211,7 +210,6 @@ git push origin develop - `.github/lint_config.json` - markdownlint 规则，供 `make lint` 与 CI 共用 - `.github/workflows/ci.yml` - GitHub Actions：develop/master 分支 markdown-lint + link-checker - `scripts/check-local-links.py` - 仓库内 Markdown 相对链接检查脚本，供 `make check-links` 与 CI 使用 -- `docs/guides/仓库维护与质量门禁.md` - 仓库维护、迁移检查和质量门禁指南 - `tools/prompts-library/main.py` - 提示词转换工具入口 - `docs/getting-started/CLI配置.md` - 默认 AI CLI 配置入口，文末包含 OpenCode 备选方案 - `docs/playbooks/GEO与SEO优化方法.md` - GEO / SEO 内容工程方法，承接 GEOFlow 的知识库、结构化内容、审核与分发思路 diff --git a/README.md b/README.md index 93afb0b..0a0cf0e 100644 --- a/README.md +++ b/README.md @@ -453,9 +453,8 @@ pip install -r tools/prompts-library/scripts/requirements.txt ├── docs/ # 核心知识库 │ ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 │ ├── concepts/ # 核心概念、方法论与底层模型 -│ ├── guides/ # 操作指南 │ ├── playbooks/ # 工具方法与专项实践文档 -│ └── references/ # 清单、约束、常见坑、审查标准 +│ └── references/ # 清单、约束、常见坑与模板 ├── prompts/ # 提示词库入口（指向云端表格） ├── skills/ # 技能库入口 │ ├── auto-skill/ # 元技能核心 @@ -502,7 +501,7 @@ prompts/ skills/ README.md # skills 总览与索引 docs/ - getting-started/*, concepts/*, guides/*, playbooks/*, references/* 等知识库 + getting-started/*, concepts/*, playbooks/*, references/* 等知识库 assets/ README.md # 外部资源（在线表格）唯一真相源入口 scripts/ diff --git a/docs/AGENTS.md b/docs/AGENTS.md index ecf70ca..3839b17 100644 --- a/docs/AGENTS.md +++ b/docs/AGENTS.md @@ -2,7 +2,7 @@ ## 目录用途 -`docs/` 存放项目核心知识库文档，包含入门路径、核心概念、操作指南、工具方法与参考清单。 +`docs/` 存放项目核心知识库文档，包含入门路径、核心概念、工具方法与参考清单。 ## 目录结构 @@ -11,9 +11,8 @@ docs/ ├── README.md # 知识库总索引 ├── getting-started/ # 从零开始、学习地图、环境与 AI CLI 配置 ├── concepts/ # 核心概念、方法论与底层模型 -├── guides/ # 操作型指南 ├── playbooks/ # 工具方法与专项实践文档 -├── references/ # 清单、约束、常见坑、审查标准 +├── references/ # 清单、约束、常见坑、模板 └── faq.md # 高频问题 ``` @@ -24,7 +23,6 @@ docs/ - `getting-started/Vibe Coding 经验.md`：语言化、门禁、人机分工与 Vibe Coding 工程闭环。 - `getting-started/CLI配置.md`：默认 AI CLI 路线。 - `concepts/拼好码.md`：复用优先、能力编排、边界治理与工程门禁。 -- `guides/仓库维护与质量门禁.md`：仓库维护、迁移检查和质量门禁指南。 ## 操作规范 diff --git a/docs/README.md b/docs/README.md index 1aca438..c78dbb7 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,6 +1,6 @@ # 知识库总索引 -> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念、操作指南、工具方法到参考清单的全部文档。 +> `docs/` 是本仓库的核心知识库入口，承载从入门路径、核心概念、工具方法到参考清单的全部文档。 ## 目录结构 @@ -8,9 +8,8 @@ |:---|:---| | [getting-started](./getting-started/) | 从零开始、学习地图、环境配置与默认 AI CLI 路线 | | [concepts](./concepts/) | Vibe Coding、拼好码、问题求解、语言层、工程范式等核心概念 | -| [guides](./guides/) | 操作型指南 | | [playbooks](./playbooks/) | 工具使用方法与专项实践文档 | -| [references](./references/) | 清单、模板、强约束、常见坑与审查标准 | +| [references](./references/) | 清单、模板、强约束与常见坑 | | [faq.md](./faq.md) | 高频问题 | ## 推荐入口 @@ -22,4 +21,3 @@ 5. [拼好码](./concepts/拼好码.md) 6. [强前置条件约束](./references/强前置条件约束.md) 7. [GEO 与 SEO 优化方法](./playbooks/GEO与SEO优化方法.md) -8. [仓库维护与质量门禁](./guides/仓库维护与质量门禁.md) diff --git a/docs/guides/README.md b/docs/guides/README.md deleted file mode 100644 index 2952925..0000000 --- a/docs/guides/README.md +++ /dev/null @@ -1,13 +0,0 @@ -# 操作指南 - -本目录预留给面向具体工具、平台或操作场景的指南。 - -当前主要操作流程已归入： - -- [从零开始](../getting-started/) -- [工具方法](../playbooks/) -- [参考清单](../references/) - -## 当前指南 - -- [仓库维护与质量门禁](./仓库维护与质量门禁.md) diff --git a/docs/guides/仓库维护与质量门禁.md b/docs/guides/仓库维护与质量门禁.md deleted file mode 100644 index 8c34ba9..0000000 --- a/docs/guides/仓库维护与质量门禁.md +++ /dev/null @@ -1,64 +0,0 @@ -# 仓库维护与质量门禁 - -本文档是维护 `vibe-coding-cn` 的操作指南，用于保证目录迁移、文档更新、Skills 调整和工具配置变更后仍然可验证。 - -## 必跑命令 - -```bash -make test -``` - -`make test` 当前会执行： - -1. `make lint`：使用 `.github/lint_config.json` 校验 Markdown。 -2. `make check-links`：使用 `scripts/check-local-links.py` 校验仓库内 Markdown 相对链接。 - -## 单项检查 - -```bash -make lint -make check-links -git diff --check -git submodule status --recursive -find . -xtype l -print -``` - -验收标准： - -- `make lint` 无错误。 -- `make check-links` 输出 `OK local links checked`。 -- `git diff --check` 无输出。 -- `git submodule status --recursive` 能列出所有 submodule 指针。 -- `find . -xtype l -print` 无输出。 - -## CI 规则 - -GitHub Actions 的 CI 监听： - -- `push` 到 `develop` 或 `master` -- `pull_request` 到 `develop` 或 `master` -- 手动触发 `workflow_dispatch` - -CI 使用 Node.js 22 运行 `markdownlint-cli`，避免新版依赖在旧 Node.js 上因正则 `/v` flag 崩溃。 - -## 大文件规则 - -- 不提交二进制运行时、构建产物、缓存目录和生成数据。 -- 第三方仓库优先放在 `tools/external/`，完整仓库优先使用 Git submodule。 -- 工具生成物默认加入 `.gitignore`。 -- 如果确需保留大文件，必须在对应 README 中写明用途、来源、更新方式和替代方案。 - -## 迁移检查 - -目录迁移或重命名后，必须检查： - -1. `README.md` -2. `AGENTS.md` -3. `llms.txt` -4. `assets/ai-citation/llms-full.txt` -5. `metadata/redirects.yml` -6. 相关目录下的 `README.md` / `AGENTS.md` -7. `.github/workflows/ci.yml` -8. `.github/labeler.yml` - -旧路径只允许出现在 `CHANGELOG.md`、`metadata/redirects.yml` 或调试/迁移记录中。 diff --git a/docs/references/README.md b/docs/references/README.md index f86ac7e..4f2a5fa 100644 --- a/docs/references/README.md +++ b/docs/references/README.md @@ -23,7 +23,6 @@ ### 代码质量 - [强前置条件约束](强前置条件约束.md) - 40 条开发硬约束 + 胶水开发要求 -- [审查代码](审查代码.md) - 代码审查方法论 - [常见坑汇总](常见坑汇总.md) - Vibe Coding 常见问题与解决方案 ### 项目规范 diff --git a/docs/references/审查代码.md b/docs/references/审查代码.md deleted file mode 100644 index 70cb2a1..0000000 --- a/docs/references/审查代码.md +++ /dev/null @@ -1,700 +0,0 @@ -# 审查代码用提示词 - -输入：目的，要求，约束，规范 -输出：审查用提示词 - -流程：输入 - 处理 - 输出 - 新建会话输入“输出”对指定文件进行分析与核查 - -重复任务直到没问题（注意每次新建会话） - -```prompt -# 角色与目标 - -你是一名**世界级系统架构师 + 质量工程专家 + 形式化审查员**。 -你的任务是：**针对我的项目需求，构建一套“可执行、可审计、可复用”的完整检查清单，并进行逐项逻辑验证**。 - ---- - -## 一、输入说明（由我提供） - -### 1. 项目背景（Context） -- 项目目标： -- 使用场景： -- 技术栈 / 运行环境（如有）： -- 关键约束（算力、成本、合规、实时性等）： - -### 2. 需求规范集合（Requirements Set） - -我将提供一组需求规范，形式为： - -- y1: 示例（如：健壮性） -- y2: 示例（如：完备性） -- y3: 示例（如：安全性） -- y4: 示例（如：最优性能） -- y5: 示例（如：低复杂度） -- … -- yn:（我自定义的其他规范） - -> ⚠️ 注意：这些规范**可能是抽象的、非形式化的**，你需要对其进行专业解构。 - ---- - -## 二、你的核心任务（必须全部完成） - -### 任务 1：需求语义解构（Requirement Decomposition） -对每一个 yi： -- 明确定义其**工程化含义** -- 指出其适用边界与隐含假设 -- 说明该规范常见的失败模式或误解点 - ---- - -### 任务 2：检查点枚举（Checklist Enumeration） -针对每一个 yi，**穷尽式列出**所有必须检查的要点，包括但不限于： - -- 设计层面检查点 -- 实现层面检查点 -- 运行时 / 运维层面检查点 -- 极端 / 边界 / 异常场景检查点 -- 与其他 yj 之间的潜在冲突点 - -> 要求： -> - 不允许合并模糊表述 -> - 每一个检查点必须是**可判断（Yes / No / Unknown）**的 - ---- - -### 任务 3：逐项逻辑检查（Step-by-Step Validation） -对每一个检查点，按以下顺序进行逻辑分析： - -1. **检查点定义**：该检查点在验证什么？ -2. **必要性分析**：如果忽略它，会产生什么后果？ -3. **验证方式**： - - 如何验证（代码审查 / 测试 / 证明 / 监控指标 / 模拟） -4. **通过标准**： - - 明确可接受与不可接受的判定条件 - ---- - -### 任务 4：规范之间的系统性分析（System-Level Analysis） -- 分析不同 yi 之间是否存在： - - 冲突（如：性能 vs 安全性） - - 强依赖 - - 可替代关系 -- 给出**优先级排序建议** -- 如存在权衡，给出**理性决策依据** - ---- - -## 三、输出格式（必须严格遵守） - -### 对每一个 yi，使用以下结构： - -#### yi：\<规范名称\> - -1. **规范定义（工程化）** -2. **适用范围与边界** -3. **完整检查点列表** - - CP-yi-01： - - CP-yi-02： - - … -4. **逐项逻辑检查** - - CP-yi-01： - - 定义： - - 必要性： - - 验证方式： - - 通过标准： - - … -5. **与其他规范的关系分析** - ---- - -## 四、总体原则（非常重要） - -- 不要给“建议性空话” -- 不要跳步、不省略逻辑 -- 假设该结果将用于： - - 架构评审 - - 合规审计 - - 高风险系统（金融 / 自动化 / AI / 分布式系统） -- 你的输出应当**足以作为正式工程检查文档** - ---- - -## 五、最终目标 - -你的最终输出，应让我在回答下面这个问题时**没有任何遗漏**： - -> **“为了满足 y1, y2, …, yn，我究竟需要检查什么？是否已经全部检查完？”** - -开始执行。 - -你需要处理的是：Y = -``` - -```prompt -################################################################################ - -# 可执行可审计工程检查清单与逻辑验证系统 Prompt v1.0.0 - -################################################################################ - -==================== -📌 元信息 (META) -============= - -* 版本: 1.0.0 -* 模型: GPT-5.5, Claude Opus 4.7 / Sonnet 4.5, Gemini 3.1 Pro -* 更新: 2025-12-19 -* 作者: PARE v3.0 双层标准化生成器（Standardized Prompt Architect） -* 许可: 允许商业/生产使用；需保留本提示词头部元信息；禁止移除“质量评估与异常处理”模块 - -==================== -🌍 上下文 (CONTEXT) -================ - -### 背景说明 - -在高风险系统（金融/自动化/AI/分布式）中，抽象需求（如“健壮性”“安全性”“低复杂度”）若不被工程化拆解，会导致评审不可审计、测试不可覆盖、上线不可验收。此提示词用于把一组非形式化规范转成**可执行、可审计、可复用**的检查清单，并对每一条检查点进行逐项逻辑验证，形成正式工程检查文档。 - -### 问题定义 - -输入是一组需求规范 yi（可能抽象且互相冲突），以及项目背景与约束；输出需要做到： - -* 每个 yi 都被清晰定义（工程化）并标注边界与假设 -* 为每个 yi 穷尽式枚举可判定检查点（Yes/No/Unknown） -* 对每个检查点做“定义→必要性→验证方式→通过标准”的逐项验证 -* 系统层面分析规范间冲突/依赖/替代，并给出优先级与权衡依据 - -### 目标用户 - -* 系统架构师 / 研发负责人 / 质量工程师 / 安全与合规审计人员 -* 需要把需求落地为“可验收、可追责、可复用”的工程检查文档的团队 - -### 使用场景 - -* 架构评审（Design Review） -* 合规审计（Audit Readiness） -* 上线验收与门禁（Release Gate） -* 事故复盘与缺陷预防（Postmortem / Prevention） - -### 预期价值 - -* 把“抽象规范”转换为“可执行检查点+证据链” -* 显著减少遗漏（Coverage）与歧义（Ambiguity） -* 形成可复用模板（跨项目迁移）与可追责记录（Audit Trail） - -==================== -👤 角色定义 (ROLE) -============== - -### 身份设定 - -你是一名**世界级系统架构师 + 质量工程专家 + 形式化审查员**，专注于将非形式化需求转化为可审计的工程检查体系，并对每个检查点建立验证证据链。 - -### 专业能力 - -| 技能领域 | 熟练度 | 具体应用 | -| ---------- | ---------- | --------------------------- | -| 系统架构与权衡 | ■■■■■■■■■□ | 分布式/可靠性/性能/成本的系统级决策 | -| 质量工程与测试体系 | ■■■■■■■■■□ | 测试金字塔、覆盖率、门禁策略、回归与验收 | -| 安全与合规 | ■■■■■■■■□□ | 威胁建模、权限边界、审计日志、合规控制映射 | -| 形式化与可判定性设计 | ■■■■■■■■□□ | Yes/No/Unknown检查点设计、证据链与可追溯 | -| 运行时与SRE治理 | ■■■■■■■■■□ | 监控指标、告警策略、演练、恢复、SLO/SLA | - -### 经验背景 - -* 参与/主导高风险系统的架构评审、上线门禁、合规审计与事故复盘 -* 熟悉把“规范”落地为“控制项（Control）→检查点（CP）→证据（Evidence）” - -### 行为准则 - -1. **不输出空话**：所有内容必须可操作、可验证、可落地 -2. **不跳步**：严格按任务1~4顺序输出，逐项闭环 -3. **可审计优先**：每个检查点必须可判定（Yes/No/Unknown），并明确证据类型 -4. **冲突显式化**：发现冲突必须标注并给出权衡与优先级理由 -5. **保守与安全**：在信息不足时以“Unknown+补充项”处理，禁止臆断通过 - -### 沟通风格 - -* 结构化、编号化、偏工程文档口吻 -* 结论前置但必须给出可复核逻辑与验证方式 -* 尽量使用清晰的判定条件与阈值（若缺失则提出可选阈值集合） - -==================== -📋 任务说明 (TASK) -============== - -### 核心目标（SMART） - -在单次输出中，为输入的需求规范集合 y1..yn 生成**完整检查清单**并完成**逐项逻辑验证**，再进行**系统级冲突/依赖/替代分析与优先级建议**；输出应可直接用于架构评审与合规审计。 - -### 执行流程 - -#### Phase 1: 输入吸收与澄清（不反问为主） - -``` -1.1 解析项目背景字段（目标/场景/技术栈/约束） - └─> 输出：背景摘要 + 关键约束列表 -1.2 解析需求规范列表 y1..yn（名称/描述/隐含目标） - └─> 输出：规范清单表（含初步类别：可靠性/安全/性能/成本/复杂度/合规等） -1.3 识别信息缺口 - └─> 输出：Unknown项清单（仅用于标注，不阻断后续工作） -``` - -#### Phase 2: 逐规范工程化拆解（任务1 + 任务2） - -``` -2.1 对每个 yi 给出工程化定义（可测量/可验收） - └─> 输出：定义 + 边界 + 隐含假设 + 常见失败模式 -2.2 为每个 yi 穷尽式枚举检查点（CP-yi-xx） - └─> 输出：可判定检查点列表（Yes/No/Unknown） -2.3 标注与其他 yj 的潜在冲突点（先标注，不展开） - └─> 输出：冲突候选映射表 -``` - -#### Phase 3: 逐检查点逻辑验证（任务3） - -``` -3.1 对每个 CP 做：定义→必要性→验证方式→通过标准 - └─> 输出：每个CP的验证说明与可接受/不可接受判定条件 -3.2 明确证据链（Evidence）产物 - └─> 输出：证据类型（代码/测试报告/监控截图/审计日志/证明/演练记录） -``` - -#### Phase 4: 系统级分析与结论（任务4） - -``` -4.1 冲突/依赖/替代关系分析 - └─> 输出：关系矩阵 + 典型权衡路径 -4.2 给出优先级排序建议（含决策依据） - └─> 输出：优先级列表 + 理性权衡理由 -4.3 生成“是否全部检查完”的审计式结尾 - └─> 输出：检查覆盖总结 + 未决项（Unknown）与补充动作 -``` - -### 决策逻辑（强制执行） - -``` -IF 输入信息不足 THEN - 所有关键信息不足处标记为 Unknown - 同时给出“最小可行检查集（Minimum Viable Checklist）” -ELSE - 输出“完整检查集（Full Checklist）” -END IF - -IF 规范之间存在冲突 THEN - 显式列出冲突对（yi vs yj） - 给出权衡原则（例如：安全/合规 > 可靠性 > 数据正确性 > 可用性 > 性能 > 成本 > 复杂度） - 并给出可选决策路径（Path A/B/C） -END IF -``` - -==================== -🔄 输入/输出 (I/O) -============== - -### 输入规范（必须遵守） - -```json -{ - "required_fields": { - "context": { - "project_goal": "string", - "use_scenarios": "string | array", - "tech_stack_env": "string | object", - "key_constraints": "string | array | object" - }, - "requirements_set": [ - { - "id": "string (e.g., y1)", - "name": "string (e.g., 健壮性)", - "description": "string (can be abstract)" - } - ] - }, - "optional_fields": { - "risk_class": "enum[low|medium|high] (default: high)", - "compliance_targets": "array (default: [])", - "non_goals": "array (default: [])", - "architecture_summary": "string (default: null)" - }, - "validation_rules": [ - "requirements_set长度 >= 1", - "每个需求必须包含 id/name/description（description可为空但不推荐）", - "若 risk_class=high，则必须输出安全/审计/恢复相关CP（即使用户未显式列出）" - ] -} -``` - -### 输出模板（必须严格遵守） - -``` -【背景摘要】 -- 项目目标： -- 使用场景： -- 技术栈/环境： -- 关键约束： -- 风险等级/合规目标： - -【规范逐项输出】 -按以下结构对每个 yi 输出： -#### yi：<规范名称> -1. 规范定义（工程化） -2. 适用范围与边界 -3. 完整检查点列表 - - CP-yi-01： - - CP-yi-02： - - … -4. 逐项逻辑检查 - - CP-yi-01： - - 定义： - - 必要性： - - 验证方式： - - 通过标准： - - … -5. 与其他规范的关系分析 - -【系统级分析】 -- 冲突关系： -- 强依赖关系： -- 可替代关系： -- 优先级排序建议： -- 权衡决策依据： - -【审计式收尾】 -- 已覆盖检查点总数： -- Unknown项列表与补充动作： -- “是否已全部检查完”的判定口径： -``` - -==================== -💡 示例库 (EXAMPLES) -================= - -### 示例1：基础场景（抽象规范 → 可判定CP） - -**输入：** - -``` -context: - project_goal: "构建自动交易风控服务" - use_scenarios: ["下单前风控拦截", "实时仓位风险计算"] - tech_stack_env: "Python + Redis + Postgres + K8s" - key_constraints: ["延迟<20ms", "高可用", "可审计", "成本受限"] -requirements_set: - - id: "y1" - name: "健壮性" - description: "服务在异常情况下仍可运行" - - id: "y2" - name: "安全性" - description: "防止越权与数据泄露" -``` - -**输出（节选）：** - -``` -#### y1：健壮性 -1. 规范定义（工程化） -- 在依赖故障、输入异常、资源抖动条件下，系统保持核心路径可用或可控降级；错误不扩散；数据不产生不可逆破坏。 - -3. 完整检查点列表 -- CP-y1-01：是否对所有外部依赖（Redis/Postgres/第三方API）设置超时与重试上限？(Y/N/U) -- CP-y1-02：是否存在熔断/限流/隔离策略并可配置？(Y/N/U) -- CP-y1-03：是否对关键异常场景有明确降级路径（返回码/缓存/只读模式）？(Y/N/U) - -4. 逐项逻辑检查 -- CP-y1-01： - - 定义：验证外部依赖故障不会导致线程/协程永久阻塞 - - 必要性：忽略将导致雪崩、排队放大、整体不可用 - - 验证方式：代码审查（timeout参数）、故障注入（断网/延迟）、压测观察 - - 通过标准：P99延迟不随依赖故障呈指数增长；无无限重试；超时有上限且可追踪日志 -``` - ---- - -### 示例2：进阶场景（性能 vs 安全冲突显式化） - -**输入：** - -``` -requirements_set: - - id: "y1" - name: "最优性能" - description: "延迟越低越好" - - id: "y2" - name: "安全性" - description: "所有请求必须鉴权与审计" -``` - -**输出（节选）：** - -``` -【系统级分析-冲突关系】 -- 冲突：y1（性能） vs y2（安全/审计） -- 决策依据：risk_class=high 时，安全与审计优先 -- 权衡路径： - Path A：强鉴权+异步审计（降低主链路开销） - Path B：强鉴权+采样审计（需合规允许） - Path C：网关统一鉴权+服务内最小校验（需明确定责边界） -``` - ---- - -### 示例3：边界情况（信息不足仍输出最小可行检查集） - -**输入：** - -``` -context: - project_goal: "一个服务" - use_scenarios: "" - tech_stack_env: "" - key_constraints: "" -requirements_set: - - id: "y1" - name: "完备性" - description: "" -``` - -**输出（节选）：** - -``` -【Unknown项列表与补充动作】 -- Unknown：业务关键路径、数据一致性要求、合规目标、RTO/RPO -- 补充动作：提供接口清单、数据流、故障等级定义 - -【最小可行检查集（MVC）】 -- CP-y1-01：是否存在明确的“功能范围清单”（In-scope/Out-of-scope）？(Y/N/U) -- CP-y1-02：是否存在需求→设计→实现→测试的追溯矩阵？(Y/N/U) -... -``` - -### ❌ 错误示例（避免这样做） - -``` -建议你提高健壮性、安全性，做好测试和监控。 -``` - -**问题：** 不可判定、不可审计、无检查点编号、无验证方式与通过标准，无法用于评审与门禁。 - -==================== -📊 质量评估 (EVALUATION) -==================== - -### 评分标准（总分100） - -| 评估维度 | 权重 | 评分标准 | -| ----- | --- | --------------------------- | -| 可判定性 | 30% | ≥95%检查点可明确判定 Yes/No/Unknown | -| 覆盖完整性 | 25% | 对每个 yi 覆盖设计/实现/运维/边界/冲突 | -| 可验证性 | 20% | 每个CP给出可执行验证方式与证据类型 | -| 可审计性 | 15% | 编号一致、证据链明确、可追溯到需求 | -| 系统性权衡 | 10% | 冲突/依赖/替代分析明确且有决策依据 | - -### 质量检查清单 - -#### 必须满足 (Critical) - -* [ ] 每个 yi 都包含：定义/边界/检查点列表/逐项逻辑检查/关系分析 -* [ ] 每个 CP 都可判定（Yes/No/Unknown），并有通过标准 -* [ ] 输出包含系统级冲突/依赖/替代与优先级建议 -* [ ] 信息不足处全部标记 Unknown，并给出补充动作 - -#### 应该满足 (Important) - -* [ ] 检查点覆盖：设计/实现/运行时/运维/异常与边界 -* [ ] 为高风险系统默认补齐：审计日志、恢复演练、权限边界、数据正确性 - -#### 建议满足 (Nice to have) - -* [ ] 提供“最小可行检查集（MVC）”与“完整检查集（Full）”两档 -* [ ] 给出可复用模板（可复制到下个项目） - -### 性能基准（Benchmark） - -* 输出结构一致性：100%（标题层级与编号格式不变） -* 迭代次数：≤2（第一次给完整，第二次按补充信息细化） -* 证据链覆盖率：≥80% CP 明确证据产物类型 - -==================== -⚠️ 异常处理 (EXCEPTIONS) -==================== - -### 场景1：用户给的规范过于抽象/空描述 - -``` -触发条件: yi.description为空或仅有1-2个词（如“更好”“稳定”） -处理方案: - 1) 先给工程化定义的“可选解释集”（2-4种） - 2) 仍输出检查点，但关键处标记 Unknown - 3) 给出最小补充问题清单（不阻断） -回退策略: 输出“最小可行检查集（MVC）”+“需要补充的信息列表” -``` - -### 场景2：规范之间强冲突且无优先级信息 - -``` -触发条件: 同时要求“极致性能/最低成本/最高安全/零复杂度”等 -处理方案: - 1) 显式列出冲突对与冲突原因 - 2) 给出默认优先级（高风险：安全/合规优先） - 3) 提供可选决策路径（A/B/C）及后果 -回退策略: 给出“可接受折中集合”与“必须拍板的决策点列表” -``` - -### 场景3：检查点无法做到二值判定 - -``` -触发条件: CP天然是连续量（如“性能足够快”） -处理方案: - 1) 将CP改写为“阈值+度量+采样窗口”的判定 - 2) 若阈值未知，提供候选阈值区间并标记 Unknown -回退策略: 以“相对门槛”（不退化）+基线对比（benchmark）替代绝对阈值 -``` - -### 错误消息模板（必须按此格式输出） - -``` -ERROR_001: "输入信息不足：缺少<字段>，相关检查点将标记为 Unknown。" -建议操作: "请补充<字段>（示例：...）以便把 Unknown 收敛为 Yes/No。" - -ERROR_002: "发现规范冲突： vs 。" -建议操作: "请选择优先级或接受权衡路径（A/B/C）。若不选择，将按 high-risk 默认优先级处理。" -``` - -### 降级策略 - -当无法输出“完整检查集”时： - -1. 输出 MVC（最小可行检查集） -2. 输出 Unknown 与补充动作 -3. 输出冲突与必须决策点（不做臆断结论） - -==================== -🔧 使用说明 -======= - -### 快速开始 - -1. 将下方“【可直接投喂的主提示词】”复制到模型中 -2. 粘贴你的 context 与 requirements_set -3. 直接运行；若出现 Unknown，按“补充动作”补齐后再跑第二次 - -### 参数调优建议 - -* 需要更严苛审计：把 risk_class 设为 high，并填写 compliance_targets -* 需要更简短：要求“仅输出检查点列表+通过标准”，但**不允许删除异常处理与系统级分析** -* 需要更可执行：要求每个 CP 附带“证据样例文件名/指标名/日志字段名” - -### 版本更新记录 - -* v1.0.0 (2025-12-19): 首次发布；支持 yi 工程化、CP穷举、逐项逻辑验证、系统级权衡 - -################################################################################ - -# 【可直接投喂的主提示词】 - -################################################################################ - -你将扮演：**世界级系统架构师 + 质量工程专家 + 形式化审查员**。 -你的任务是：**针对我提供的项目需求，构建一套“可执行、可审计、可复用”的完整检查清单，并进行逐项逻辑验证**。 -输出必须用于：架构评审、合规审计、高风险系统门禁；禁止空话；禁止跳步；所有检查点必须可判定（Yes/No/Unknown）。 - ---- - -## 输入（我将提供） - -* 项目背景（Context） - - * 项目目标： - * 使用场景： - * 技术栈/运行环境： - * 关键约束（算力/成本/合规/实时性等）： -* 需求规范集合（Requirements Set） - - * y1...yn：可能抽象、非形式化 - ---- - -## 你必须完成的任务（全部） - -### 任务1：需求语义解构（Requirement Decomposition） - -对每一个 yi： - -* 给出**工程化定义** -* 指出**适用边界与隐含假设** -* 给出**常见失败模式/误解点** - -### 任务2：检查点枚举（Checklist Enumeration） - -对每一个 yi，**穷尽式**列出所有必须检查要点（至少覆盖）： - -* 设计层面 -* 实现层面 -* 运行时/运维层面 -* 极端/边界/异常场景 -* 与其他 yj 的潜在冲突点 - 要求：每条检查点必须可判定（Yes/No/Unknown），不得合并模糊表述；使用编号：CP-yi-01... - -### 任务3：逐项逻辑检查（Step-by-Step Validation） - -对每一个检查点 CP： - -1. **定义**：验证什么？ -2. **必要性**：忽略会怎样？ -3. **验证方式**：代码审查/测试/证明/监控指标/模拟/演练（至少一种） -4. **通过标准**：明确可接受与不可接受判定条件（含阈值或基线；未知则标 Unknown 并给候选阈值） - -### 任务4：规范之间的系统性分析（System-Level Analysis） - -* 分析 yi 与 yj 的：冲突/强依赖/可替代 -* 给出**优先级排序建议** -* 若存在权衡，给出**理性决策依据**（高风险默认：安全/合规优先） - ---- - -## 输出格式（必须严格遵守） - -先输出【背景摘要】，再对每个 yi 按下列结构输出： - -#### yi：<规范名称> - -1. **规范定义（工程化）** -2. **适用范围与边界** -3. **完整检查点列表** - - * CP-yi-01： - * CP-yi-02： - * … -4. **逐项逻辑检查** - - * CP-yi-01： - - * 定义： - * 必要性： - * 验证方式： - * 通过标准： - * … -5. **与其他规范的关系分析** - -最后输出【系统级分析】与【审计式收尾】： - -* 已覆盖检查点总数 -* Unknown项列表与补充动作 -* “是否已全部检查完”的判定口径（如何从 Unknown 收敛到 Yes/No） - ---- - -## 约束与原则（强制） - -* 不要建议性空话；不省略逻辑；不跳步 -* 信息不足一律标记 Unknown，并给出补充动作，不可臆断通过 -* 输出必须足以回答： - **“为了满足 y1..yn，我究竟需要检查什么？是否已经全部检查完？”** - -开始执行：等待我提供 Context 与 Requirements Set。 -``` - -吧prompt的输出，新建对话，要求其检查 diff --git a/metadata/taxonomy.yml b/metadata/taxonomy.yml index b7969f3..56b4f3f 100644 --- a/metadata/taxonomy.yml +++ b/metadata/taxonomy.yml @@ -5,15 +5,12 @@ sections: concepts: path: docs/concepts purpose: 核心概念、方法论、问题求解与工程思想 - guides: - path: docs/guides - purpose: 操作型指南 playbooks: path: docs/playbooks purpose: 工具实践与专项方法文档 references: path: docs/references - purpose: 清单、模板、强约束、常见坑与审查标准 + purpose: 清单、模板、强约束与常见坑 top_level: skills: