cswanghan-team-cli

v2.0.0

Published

6 days ago

AI-Native 团队研发脚手架 - Node.js 版本

0High
0Medium
0Low

cswanghan

cli scaffold team ai claude spring-boot nextjs

team-cli

AI-Native 团队研发脚手架 CLI 工具

一个统一团队工程初始化标准、利用 Claude Code 能力自动化生成代码的命令行工具。

功能概述

team-cli 是一个功能完善的 AI-Native 团队研发脚手架工具，提供从项目初始化到代码开发的全流程支持。

核心功能

| 命令 | 功能描述 | |------|---------| | init | 初始化标准化项目结构 | | split-prd | 将 PRD 文档拆分为多个功能规格 | | breakdown | 将 spec 拆分为 milestones 和 todos | | dev | 选择并执行开发任务 | | add-feature | 添加新功能 | | bugfix | 创建 Bugfix 记录 | | hotfix | 紧急修复 | | detect-deps | 检测依赖关系 | | sync-memory | 同步 AI_MEMORY.md | | check-api | API 检查（冲突/变更/Registry） | | status | 查看项目状态 | | lint | 前后端代码质量检查 | | logs | 查看 AI 开发会话历史 |

开发时间线

以下记录了 team-cli 的开发进展，按时间倒序排列。

2026-01-27 - 迭代开发与自动化

Phase 3: API 管理功能

提交: 6a69bc5
新增命令: check-api
功能:
- 自动扫描后端 Controller 生成 API 文档
- 维护 API 定义、版本和变更历史
- API 冲突检测（防止重复定义）
- API 变更检测（基于 Git diff）
新增文件: docs/api-registry.md
代码量: +360 行

Phase 2: 自动化功能

提交: a06c74f
新增命令: sync-memory, detect-deps
功能:
- AI_MEMORY 自动同步（功能清单、API 列表、数据模型）
- 依赖关系自动检测（API 调用、实体关联、服务引用）
- 自动匹配 spec 文件
代码量: +620 行

Phase 1: 迭代开发支持

提交: 54685ab
新增命令: add-feature, bugfix, hotfix, status
功能:
- 添加新功能（交互式选择依赖）
- Bugfix 规范化管理
- Hotfix 紧急修复（规范化 commit log）
- 项目状态查看
代码量: +724 行

2026-01-26 - 模板仓库与 README

模板仓库配置

提交: 95c134a
变更: 更新后端模板仓库地址
新地址: [email protected]:yungu-app/java-scaffold-template.git

README 文档

提交: f3b70e7
新增: 完整的 README.md 文档
内容: 功能介绍、使用指南、设计理念

2026-01-23 - 基础设施与初始化

Session Log 优化

提交: 1825501
修复: 移除 session log 问题

Gradle 支持

提交: 5265aca
新增: Gradle 构建支持

项目初始化

提交: a2ca717
初始提交: 项目首次初始化

技术栈

后端

Java 17 (LTS)
Spring Boot 3.x
MyBatis Plus 3.5+
MySQL 8.0
Gradle 8.x

前端

Next.js 14 (App Router)
TypeScript 5.x
Tailwind CSS 3.x
Shadcn/UI

测试与质量

后端: JUnit 5, Checkstyle, SpotBugs
前端: Jest/Vitest, ESLint

安装

方式一：Git 仓库分发（推荐）

# 克隆仓库
git clone https://github.com/your-org/team-cli.git
cd team-cli

# 添加到 PATH
echo 'export PATH=$PATH:'$(pwd)'' >> ~/.zshrc
source ~/.zshrc

# 赋予执行权限
chmod +x team-cli

方式二：直接下载

# 下载脚本
curl -O https://raw.githubusercontent.com/your-org/team-cli/main/team-cli

# 赋予执行权限
chmod +x team-cli

# 添加到 PATH
sudo mv team-cli /usr/local/bin/

使用指南

1. 初始化项目

创建一个新的标准化项目：

team-cli init my-project

执行内容：

环境检查（Claude Code CLI）
交互式输入项目名称
创建标准目录结构
生成"宪法"文件（TECH_STACK.md, CONVENTIONS.md, AI_MEMORY.md）
从模板仓库克隆前后端代码
初始化 Git 仓库
配置 pre-commit hook

生成的目录结构：

