yg-team-cli

v2.8.0

Published

a month 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 | 选择并执行开发任务 | | dev:wt | Worktree Orchestrator - 多角色并行开发 | | add-feature | 添加新功能 | | bugfix | 创建 Bugfix 记录 | | hotfix | 紧急修复 | | detect-deps | 检测依赖关系 | | sync-memory | 同步 AI_MEMORY.md | | check-api | API 检查（冲突/变更/Registry） | | status | 查看项目状态 | | lint | 前后端代码质量检查 | | logs | 查看 AI 开发会话历史 |

开发时间线

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

2026-02-03 - PRD → Spec 工作流重构

v2.5.0 - 新增 PRD → Spec 两阶段工作流

重构: add-feature 命令现在生成 PRD 到 docs/prd-docs/ 目录
新增: split-prd 支持单文件模式，将单个 PRD 转换为 Spec
移动: updateAiMemory 从 add-feature 移到 split-prd，Spec 生成后更新功能清单
工作流: add-feature → split-prd → breakdown

v2.5.1 - 修复目录创建 bug

修复: FileUtils.write 现在自动创建父目录，解决 docs/prd-docs/ 不存在时的写入失败问题

v2.5.2 - init 命令新增 prd-docs 目录

新增: team-cli init 现在默认创建 docs/prd-docs/ 目录供存放 PRD 需求文档

v2.5.3 - 优化 breakdown 命令合并逻辑

改进: breakdown 现在仅请求生成里程碑部分，并精确合并到原 Spec 文件
修复: 解决了 breakdown 命令可能会覆盖原文件技术设计内容的问题 (防止 Claude 的内容截断)

v2.5.4 - 修复 dev 模式交互卡死问题

修复: dev 命令现在真正进入交互式 Claude Code 会话，解决之前因非交互模式导致的长时间无反馈和卡死问题
改进: ClaudeAI 类新增 runTerminal 方法支持 stdio: 'inherit' 交互模式

v2.5.5 - 修复交互式会话初始 Prompt 丢失问题

修复: 确保启动交互式 Claude 时正确传递初始任务指令，无需用户手动粘贴指令

v2.5.6 - 优化开发者模式启动体验

改进: 调整交互式会话参数顺序，确保任务指令在启动时 100% 被加载
清理: 移除控制台冗余的 Prompt 打印信息，实现更清爽的界面切换

v2.5.7 - 修复 Claude CLI 可能重复启动的问题

修复: 优化内部检查逻辑，使用更轻量的 which 进行环境检查，避免因 --version 检查逻辑导致的潜在多次触发
优化: 简化 runTerminal 传参逻辑，移除冗余参数，确保单次稳定启动交互式会话

v2.5.8 - Milestone 选择样式优化

新增: team-cli dev 选择里程碑时，现在会直观显示已完成、进行中和未开始的状态图标及进度 (如 [4/7])
改进: 增强了 Spec 文件的解析逻辑，能够更准确地识别已标记为 [x] 的任务项

v2.5.9 - Spec 状态同步与动态检测

改进: dev 模式列表现在基于 Milestone 实际完成百分比动态显示 Spec 状态（即使文件头部状态未及时手动更新）
修复: 在通过 dev 命令完成任务时，系统现在会自动同步并更新 Spec 文件头部的“状态”标识，确保文档与进度一致

v2.6.0 - 统一状态解析逻辑与多维同步

重构: 将核心 Spec 解析逻辑沉淀至 SpecUtils 共享工具类，实现全系统逻辑收口
改进: status 命令与 sync-memory 命令现在统一接入动态进度推导引擎，解决状态显示落后的问题
优化: 全面统一了各命令中状态图标（✓, ⟳, ◉, ○）的定义，提供一致的视觉交互体验
增强: sync-memory 现在能更准确地根据任务勾选情况自动更新 AI_MEMORY.md 中的完成日期及状态列

v2.6.2 - 增强 Lint 命令稳定性

改进: lint 命令改为非阻塞式运行 TypeScript 类型检查。当检测到复杂的环境配置或老旧依赖导致的 tsc 报错时，系统将输出警告而非判定整体执行失败
新增: 为 lint 命令增加 --no-type-check 选项，允许完全跳过类型检查环节，专注于代码规范校验
修复: 统一了全系统的 Lint 扫描范围判定，减少了由于目录嵌套导致的误报现象

