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