my-project/
├── TECH_STACK.md              # 技术栈定义
├── CONVENTIONS.md             # 开发规范
├── AI_MEMORY.md              # 项目状态记录
├── backend/                  # Spring Boot 后端
├── frontend/                 # Next.js 前端
├── docs/
│   ├── specs/                # 需求规格文档
│   ├── api/                  # API 文档
│   └── sessions/             # AI 会话日志
└── .git/hooks/pre-commit     # Git 预提交钩子

2. 拆分 PRD

将产品需求文档拆分为多个独立的功能规格：

# 准备 PRD 文档
mkdir -p docs/prd-docs/{screenshots,demo-repo}
# 将 prd.md 放入 docs/prd-docs/

# 执行拆分
team-cli split-prd docs/prd-docs

PRD 文档结构：

docs/prd-docs/
├── prd.md              # PRD 描述文档（必需）
├── screenshots/        # 功能截图（可选）
└── demo-repo/          # Demo 代码仓库（可选）

输出： 在 docs/specs/ 目录生成多个 kebab-case 命名的 markdown 文件。

3. 拆分 Spec

将功能规格拆分为可执行的 milestones 和 todos：

team-cli breakdown docs/specs/user-authentication.md

输出的 Milestone 格式：

## 里程碑

### Milestone 1: 数据模型设计
**目标**: 设计用户认证相关的数据库表结构
**状态**: 待开始
**预估**: 1 天

**Todo List**:
- [ ] 设计 User 实体和表结构
- [ ] 定义 Role 和 Permission 枚举
- [ ] 创建 MyBatis Mapper 接口

4. 开发功能

选择并执行开发任务：

team-cli dev

开发流程：

步骤 1/3 - 选择 spec 文件：

自动解析依赖关系
拓扑排序推荐开发顺序
显示状态图标：
- ✓ 已完成
- ⟳ 进行中
- ◉ 已拆分
- ○ 未开始

步骤 2/3 - 选择 milestone：

列出所有 milestones
可选择实现整个 spec

步骤 3/3 - 选择 todo：

列出选中 milestone 的 todos
可选择实现整个 milestone

执行开发任务：

构建 prompt 发送给 Claude
Claude 按照 TDD 方式开发
API 定义 → 测试 → 后端实现 → 前端集成
记录会话日志到 docs/sessions/

5. 代码检查

运行前后端代码质量检查：

team-cli lint

检查内容：

前端：

ESLint 语法检查
TypeScript 类型检查

后端：

Checkstyle 代码规范检查
SpotBugs 潜在 Bug 检查
Gradle 编译检查

退出码：

0 - 检查通过
1 - 检查失败

6. 查看日志

查看 AI 开发会话历史：

# 查看今日日志
team-cli logs

# 查看指定日期日志
team-cli logs 2026-01-26

# 查看所有日志
team-cli logs --all

日志存储位置： docs/sessions/YYYY-MM-DD/HH-MM_SS_<spec-name>.md

日志内容：

时间戳
执行的 spec 文件
Milestone/Todo 信息
耗时统计
用户 Prompt
变更文件列表

新增功能使用样例 (2026-01-27)

以下命令是在今天开发迭代中新增的，用于支持项目的持续开发和维护。

7. 添加新功能

在已有项目中添加新功能，自动处理依赖关系：

cd my-project
team-cli add-feature payment-system

交互流程：

═══════════════════════════════════════════════════════
  添加新功能: payment-system
═══════════════════════════════════════════════════════

▸ 扫描已有功能...
✓ 找到 2 个已有 specs

已有功能列表:
  [1] user-authentication ✓
  [2] user-profile ✓

➜ 选择此功能依赖的已有功能（已完成的功能）:
  依赖 user-authentication? (y/n): y
  依赖 user-profile? (y/n): y
✓ 选择了 2 个依赖

▸ 创建 spec 文件...
✓ 创建 spec 文件: docs/specs/payment-system.md

▸ 更新 AI_MEMORY.md...
✓ AI_MEMORY.md 已更新

═══════════════════════════════════════════════════════
  功能添加完成!
═══════════════════════════════════════════════════════

下一步:
  1. 编辑 spec 文件完善需求：
     vim docs/specs/payment-system.md

  2. 拆分为 milestones 和 todos：
     team-cli breakdown docs/specs/payment-system.md

  3. 开始开发：
     team-cli dev

生成的 spec 文件自动包含依赖关系：

## 依赖关系

**前置依赖**:
- [x] user-authentication.md
- [x] user-profile.md

**被依赖于**:
- (自动生成，表示哪些 spec 依赖本功能)

8. 创建 Bugfix 记录

为发现的 bug 创建规范的修复记录：

team-cli bugfix

