devspec

v1.0.3

Published

4 months ago

AI-native system for spec-driven development

Downloads

0High
0Medium
0Low

charlie2022

devspec specs cli ai development

DevSpec

AI-native system for spec-driven development

DevSpec是一个专为AI助手设计的规格驱动开发系统，旨在通过结构化的规范文档来指导和管理软件开发过程。它提供了一套完整的CLI工具，帮助开发者和AI助手以规范化的方式创建、管理和跟踪项目变更。

注意：除了init外，其它都都必须在Agent中使用，不要直接使用command命令

DevSpec Dashboard

✨ 特性

🎯 规格驱动开发 - 通过结构化的规范文档管理项目变更
🤖 AI原生设计 - 专为AI助手优化的开发工作流
📋 变更管理 - 完整的提案、验证和实现跟踪系统
🔄 文档同步 - 自动维护项目文档的一致性
🛠️ 强大的CLI - 直观易用的命令行工具
📊 实时状态跟踪 - 可视化的项目进展监控
🔍 规范验证 - 自动检查文档结构和内容完整性
🏗️ 架构指导 - 为不同类型的项目提供架构最佳实践

🚀 快速开始

安装

使用npm全局安装DevSpec：

npm install -g devspec

或使用pnpm（推荐）：

pnpm add -g devspec

基本使用

初始化项目

devspec init

创建变更提案

devspec plan

扩展提案内容

devspec expand <proposal-id>

生成技术设计

devspec design <proposal-id>

验证提案

devspec validate <proposal-id>

📚 核心概念

变更提案 (Change Proposals)

变更提案是DevSpec的核心单位，用于描述项目中的任何变更：

需求描述 - 明确说明变更的目的和范围
验收标准 - 定义变更完成的具体条件
影响分析 - 评估变更对现有系统的影响
实现计划 - 提供具体的实施步骤

设计文档 (Design Documents)

根据变更类型，DevSpec支持多种设计文档：

API设计 - 新增或修改API接口
数据库设计 - 数据库模式和迁移策略
架构设计 - 系统架构和技术选型
通用设计 - 其他技术实现方案

规范格式 (Spec Format)

DevSpec使用结构化的Markdown格式编写规范：

## ADDED Requirements
### Requirement: 功能的简要描述
变更的详细描述，包括背景、目标和范围。

#### Scenario: 场景名称
- **GIVEN** 初始条件
- **WHEN** 执行操作
- **THEN** 期望结果

🛠️ 命令参考

`devspec init`

初始化一个新的DevSpec项目：

devspec init [project-name]

创建项目结构并设置基本的配置文件。

`devspec plan`

生成项目需求和变更提案：

# 交互式模式
devspec plan

# 从文件加载需求
devspec plan --from-file requirements.md

# 从文本加载需求  
devspec plan --from-text "你的需求描述"

`devspec expand`

扩展现有提案的详细内容：

# 交互式选择
devspec expand

# 指定提案ID
devspec expand <proposal-id>

`devspec design`

为提案生成技术设计文档：

# 交互式模式
devspec design

# 指定设计类型
devspec design <proposal-id> --type api|database|architecture

# 非交互模式
devspec design <proposal-id> --type general --no-interactive

`devspec validate`

验证提案和规范的结构完整性：

# 验证指定提案
devspec validate <proposal-id>

# 验证所有提案
devspec validate

# JSON输出格式
devspec validate <proposal-id> --json

`devspec show`

显示提案的详细信息：

# 显示基本信息和摘要
devspec show <proposal-id>

# 显示完整内容
devspec show <proposal-id> --full

# JSON格式输出
devspec show <proposal-id> --json

# 仅显示变更
devspec show <proposal-id> --deltas-only

`devspec change`

管理变更生命周期：

# 创建新变更
devspec change add <name>

# 显示变更状态
devspec change show <name>

# 验证变更
devspec change validate <name>

# 归档完成变更
devspec change archive <name>

`devspec list`

列出项目中的所有提案和变更：

# 列出所有变更
devspec list

# 按状态过滤
devspec list --status active|completed|archived

# JSON格式输出
devspec list --json

`devspec spec`

管理项目规范：

# 创建新规范
devspec spec add <capability-name>

# 验证所有规范
devspec spec validate

# 显示规范详情
devspec spec show <capability-name>

`devspec docs`

文档同步和管理：

# 同步README.md
devspec docs sync

# 创建文档结构
devspec docs init

# 生成API文档
devspec docs api

# 导出为JSON
devspec docs export

`devspec update`

更新项目信息和配置：

# 更新项目信息
devspec update

# 更新配置
devspec update config

# 刷新模板
devspec update templates

`devspec view`

视图操作辅助工具：

# 以树形结构显示项目
devspec view tree

# 显示统计信息
devspec view stats

# 导出报告
devspec view export --format pdf|html|json

`devspec archive`

归档管理工具：

# 归档变更
devspec archive <proposal-id>

# 批量归档
devspec archive --status completed

# 恢复归档
devspec archive restore <archive-id>

📁 项目结构

DevSpec项目具有以下标准目录结构：