v2.4.10 - 修复 Claude 返回权限确认而非实际内容问题

修复: 添加 --dangerously-skip-permissions 参数跳过权限确认
问题: v2.4.9 中 Claude CLI 在新目录首次运行时返回权限确认提示而非 spec 内容

v2.4.9 - 修复 Claude 调用卡住问题

修复: claude.ts 中使用 input 选项通过 stdin 传递 prompt
问题: v2.4.8 将整个 prompt 作为命令行参数传递，导致大型 prompt 处理异常

v2.4.8 - 修复 add-feature 命令 Listr 进度显示和 AI_MEMORY 更新问题

修复: claude.ts 中 prompt 和 chat 方法使用 -p 参数以 print 模式运行
修复: stdio 从 inherit 改为 pipe，正确捕获 Claude 输出
修复: 添加 5 分钟超时和 10MB buffer 限制
影响: 解决了 Listr 任务进度卡在"调用 Claude 生成 spec"的问题

v2.4.7 - 修复 AI_MEMORY 功能清单更新

修复: add-feature.ts 中 updateAiMemory 函数逻辑重写
修复: 使用精确的段落定位在"功能清单"表格中插入新行
修复: 添加功能名称格式化（sso_pre_test → Sso Pre Test）
修复: Shell 脚本 team-cli 使用 awk 替代 sed 解决 macOS 兼容性问题

v2.4.4 - 修复 breakdown 命令日志变量未正确插值

提交: c873ea5
修复: breakdown.ts 中 ctx.selectedFile 变量未正确插值
npm 发布: [email protected]

v2.4.3 - 修复 breakdown 命令 Listr 任务上下文传递

提交: bed4981
修复: ctx.specs 和 ctx.selectedFile 未赋值问题
修复: ctx.breakdownResult 未赋值问题
修复: breakdown.ts 任务返回类型不匹配
npm 发布: [email protected]

v2.4.2 - 修复 add-feature 命令上下文传递

提交: 8cd6c85
修复: PRD 模式 ctx.generatedSpec 未赋值
修复: 简单描述模式 ctx.generatedSpec 未赋值
npm 发布: [email protected]

v2.4.1 - 修复 breakdown 命令上下文传递

提交: e674879
修复: ctx.breakdownResult 未赋值导致文件写入失败
npm 发布: [email protected]

v2.4.0 - SSO 模块集成

提交: d17a8be
新增: SSO 单点登录模块 (yungu-sso)
功能: CAS 集成、Token 验证、会话管理、UserContext
新增文件: src/templates/modules/yungu-sso/
新增依赖: org.yungu:login-client
npm 发布: [email protected]

2026-01-27 - GitLab 版本管理与 Dev 模式增强

Phase 4: GitLab 版本管理

提交: npm_feature 分支
新增命令: config, diff
功能:
- GitLab Access Token 管理（加密存储）
- 模板版本检查和更新
- 版本对比功能（支持 tag/branch）
- 模板版本信息记录到 AI_MEMORY.md
新增文件:
- src/lib/user-config.ts - 用户配置管理
- src/lib/gitlab-api.ts - GitLab API 客户端
- src/commands/config.ts - 配置管理命令
- src/commands/diff.ts - 版本对比命令
npm 发布: [email protected]

Phase 3: Dev 模式增强

功能:
- 任务完成后自动更新 spec 文件状态
- 支持单个 todo 或整个 milestone 批量更新
交互优化:
- 添加用户指引提示
- 移除超时限制，允许长时间开发

Phase 2: 迭代开发与自动化

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

安装

通过 npm 安装（推荐）

# 全局安装
npm install -g yg-team-cli

# 验证安装
team-cli --version

方式一：Git 仓库分发

# 克隆仓库
git clone https://gitlab.yungu-inc.org/yungu-app/claude-dev-cli.git
cd claude-dev-cli

# 安装依赖
npm install

# 构建项目
npm run build

# 全局链接
npm link

使用指南

1. 初始化项目

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

team-cli init my-project

指定版本初始化：

