redev-dev-standards/USAGE.md

Development standards management tool for multi-project teams with intelligent config merging

# 详细使用指南

## 🎯 使用场景

### 1. 新项目初始化
```bash
# 在项目根目录
npx redev-dev-standards init
```

### 2. 技术栈信息填写
初始化后，使用 Cursor AI 分析项目并填写技术栈信息：

```
请分析这个项目并填写 specs/project-config.yaml 和 AGENTS.md 中的技术栈信息
```

### 3. 定期更新标准
```bash
# 更新到最新的公司标准
npx redev-dev-standards update
```

## 📦 安装方式

### 方式一：全局安装（推荐）
```bash
npm install -g redev-dev-standards
```
安装后可以直接使用：
```bash
dev-standards init
dev-standards update
```

### 方式二：项目本地安装
```bash
npm install --save-dev redev-dev-standards
```
使用 npx 运行：
```bash
npx dev-standards init
npx dev-standards update
```

### 方式三：临时使用（无需安装）
```bash
npx redev-dev-standards init
npx redev-dev-standards update
```

## 🤖 AI 集成说明

### Cursor AI 如何读取配置
- **自动读取**: Cursor 会自动读取项目根目录的 `AGENTS.md`
- **上下文理解**: 根据 `AGENTS.md` 中的引用，读取 `specs/` 目录下的配置文件
- **智能行为**: AI 会理解项目的工作流程、代码规范、审查标准

### 常见问题解决

#### 问题：Cursor 没有遵循我们的流程
**原因分析**:
- AI 可能没有正确读取 `AGENTS.md` 文件
- 配置文件路径不正确
- AI 上下文没有更新

**解决方案**:
1. **检查文件位置**: 确保 `AGENTS.md` 在项目根目录
2. **明确指令**: 在对话中明确引用配置文件
3. **重新初始化**: 运行 `npx redev-dev-standards update` 更新配置
4. **手动引用**: 直接告诉 AI 参考哪个配置文件

#### 问题：AI 没有自动识别意图
**解决方案**:
- 使用更明确的关键词（如 "AZRD-12345"、"创建分支"、"发布到测试"）
- 在对话开始时明确说明要执行的操作
- 引用具体的工作流程步骤

## 🔧 命令详解

### `dev-standards init`
- **功能**: 初始化项目开发标准
- **交互**: 3个简单问题（项目名、描述、分支策略）
- **输出**: 完整的 `specs/` 目录和 `AGENTS.md` 文件
- **特点**: 使用占位符，支持 Cursor AI 后续分析

### `dev-standards update`
- **功能**: 更新项目到最新标准
- **检查**: 自动检查包版本更新
- **保护**: 智能保护项目特定设置
- **合并**: 深度合并公司级标准

## 🛡️ 配置保护机制

工具会自动保护以下项目特定设置：
- 项目名称和描述
- 技术栈配置
- 合并请求目标分支策略
- 项目特定编码标准

## 🤖 Cursor AI 集成

初始化后，使用以下提示词让 Cursor AI 自动分析技术栈：

```
请分析这个项目的代码结构和配置文件，然后填写以下文件中的技术栈信息：

1. specs/project-config.yaml 中的 tech_stack 部分
2. AGENTS.md 中的 Technology Stack 部分
3. specs/workflows/development.yaml 中的 project_info 部分

请根据以下信息进行分析：
- 项目配置文件（package.json, composer.json, requirements.txt 等）
- 代码文件扩展名和 import/require 语句
- 项目目录结构
- 依赖包信息

分析完成后，请将占位符（如 {{FRAMEWORK}}, {{LANGUAGE}} 等）替换为实际检测到的技术栈信息。
```

## 🔄 版本更新

当您看到版本更新提示时：

```bash
# 更新包
npm update -g redev-dev-standards

# 应用最新标准
npx redev-dev-standards update
```

## 🚨 快速故障排除

### 常见问题

| 问题 | 解决方案 |
|------|----------|
| `npx redev-dev-standards init` 失败 | 确保在项目根目录运行，检查网络连接 |
| Cursor AI 没有遵循流程 | 检查 `AGENTS.md` 是否在项目根目录 |
| 配置文件被覆盖 | 使用 `npx redev-dev-standards update` 而不是重新 init |
| 技术栈信息丢失 | 重新运行 Cursor AI 分析提示词 |

### 重置项目配置

如果需要完全重新开始：

```bash
# 删除现有配置
rm -rf specs/ AGENTS.md

# 重新初始化
npx redev-dev-standards init
```

## 📁 生成的文件结构

```
项目根目录/
├── specs/
│   ├── project-config.yaml          # 项目配置（技术栈、分支策略等）
│   ├── workflows/
│   │   └── development.yaml         # 开发工作流定义
│   └── standards/
│       ├── code-standards.yaml      # 代码规范
│       └── code-review.yaml         # 代码审查规范
└── AGENTS.md                        # AI 代理文档
```