your-project/
├── devspec/                    # DevSpec核心目录
│   ├── changes/               # 变更提案
│   │   ├── <proposal-id>/
│   │   │   ├── proposal.md    # 提案文档
│   │   │   ├── tasks.md       # 任务列表
│   │   │   ├── design.md      # 设计文档
│   │   │   └── specs/         # 相关规范
│   │   └── archive/           # 已归档变更
│   ├── specs/                 # 项目规范
│   │   └── <capability>/
│   │       └── spec.md        # 规范文档
│   ├── project.md            # 项目信息
│   └── AGENTS.md             # AI助手指导
├── docs/                     # 文档目录
│   ├── README.md             # 自动生成的文档索引
│   ├── api/                  # API文档
│   ├── guides/               # 用户指南
│   └── tutorials/            # 教程
├── requirements.txt          # 项目需求文档
└── package.json              # 项目配置

🏗️ 架构设计

核心组件

CLI接口层 - 处理用户交互和命令解析
命令处理器 - 执行具体的业务逻辑
文档解析器 - 解析和管理规范文档
验证引擎 - 检查文档结构完整性
同步服务 - 维护文档一致性
模板系统 - 提供文档模板和最佳实践

技术栈

运行时: Node.js (>=20.19.0)
语言: TypeScript 5.9.3
CLI框架: Commander.js
输入处理: @inquirer
验证: Zod
构建: 自定义构建系统
测试: Vitest
版本管理: Changesets

🤝 贡献指南

我们欢迎所有形式的贡献！

贡献类型

🐛 Bug修复 - 报告和修复问题
✨ 新功能 - 提出和实现新特性
📝 文档改进 - 完善用户文档和注释
🎨 用户体验 - 改进界面和交互
⚡ 性能优化 - 提升系统性能
🔒 安全修复 - 修复安全漏洞

开发规范

代码风格 - 遵循TypeScript最佳实践
提交信息 - 使用语义化提交格式
测试覆盖 - 新功能需包含测试用例
文档更新 - 相关文档同步更新
向后兼容 - 保持API向后兼容

提交规范

使用changesets管理版本发布：

# 添加变更
pnpm changeset

# 版本发布
pnpm run release:ci

📖 使用案例

案例1: 新功能开发

# 1. 初始化项目
devspec init my-app

# 2. 创建需求提案
devspec plan --from-file requirements.md

# 3. 扩展提案细节
devspec expand user-authentication

# 4. 生成API设计
devspec design user-authentication --type api

# 5. 验证完整性
devspec validate user-authentication

# 6. 查看实现计划
devspec show user-authentication

案例2: 架构改进

# 1. 创建架构提案
devspec plan --from-text "迁移到微服务架构"

# 2. 生成架构设计
devspec design microservice-migration --type architecture

# 3. 分解为子任务
devspec expand microservice-migration

# 4. 跟踪实施进展
devspec list --status active

案例3: 数据库重构

# 1. 创建数据库提案
devspec plan --from-file db-migration.md

# 2. 生成数据库设计
devspec design db-v2 --type database

# 3. 验证迁移计划
devspec validate db-v2

# 4. 查看迁移脚本
devspec show db-v2 --full

🔧 配置选项

全局配置

DevSpec支持多种配置方式：

命令行参数 - 临时覆盖设置
配置文件 - 项目级别配置（.devspecrc.json）
环境变量 - 系统级别配置
交互式设置 - 首次使用时的设置向导

常用配置项

{
  "projects": {
    "defaultPath": "./devspec",
    "templatePath": "./templates"
  },
  "docs": {
    "autoSync": true,
    "includeInReadme": true,
    "indexPath": "./docs/README.md"
  },
  "validation": {
    "strictMode": true,
    "autoFix": false,
    "requiredSections": ["requirements", "scenarios"]
  },
  "git": {
    "autoCommit": false,
    "commitMessageTemplate": "feat: {proposal-title}"
  }
}

🐛 故障排除

常见问题

Q: DevSpec命令无法找到

# 检查安装
npm list -g devspec

# 重新安装
npm install -g devspec

# 检查PATH
echo $PATH | grep node_modules

Q: 项目初始化失败

# 检查权限
ls -la current-directory

# 手动创建目录
mkdir .devspec
devspec init

Q: 文档同步问题

# 手动同步
devspec docs sync

# 重建文档结构
devspec docs init --force

Q: 验证错误

# 详细验证输出
devspec validate <proposal-id> --verbose

# 检查配置文件
cat .devspecrc.json

# 重置配置
devspec init --reset-config

调试模式

启用详细日志输出：

# 启用调试模式
export DEVSPEC_DEBUG=1
devspec <command>

# 或使用命令行参数
devspec <command> --debug

📚 深入文档

🎯 路线图

v0.2.0 (计划中)

[ ] 支持插件系统
[ ] 集成代码生成器
[ ] Web界面支持
[ ] 团队协作功能

v0.3.0 (计划中)

[ ] CI/CD集成
[ ] 实时协作编辑
[ ] 多项目支持
[ ] 高级分析仪表板

v1.0.0 (长期目标)

[ ] 完整的企业级功能
[ ] 商业化部署支持
[ ] 社区生态建设
[ ] 国际化支持

📄 许可证

本项目采用 MIT 许可证 - 详见 LICENSE 文件。

🙏 致谢

感谢所有为DevSpec项目做出贡献的开发者和用户！

特别感谢：

所有测试用户和反馈提供者
开源社区的支持和贡献
AI助手框架和工具的开发者