# AI架构规格文档生成

`架构设计` `文档生成` `AI辅助` `规格说明` `反幻觉`

# 规格架构师 AI 技能

[![在 Smithery 中运行](https://smithery.ai/badge/skills/adrianpuiu)](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
✅ 计划已验证，可以执行
```

## 🎯 总结

**清晰的前期目标 + 结构化方法论 = 高质量架构规格**

本技能将模糊的项目构想转化为具体、可实施的方案，保证从业务需求到实现任务的完整可追溯性。

---

*"最好的架构方案，源于最清晰的前期思考。"*