交互流程：

═══════════════════════════════════════════════════════
  创建 Bugfix 记录
═══════════════════════════════════════════════════════

Bug 描述: 用户登录时特殊字符报错
关联 spec (可选，直接回车跳过): user-authentication
严重程度 (高/中/低，默认: 中): 高

✓ 创建 Bugfix 记录: docs/bugfixes/2026-01-27-login-special-char.md
✓ AI_MEMORY.md 已更新

═══════════════════════════════════════════════════════
  Bugfix 记录创建完成!
═══════════════════════════════════════════════════════

下一步:
  1. 完善 bugfix 文档：
     vim docs/bugfixes/2026-01-27-login-special-char.md

  2. 运行开发模式开始修复：
     team-cli dev

  3. 修复完成后更新 bugfix 状态

生成的 Bugfix 文件结构：

# Bugfix: 用户登录时特殊字符报错

## Bug 信息
- **ID**: BUG-20260127-000
- **关联 Spec**: user-authentication
- **严重程度**: 高
- **状态**: 待修复

## 问题描述
用户登录时特殊字符报错

## 复现步骤
1. 输入用户名
2. 输入包含特殊字符的密码
3. 点击登录

## 根本原因
待分析

## 修复方案
- [ ] 分析根本原因
- [ ] 设计修复方案
- [ ] 编写测试用例
- [ ] 实现修复
- [ ] 验证修复

9. 紧急修复

对于需要立即修复的线上问题：

team-cli hotfix

交互流程：

═══════════════════════════════════════════════════════
  创建 Hotfix
═══════════════════════════════════════════════════════

问题描述: 支付接口超时导致订单失败
影响范围: 所有使用支付宝的用户，约20%订单失败
严重程度 (高/中/低，默认: 高): 高
模块 (如: payment, user, order): payment
根本原因: 支付宝SDK超时时间设置过短
临时方案: 增加超时时间到15s
后续计划 (可选): 优化支付流程使用异步回调

▸ 创建 hotfix 分支: hotfix/HOTFIX-20260127-000
✓ 分支创建成功
✓ Commit message 模板已生成
✓ Hotfix 记录已添加到: docs/hotfixes.md
✓ AI_MEMORY.md 已更新

═══════════════════════════════════════════════════════
  Hotfix 准备完成!
═══════════════════════════════════════════════════════

当前分支: hotfix/HOTFIX-20260127-000

下一步:
  1. 进行代码修复

  2. 添加修改的文件：
     git add <files>

  3. 使用预设的 commit message 提交：
     git commit -F .git/HOTFIX_COMMIT_MSG

  4. 推送到远程并创建 MR/PR：
     git push -u origin hotfix/HOTFIX-20260127-000

  5. 合并到 main 分支

提示: Hotfix 合并后，建议创建规范 Bugfix 进行彻底修复

生成的 Commit Message 格式：

hotfix(payment): 支付接口超时导致订单失败

HOTFIX-20260127-000
Severity: 高
Impact: 所有使用支付宝的用户，约20%订单失败
Root-Cause: 支付宝SDK超时时间设置过短
Temporary-Solution: 增加超时时间到15s
Permanent-Plan: 优化支付流程使用异步回调

10. 查看项目状态

快速查看项目整体状态：

team-cli status

输出示例：

═══════════════════════════════════════════════════════
  项目状态
═══════════════════════════════════════════════════════

功能清单:

  No. 功能                          状态            进度
  ─────────────────────────────────────────────────────────
  [01] User Authentication           ✅ 已完成        3/3
  [02] User Profile                 ✅ 已完成        3/3
  [03] Order Management            ⟳ 进行中        2/3
  [04] Payment System              ○ 未开始        0/3

Bugfix 记录:

  共 1 个 bugfix 记录
  最新: 2026-01-27-login-special-char (待修复)

Git 状态:

  当前分支: hotfix/HOTFIX-20260127-000
  工作区: 有未提交的更改
    - 未暂存: 2 个文件
    - 已暂存: 1 个文件

11. 依赖关系自动检测

自动检测代码中的依赖关系：

# 检测单个 spec 的依赖
team-cli detect-deps docs/specs/payment-system.md

# 检测所有 specs 的依赖
team-cli detect-deps

输出示例：

═══════════════════════════════════════════════════════
  检测依赖关系
═══════════════════════════════════════════════════════

▸ 自动检测依赖关系...
  - 扫描后端 API 调用...
  - 扫描后端实体关联...
  - 扫描后端服务引用...
  - 扫描前端 API 调用...

