238 lines
8.6 KiB
Markdown
238 lines
8.6 KiB
Markdown
# AI架构规格文档生成
|
||
|
||
`架构设计` `文档生成` `AI辅助` `规格说明` `反幻觉`
|
||
|
||
# 规格架构师 AI 技能
|
||
|
||
[](https://smithery.ai/skills?ns=adrianpuiu&utm_source=github&utm_medium=badge)
|
||
|
||
## 📦 安装
|
||
|
||
### 前置条件
|
||
|
||
- 已安装并运行 [Claude Code](https://docs.claude.com/en/docs/claude-code)
|
||
|
||
### 快速开始（选择你的方式）
|
||
|
||
**方式一：使用 Claude Code 聊天界面**
|
||
|
||
在 Claude Code 的对话框中运行以下命令：
|
||
|
||
```
|
||
/plugin marketplace add adrianpuiu/specification-document-generator
|
||
/plugin install architecture-skills@specification-document-generator
|
||
```
|
||
|
||
**方式二：使用终端/CLI**
|
||
|
||
在终端中运行：
|
||
|
||
```bash
|
||
claude plugin marketplace add adrianpuiu/specification-document-generator
|
||
claude plugin install architecture-skills@specification-document-generator
|
||
```
|
||
|
||
**这些命令的作用：**
|
||
- Claude Code 从本 GitHub 仓库获取 `.claude-plugin/marketplace.json`
|
||
- 发现 `architecture-skills` 插件（包含 `specification-architect` 技能）
|
||
- 安装插件并在当前会话中启用所有技能
|
||
|
||
### 其他安装方式
|
||
|
||
**方式二：从中央技能市场安装**
|
||
|
||
Claude Code 聊天：
|
||
```
|
||
/plugin marketplace add adrianpuiu/claude-skills-marketplace
|
||
/plugin install architecture-skills@claude-skills-marketplace
|
||
```
|
||
|
||
终端：
|
||
```bash
|
||
claude plugin marketplace add adrianpuiu/claude-skills-marketplace
|
||
claude plugin install architecture-skills@claude-skills-marketplace
|
||
```
|
||
|
||
**方式三：本地开发安装**
|
||
|
||
克隆仓库：
|
||
```bash
|
||
git clone https://github.com/adrianpuiu/specification-document-generator.git
|
||
cd specification-document-generator
|
||
```
|
||
|
||
通过 CLI 安装：
|
||
```bash
|
||
claude plugin marketplace add adrianpuiu/specification-document-generator
|
||
claude plugin install architecture-skills@specification-document-generator
|
||
```
|
||
|
||
或通过 Claude Code 聊天：
|
||
```
|
||
/plugin marketplace add /absolute/path/to/specification-document-generator
|
||
/plugin install architecture-skills@specification-document-generator
|
||
```
|
||
|
||
### 验证安装
|
||
|
||
**Claude Code 聊天：**
|
||
```
|
||
/plugin list
|
||
```
|
||
|
||
**终端：**
|
||
```bash
|
||
claude plugin list
|
||
```
|
||
|
||
已安装插件列表中应出现 `architecture-skills`。
|
||
|
||
### 使用技能
|
||
|
||
安装完成后，即可在 Claude Code 中使用 `specification-architect` 技能。只需提供项目需求，该技能将引导你完成六阶段文档生成流程。
|
||
|
||
## 概述
|
||
|
||
这是一套严格的、基于证据的系统，可生成六份相互关联的架构文档，同时**消除"研究糟粕"**，防止 AI 生成错误信息。每项技术决策均有可验证的来源支撑，从研究到实现全程可追溯。
|
||
|
||
## 🚨 关键：防止"研究糟粕"
|
||
|
||
**问题所在**：AI 生成的内容往往措辞精练、言之凿凿，令人产生"盲目信任"，但却常常未经核实、存在事实错误。这已导致：
|
||
- 律师事务所因提交伪造引用而**受到法律制裁**
|
||
- 咨询公司因提供错误统计数据而**被处以经济处罚**
|
||
- 依赖似是而非的谎言导致**职业生涯毁于一旦**
|
||
|
||
**我们的解决方案**：**强制验证协议**，将 AI 从"自信的作者"转变为"勤勉的研究助手"，并留下可审计的证据链。
|
||
|
||
## 🎯 基于证据的架构
|
||
|
||
**架构规格的质量与研究证据的可验证性直接挂钩。**
|
||
|
||
### 本技能的功能
|
||
|
||
1. **阶段 0**：🔍 **可验证研究**（强制网络搜索 + 浏览 + 引用）
|
||
2. **阶段 1**：架构蓝图（基于证据的组件映射）
|
||
3. **阶段 2**：需求生成（基于研究的验收标准）
|
||
4. **阶段 3**：详细设计（经来源验证的规格说明）
|
||
5. **阶段 4**：任务分解（可追溯的实施计划）
|
||
6. **阶段 5**：验证与可追溯性（100% 覆盖率 + 证据验证）
|
||
|
||
## 🚀 示例：清晰输入 = 清晰输出
|
||
|
||
### 用户提示（高质量）：
|
||
```
|
||
"我需要为一家成长中的电商企业设计一套库存管理系统。
|
||
系统必须支持 50,000 个 SKU，与现有的 Shopify 商店集成，
|
||
并提供实时库存更新。需要条形码扫描、低库存预警和供应商管理。
|
||
请不要包含 POS 功能或面向客户的功能。
|
||
我们团队使用 Node.js/React，需要云端部署并支持自动备份。"
|
||
```
|
||
|
||
### 此提示提供了什么：
|
||
✅ **清晰的业务背景**：电商库存管理
|
||
✅ **具体约束条件**：50,000 个 SKU、Shopify 集成、实时更新
|
||
✅ **技术栈**：Node.js/React、云端部署
|
||
✅ **明确的范围边界**：无 POS、无面向客户的功能
|
||
✅ **成功指标**：条形码扫描、库存预警、供应商管理
|
||
|
||
### 最终架构质量：
|
||
🎯 **清晰的组件边界**：每个服务职责单一
|
||
🎯 **明确的数据流**：从条形码扫描到库存更新的完整链路
|
||
🎯 **定义好的集成点**：Shopify API、备份系统、云基础设施
|
||
🎯 **可追溯的需求**：每个功能均追溯到具体实现任务
|
||
🎯 **无范围蔓延**：清晰边界防止"功能叠加"
|
||
|
||
## 📋 生成的文档
|
||
|
||
1. **research.md** - 网络搜索结果、技术对比、技术栈选型（新增！）
|
||
2. **blueprint.md** - 组件映射、数据流图、集成点
|
||
3. **requirements.md** - 带组件分配的可测试验收标准
|
||
4. **design.md** - 详细组件规格与接口说明
|
||
5. **tasks.md** - 带需求追溯的实施计划
|
||
6. **validation.md** - 自动验证，确认 100% 覆盖率
|
||
|
||
## ✨ 核心特性
|
||
|
||
- **🚫 防研究糟粕**：强制验证消除 AI 生成的错误信息
|
||
- **🔍 基于证据的研究**：每项声明均有浏览来源和引用支撑
|
||
- **📋 引用协议**：严格的 `[cite:INDEX]` 格式构建可审计的证据链
|
||
- **🛡️ 专业标准**：防止法律制裁、经济处罚和职业风险
|
||
- **自动验证**：Python 脚本确保 100% 需求覆盖率 + 证据验证
|
||
- **来源核实**：强制浏览原始来源，而非仅查看搜索摘要
|
||
- **模板强制**：保证一致性与完整性
|
||
- **组件一致性**：所有文档中精确匹配组件名称
|
||
- **可追溯性矩阵**：从需求到任务的完整映射
|
||
- **质量门控**：带证据验证的顺序审批流程
|
||
|
||
## 🔍 阶段 0：可验证研究——反糟粕协议
|
||
|
||
**关键**：本阶段专门防止导致法律制裁和职业风险的 AI 错误类型。
|
||
|
||
### 强制验证流程：
|
||
1. **先搜索后浏览**：用 WebSearch 找到来源，再用 WebFetch 读取实际内容
|
||
2. **不得仅用搜索摘要**：必须阅读完整来源内容，而非仅看搜索结果
|
||
3. **为每项声明引用**：每条事实陈述必须以 `[cite:INDEX]` 引用结尾
|
||
4. **基于证据的决策**：技术选型只来自经过验证的来源
|
||
5. **可审计的链路**：从声明到来源的完整引用链
|
||
|
||
### 我们防止的错误示例：
|
||
❌ **研究糟粕**："Node.js 非常适合实时应用"
|
||
✅ **基于证据**："Node.js 凭借其事件驱动、非阻塞 I/O 模型在实时应用中表现出色 [cite:1]"
|
||
|
||
❌ **研究糟粕**："TypeScript 减少错误"
|
||
✅ **基于证据**："TypeScript 通过添加静态类型，可将大型代码库的运行时错误减少约 15% [cite:2]"
|
||
|
||
### 专业影响：
|
||
本协议防止以下类型的错误：
|
||
- 律师事务所的**法律制裁**（伪造引用）
|
||
- 咨询公司的**经济处罚**（错误统计数据）
|
||
- AI 生成错误信息导致的**职业毁损**
|
||
|
||
## 🎖️ 关键成功因素
|
||
|
||
### 1. 以研究驱动决策
|
||
不要跳过阶段 0！网络研究确保：
|
||
- 当前最佳实践和模式
|
||
- 经过验证的技术栈
|
||
- 特定行业的考量
|
||
- 避免使用过时的方案
|
||
|
||
### 2. 组件清晰度
|
||
每个组件必须有单一、明确的职责。如果你发现自己说"同时还……"，请拆分为多个组件。
|
||
|
||
### 2. 数据流可视化
|
||
绘制数据从输入到输出在系统中的流转路径。Mermaid 图应展示完整的数据旅程。
|
||
|
||
### 3. 集成点
|
||
清晰定义所有 API、协议和外部系统连接，明确数据格式、认证方式和错误处理。
|
||
|
||
### 4. 边界设定
|
||
明确定义范围内与范围外的内容，以防止范围蔓延并实现准确估算。
|
||
|
||
## 🔧 使用方法
|
||
|
||
1. **提供清晰需求**：包括业务目标、约束条件和范围边界
|
||
2. **按序执行各阶段**：每个阶段在前一阶段基础上构建
|
||
3. **检查质量门控**：确保每个阶段满足质量标准后再推进
|
||
4. **验证可追溯性**：使用自动验证器确认完整覆盖率
|
||
|
||
## 📊 验证示例
|
||
|
||
```
|
||
验证报告：
|
||
- 验收标准总数：28
|
||
- 被任务覆盖的标准数：28
|
||
- 覆盖率：100%
|
||
- 无效引用：0
|
||
✅ 计划已验证，可以执行
|
||
```
|
||
|
||
## 🎯 总结
|
||
|
||
**清晰的前期目标 + 结构化方法论 = 高质量架构规格**
|
||
|
||
本技能将模糊的项目构想转化为具体、可实施的方案，保证从业务需求到实现任务的完整可追溯性。
|
||
|
||
---
|
||
|
||
*"最好的架构方案，源于最清晰的前期思考。"* |