# 使用指定 tag 初始化
team-cli init my-project --backend-tag v1.2.0

# 使用指定分支初始化
team-cli init my-project --frontend-branch develop

# 前后端指定不同版本
team-cli init my-project --backend-tag v1.2.0 --frontend-branch develop

执行内容：

环境检查（Claude Code CLI）
交互式输入项目名称
创建标准目录结构
生成"宪法"文件（TECH_STACK.md, CONVENTIONS.md, AI_MEMORY.md）
从模板仓库克隆前后端代码
记录模板版本信息到 .team-cli/template.json 和 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）

15. 同步 AI_MEMORY

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

team-cli sync-memory

输出示例：

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

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

✓ AI_MEMORY.md 已同步

同步内容：

功能清单（状态、进度、完成日期）
API 列表（扫描 Controller 生成）
数据模型（表名、字段数、关联关系）
模板版本信息（前后端模板版本、commit、更新时间）

16. Dev 模式增强

开发任务完成后自动更新 Spec 文件状态：

team-cli dev
# → 选择 spec → milestone → todo
# → 在 Claude 中完成开发
# → 退出 Claude 后自动询问是否更新 spec 文件

交互流程：

开发任务完成!
✓ 会话日志已保存

? 任务是否已完成？是否更新 spec 文件中的 todo 状态？ (Y/n)

选择 Y 后自动：

找到对应的 todo 项
将 - [ ] 改为 - [x]
更新 spec 文件
下次运行 team-cli dev 时会显示为已完成

17. Worktree Orchestrator - 多角色并行开发

利用 Git Worktree 实现多角色并行开发的编排工具：

# 启动编排器
team-cli dev:wt

# 创建新的并行开发会话
team-cli dev:wt --new --ticket USER-123 --goal "用户登录功能"

# 列出所有 worktree
team-cli dev:wt --list

# 查看会话状态
team-cli dev:wt --status

# 运行指定阶段
team-cli dev:wt --run-phase 1 --ticket USER-123

# 验证交接物
team-cli dev:wt --verify --ticket USER-123

架构设计：

project/
├── ../wt/                    # Worktree 根目录（与项目同级）
│   └── USER-123/             # TICKET 目录
│       ├── planner/          # Planner worktree
│       ├── architect/        # Architect worktree
│       ├── backend/          # Backend worktree
│       ├── frontend/         # Frontend worktree
│       ├── qa/               # QA worktree
│       └── reviewer/         # Reviewer worktree
└── .handoff/                 # 交接物目录
    └── USER-123/             # TICKET 交接物
        ├── planner/          # Planner 产出物
        ├── architect/        # Architect 产出物
        ├── backend/          # Backend 产出物
        ├── frontend/         # Frontend 产出物
        ├── qa/               # QA 产出物
        ├── reviewer/         # Reviewer 产出物
        ├── MANIFEST.json     # 交接物清单
        └── reports/          # 执行报告

六个研发阶段：

| 阶段 | 名称 | 主要角色 | 并行策略 | |------|------|---------|---------| | 1 | 需求与 BDD 设计 | Planner | 独立工作 | | 2 | 架构与契约 | Architect | 独立工作 | | 3 | OpenAPI + Mock | Backend | 独立工作 | | 4 | 并行实现 | Backend + Frontend | 并行开发 | | 5 | BDD 验收 | QA | 独立工作 | | 6 | 集成与发布 | Reviewer | 独立工作 |

交互流程：

═══════════════════════════════════════════════════════
  Worktree Orchestrator
═══════════════════════════════════════════════════════

选择操作:
  1. 📋 新建并行开发会话
  2. 📂 列出所有 Worktree
  3. 📊 查看会话状态
  4. ▶️ 运行阶段
  5. ✅ 验证交接物
  6. 🚪 退出

新建会话示例：

▸ 输入 TICKET ID (例如 USER-123): USER-123
▸ 输入任务目标: 实现用户登录功能
▸ 选择参与角色:
  ✓ Planner (需求与 BDD)
  ✓ Architect (架构)
  ✓ Backend (后端)
  ✓ Frontend (前端)
  ✓ QA (BDD 验收)
  ✓ Reviewer (审查)