✓ 检测到 2 个潜在依赖:
  - user-authentication.md
  - order-management.md

是否自动更新依赖关系到 spec 文件? (y/n): y
✓ 依赖关系已更新到 docs/specs/payment-system.md

═══════════════════════════════════════════════════════
  依赖检测完成
═══════════════════════════════════════════════════════

检测维度：

后端 API 调用
实体关联（@ManyToOne, @OneToMany 等）
服务引用（Service 注入）
前端 API 调用（fetch, axios）

12. 同步 AI_MEMORY

自动同步 AI_MEMORY.md，保持项目状态最新：

team-cli sync-memory

输出示例：

═══════════════════════════════════════════════════════
  同步 AI_MEMORY.md
═══════════════════════════════════════════════════════

▸ 同步 AI_MEMORY.md...
  - 扫描 specs 更新功能清单...
  - 扫描 Controller 更新 API 列表...
  - 扫描 Entity 更新数据模型...
  - 更新最后同步时间...

✓ AI_MEMORY.md 已同步

同步内容：

功能清单（状态、进度、完成日期）
API 列表（扫描 Controller 生成）
数据模型（表名、字段数、关联关系）

13. API 检查

检查 API 的冲突和变更：

team-cli check-api

交互式菜单：

═══════════════════════════════════════════════════════
  API 检查
═══════════════════════════════════════════════════════

选择检查类型:
  1) 检测 API 冲突
  2) 检测 API 变更
  3) 生成 API Registry
  4) 全部执行

请选择 (1-4): 1

选项 1: 检测 API 冲突

▸ 检测 API 冲突...
✓ 未检测到 API 冲突

选项 2: 检测 API 变更

▸ 检测 API 变更...
✓ 检测到 API 变更:
  - PaymentController.java
    新增: 2 个 API
    删除: 0 个 API

是否更新 API Registry? (y/n): y
✓ API Registry 已生成: docs/api-registry.md

选项 3: 生成 API Registry

▸ 扫描并生成 API Registry...
✓ API Registry 已生成: docs/api-registry.md

生成的 API Registry 格式：

# API Registry

## Payment 模块

### POST /api/payment/create

**版本**: v1.0
**说明**: 创建支付订单

**请求**:
```json
{
  "orderId": "string",
  "amount": 0
}

变更历史: | 日期 | 版本 | 变更类型 | 变更说明 | 作者 | |------|------|---------|---------|------| | 2026-01-27 | v1.0 | 新增 | 初始版本 | team-cli |


---

## 环境变量配置

```bash
# 后端模板仓库
export [email protected]:yungu-app/java-scaffold-template.git

# 本地后端模板（降级使用）
export LOCAL_BACKEND_TEMPLATE=/path/to/local/backend/template

# 前端模板仓库
export FRONTEND_TEMPLATE_REPO=https://gitlab.yungu-inc.org/static/fe-tpl-ai

# 本地前端模板（降级使用）
export LOCAL_FRONTEND_TEMPLATE=/path/to/local/frontend/template

# Git 网络超时时间（秒）
export GIT_TIMEOUT=5

开发规范

后端规范

分层架构：

Controller → Service → Mapper → Entity

DTO 模式：

所有 API 使用 DTO，禁止暴露 Entity
Request DTO: CreateXxxRequest
Response DTO: XxxResponse

命名规范：

Entity: User, Order
DTO: UserDTO, CreateUserRequest, UserResponse
Service: UserService, UserServiceImpl
Mapper: UserMapper

前端规范

函数式组件 + Hooks
PascalCase 命名组件文件
camelCase 命名工具文件
所有 props/state 必须有类型

开发流程

TDD 优先 - 先写测试
API First - 先定义 API 契约
小步提交 - 每个 commit 只做一件事

Git 提交规范

<type>(<scope>): <subject>

feat: 新功能
fix: 修复
docs: 文档
style: 格式
refactor: 重构
test: 测试
chore: 构建/工具

完整工作流程

# 1. 初始化项目
team-cli init my-project
cd my-project

# 2. 准备并拆分 PRD
# 将 PRD 文档放入 docs/prd-docs/
team-cli split-prd docs/prd-docs

# 3. 拆分功能规格
team-cli breakdown docs/specs/feature-name.md

# 4. 开发功能
team-cli dev
# → 选择 spec → milestone → todo

# 5. 代码检查
team-cli lint

# 6. 查看开发日志
team-cli logs

核心特性

1. 依赖关系管理