✓ 会话创建成功!
  Worktree 目录:
    - ../wt/USER-123/planner
    - ../wt/USER-123/architect
    - ../wt/USER-123/backend
    - ../wt/USER-123/frontend
    - ../wt/USER-123/qa
    - ../wt/USER-123/reviewer

  交接物目录:
    .handoff/USER-123/

是否立即开始运行 Phase 1? (y/N)

Gate 门禁检查：

═══════════════════════════════════════════════════════
  🚪 Gate 1 检查: 需求与 BDD 设计
═══════════════════════════════════════════════════════

✓ 前置阶段已全部完成

📋 Gate 检查清单:
  [ ] SPEC.md 包含目标/非目标/范围
  [ ] TASKS.md 任务拆分到可独立合并
  [ ] BDD 场景 Given/When/Then 完整
  [ ] 验收标准与 BDD 场景一一对应

────────────────────────────────────────────────────────
是否确认通过此 Gate? (y/N):

交接物清单：

| 角色 | 文件 | 类型 | 说明 | |------|------|------|------| | Planner | SPEC.md | spec | 功能规格文档 | | Planner | TASKS.md | tasks | 任务拆分 | | Planner | BDD_FEATURES/.feature | feature | BDD 场景 | | Architect | ADR.md | adr | 架构决策记录 | | Architect | API_RULES.md | api | API 设计规则 | | Backend | API_OPENAPI.yaml | openapi | OpenAPI 规范 | | Backend | API_EXAMPLES.md | api | API 示例 | | Backend | TESTING_.md | testing | 测试报告 | | QA | BDD_REPORT.md | report | BDD 验收报告 | | Reviewer | REVIEW.md | review | 审查报告 | | Reviewer | RELEASE.md | release | 发布方案 | | Reviewer | ROLLBACK.md | rollback | 回滚方案 |

环境变量配置

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 |


### 14. GitLab 版本管理

管理 GitLab 模板版本配置和更新：

```bash
# 配置 GitLab Token（首次使用必须）
team-cli config set-token

# 显示当前配置
team-cli config show

# 验证 Token
team-cli config validate

更新模板到最新版本：

# 检查并更新到最新版本
team-cli update

# 只更新后端模板
team-cli update --backend

# 更新到指定 tag
team-cli update --backend --tag v1.3.0

# 预览更新（不实际执行）
team-cli update --backend --tag v1.3.0 --dry-run

版本对比：

# 对比所有模板
team-cli diff

# 只对比后端模板
team-cli diff --backend

# 对比指定版本
team-cli diff --backend --tag v1.3.0

# 以 diff 格式输出
team-cli diff --backend --output diff

输出示例：

═══════════════════════════════════════════════════════
  模板版本对比
═══════════════════════════════════════════════════════

▸ 后端模板:
  本地版本: v1.2.0 (abc123)
  远程版本: v1.3.0 (def456)
  状态: ⚠️ 有更新

新增提交 (2):
  ✓ abc123 添加用户导出功能
  ✓ def456 修复分页查询 bug

环境变量配置

后端规范

分层架构：

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-02-03 - PRD → Spec 工作流重构

2026-01-27 - GitLab 版本管理与 Dev 模式增强

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

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

技术栈

后端

前端

测试与质量

安装

通过 npm 安装（推荐）

方式一：Git 仓库分发

使用指南

1. 初始化项目

2. 拆分 PRD

3. 拆分 Spec

4. 开发功能

5. 代码检查

6. 查看日志

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

7. 添加新功能

8. 创建 Bugfix 记录

9. 紧急修复

10. 查看项目状态

11. 依赖关系自动检测

15. 同步 AI_MEMORY

16. Dev 模式增强

17. Worktree Orchestrator - 多角色并行开发

环境变量配置

13. API 检查

环境变量配置

后端规范

前端规范

开发流程

Git 提交规范

完整工作流程

核心特性

1. 依赖关系管理

2. 状态管理

3. 模板降级机制

4. Git 集成

5. 彩色输出

设计理念

核心思想

1. 标准化（Standardization）

2. 自动化（Automation）

3. 可追溯（Traceability）

设计原则

技术决策

项目状态

贡献指南

许可证