自动解析 spec 之间的依赖关系
拓扑排序确定推荐开发顺序
防止循环依赖
视觉化显示依赖信息

2. 状态管理

每个 spec 维护状态：

未开始 → 已拆分 → 进行中 → 已完成

3. 模板降级机制

网络不可达时自动降级：

尝试远程 Git 仓库（超时检测）
降级到本地模板路径
创建最小化目录结构

4. Git 集成

自动初始化 Git 仓库
pre-commit hook 自动运行 lint
记录文件变更历史

5. 彩色输出

使用 ANSI 颜色代码：

绿色 - 成功信息
黄色 - 进行中/警告
红色 - 错误信息
蓝色 - 标题
青色 - 步骤提示

设计理念

核心思想

团队-cli 的设计理念是"标准化 + 自动化 + 可追溯"，通过三个维度解决团队研发中的协作效率问题：

1. 标准化（Standardization）

问题: 团队成员技术栈选择、代码风格、项目结构不统一，导致协作成本高。

解决方案:

宪法文件: TECH_STACK.md 定义技术栈，CONVENTIONS.md 定义开发规范
脚手架模板: 统一的前后端项目结构，开箱即用
代码规范: 集成 Checkstyle、ESLint 等工具，强制执行规范
Git Hook: pre-commit 自动检查，防止不符合规范的代码提交

2. 自动化（Automation）

问题: 重复性的初始化工作、代码生成工作浪费开发时间。

解决方案:

一键初始化: team-cli init 自动生成完整项目结构
AI 辅助开发: 集成 Claude Code，自动生成增删改查代码
智能拆分: 自动将 PRD 拆分为 specs，再拆分为 milestones 和 todos
依赖分析: 自动解析 spec 依赖关系，推荐开发顺序

3. 可追溯（Traceability）

问题: 需求变更频繁，开发过程缺乏记录，难以回溯决策原因。

解决方案:

AI_MEMORY.md: 记录项目状态、技术决策、已完成功能
会话日志: 每次 AI 开发对话都记录到 docs/sessions/
Git 历史: 结合 Git commit，可追溯每个功能的实现时间
Spec 模板: 标准化的需求文档格式，便于查阅

设计原则

约定优于配置 - 硬编码最佳实践，减少选择困难
渐进式开发 - 支持 PRD → Spec → Milestone → Todo 的渐进式拆解
失败友好 - 模板降级机制，网络不可达时仍可工作
AI-Native - 深度集成 Claude Code，最大化 AI 辅助能力
单文件分发 - 所有逻辑封装在一个 Shell 脚本，方便分发

技术决策

| 决策点 | 选择 | 理由 | |-------|------|------| | 实现语言 | Shell 脚本 | 单文件分发，无依赖，适合 Mac/Linux | | 构建工具 | Gradle | 比 Maven 更灵活，配置更简洁 | | 前端框架 | Next.js 14 (App Router) | React 最新特性，服务端渲染 | | ORM | MyBatis Plus | 比 JPA 更灵活，SQL 可控 | | AI 集成 | Claude Code | Anthropic 官方 CLI，支持代码操作 |

项目状态

当前版本基于以下 Git 提交：

614c10d - 添加 Docker 支持
1825501 - 移除 session log 问题
5265aca - 更新到 Gradle
a2ca717 - 首次初始化

贡献指南

欢迎提交 Issue 和 Pull Request！

许可证

MIT License

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

team-cli

功能概述

核心功能

开发时间线

2026-01-27 - 迭代开发与自动化

2026-01-26 - 模板仓库与 README

2026-01-23 - 基础设施与初始化

技术栈

后端

前端

测试与质量

安装

方式一：Git 仓库分发（推荐）

方式二：直接下载

使用指南

1. 初始化项目

2. 拆分 PRD

3. 拆分 Spec

4. 开发功能

5. 代码检查

6. 查看日志

新增功能使用样例 (2026-01-27)

7. 添加新功能

8. 创建 Bugfix 记录

9. 紧急修复

10. 查看项目状态

11. 依赖关系自动检测

12. 同步 AI_MEMORY

13. API 检查

开发规范

后端规范

前端规范

开发流程

Git 提交规范

完整工作流程

核心特性

1. 依赖关系管理

2. 状态管理

3. 模板降级机制

4. Git 集成

5. 彩色输出

设计理念

核心思想

1. 标准化（Standardization）

2. 自动化（Automation）

3. 可追溯（Traceability）

设计原则

技术决策

项目状态

贡献指南

许可证