GD Project Kit

AI 工程化项目模板 - 需求驱动开发工作流初始化工具

快速为你的项目搭建标准化的 AI 工程化基础设施，包括代理（Agents）、技能（Skills）、命令（Commands）等完整的工作流体系。

特性

✨ 一键初始化 - 快速搭建完整的 AI 工程化项目结构 🤖 内置代理 - 5 个专业 AI 代理，覆盖需求到实施全流程 🛠️ 丰富技能 - 15+ 细粒度技能，支持各类开发场景 📦 智能处理 - 自动检测已存在文件，提供备份/跳过/覆盖选项 🔄 灵活模式 - 支持全新初始化、增量更新、预演模式

安装

全局安装（推荐）

npm install -g gd-project-kit

使用 npx（无需安装）

npx gd-project-kit init

快速开始

在当前目录初始化

gd-project-kit init

在指定目录初始化

gd-project-kit init ./my-project

使用方法

基本用法

# 初始化当前目录
gd-project-kit init

# 在指定目录初始化
gd-project-kit init <目标目录>

# 查看帮助
gd-project-kit --help

# 查看版本
gd-project-kit --version

处理模式

当检测到文件已存在时，工具会询问你如何处理：

注意: 备份模式和强制模式只对 .codebuddy/ 目录（包括其所有子目录）生效。对于 AGENTS.md、requirements/、context/ 等其他文件和目录，始终使用跳过模式，确保不会意外覆盖用户自定义内容。

1. 备份模式（默认，推荐）

gd-project-kit init --backup

• ✅ 只对 .codebuddy/ 目录下的文件备份为 .backup 后缀
• ✅ 其他文件（AGENTS.md、requirements、context 等）保持不变
• ✅ 适合更新 AI 代理配置而不影响业务数据

2. 跳过模式

gd-project-kit init --skip

• ✅ 保留所有已存在的文件不变
• ✅ 只创建不存在的文件
• ✅ 适合增量更新或部分初始化

3. 强制覆盖模式

gd-project-kit init --force

• ⚠️ 只对 .codebuddy/agents、.codebuddy/commands、.codebuddy/skills 目录强制覆盖
• ✅ 其他文件（AGENTS.md、requirements、context 等）保持不变
• ⚠️ 会丢失 .codebuddy/ 目录中的现有数据，请谨慎使用
• ✅ 适合重新初始化 AI 代理配置

4. 预演模式

gd-project-kit init --dry-run

• ✅ 显示将要执行的操作
• ✅ 不实际创建或修改文件
• ✅ 用于预览初始化结果

初始化内容

执行初始化后，会创建以下目录结构：

your-project/
├── AGENTS.md                    # AI 项目记忆文件
├── .codebuddy/                  # AI 工程化配置目录
│   ├── agents/                  # 角色代理定义（5个）
│   │   ├── phase-router.md
│   │   ├── requirement-manager.md
│   │   ├── design-manager.md
│   │   ├── implementation-executor.md
│   │   └── experience-depositor.md
│   ├── commands/                # 统一命令入口（4个）
│   │   ├── req-dev.md
│   │   ├── init-project.md
│   │   ├── optimize-flow.md
│   │   └── load-service.md
│   └── skills/                  # 细粒度技能（15+个）
│       ├── req-create/          # 需求创建
│       ├── req-change/          # 需求变更
│       ├── design-create/       # 方案设计
│       ├── design-change/       # 方案变更
│       ├── design-impl/         # 方案实施
│       ├── code-commit/         # 代码提交
│       ├── experience-index/    # 经验索引
│       ├── workspace-setup/     # 工作区设置
│       ├── requirement-completer/
│       ├── requirement-archiver/
│       ├── index-manager/       # 索引管理
│       ├── meta-maintainer/     # 元信息维护
│       └── init-project/        # 项目初始化
├── requirements/                # 需求管理目录
│   ├── INDEX.md                 # 需求总索引
│   ├── in-progress/             # 进行中需求
│   ├── completed/               # 已完成需求
│   └── designs/                 # 技术方案
├── context/                     # 上下文知识库
│   ├── business/                # 业务知识
│   ├── tech/                    # 技术知识
│   │   └── services/
│   │       └── INDEX.md
│   └── experience/              # 经验沉淀
│       └── INDEX.md
└── workspace/                   # 开发工作区（自动创建）

工作流程

1. 初始化项目

cd your-project
codebuddy-init

2. 查看项目结构

cat AGENTS.md

了解可用的代理、技能和工作流程。

3. 开始需求开发

使用 /req-dev 命令（在支持的 AI 工具中）开始需求驱动开发。

4. 使用技能

浏览 .codebuddy/skills/ 目录，了解可用的技能及其使用方法。

使用场景

新项目启动

mkdir my-new-project
cd my-new-project
gd-project-kit init

为现有项目添加 AI 工程化

cd existing-project
gd-project-kit init --backup  # 备份现有文件

更新模板到最新版本

# 1. 备份重要文件
git add .
git commit -m "备份当前状态"

# 2. 更新 AI 代理配置（备份或强制模式）
gd-project-kit init --backup  # 备份 .codebuddy/ 目录
# 或
gd-project-kit init --force   # 强制覆盖 .codebuddy/agents、commands、skills

# 注意：AGENTS.md、requirements/、context/ 等业务文件不会被覆盖

预览初始化效果

gd-project-kit init --dry-run

常见问题

Q1: 如何更新到最新版本？

A: 全局安装的情况下：

npm update -g gd-project-kit

或使用 npx 会自动使用最新版本。

Q2: 会覆盖我的现有文件吗？

A: 默认不会。工具会检测已存在的文件并询问你如何处理：

• 备份模式（默认）：只对 .codebuddy/ 目录下的文件备份，其他文件保留
• 跳过模式：保留所有现有文件
• 强制模式：只对 .codebuddy/agents、.codebuddy/commands、.codebuddy/skills 目录强制覆盖，其他文件保留

注意: AGENTS.md、requirements/、context/ 等业务文件始终不会被覆盖，确保你的自定义内容安全。

Q3: 可以自定义初始化内容吗？

A: 初始化后，你可以：

• 修改 .codebuddy/ 中的代理和技能定义
• 编辑 AGENTS.md 添加项目特定信息
• 在 context/ 中添加业务和技术知识

注意：AGENTS.md、requirements/、context/ 等业务文件在任何模式下都不会被覆盖，你的自定义内容始终安全。只有 .codebuddy/ 目录下的代理、命令、技能定义会在备份模式或强制模式下被更新。

Q4: .codebuddy 目录要提交到 Git 吗？

A: 推荐做法：

• ✅ 将 AGENTS.md、requirements/、context/ 提交到 Git
• ❌ 将 .codebuddy/ 添加到 .gitignore（因为可以通过 gd-project-kit init 重新生成）

但如果你自定义了 .codebuddy/ 的内容，也可以选择提交。

Q5: 如何卸载？

A:

npm uninstall -g gd-project-kit

要删除项目中的文件，手动删除相关目录即可：

rm -rf .codebuddy requirements context AGENTS.md

命令速查

| 命令 | 说明 | |------|------| | gd-project-kit init | 在当前目录初始化 | | gd-project-kit init ./dir | 在指定目录初始化 | | gd-project-kit init --backup | 备份 .codebuddy/ 目录下的文件（默认） | | gd-project-kit init --skip | 跳过所有已存在的文件 | | gd-project-kit init --force | 强制覆盖 .codebuddy/agents、commands、skills | | gd-project-kit init --dry-run | 预演模式，不实际执行 | | gd-project-kit --help | 显示帮助信息 | | gd-project-kit --version | 显示版本号 |

技术栈

• Node.js: >=14.0.0
• 依赖: 仅使用 Node.js 内置模块，无额外依赖

相关资源

• 📦 NPM: https://www.npmjs.com/package/gd-project-kit
• 📖 文档: https://github.com/your-username/gd-project-kit
• 🐛 问题反馈: https://github.com/your-username/gd-project-kit/issues
• 💬 讨论: https://github.com/your-username/gd-project-kit/discussions

贡献

欢迎贡献！请查看 贡献指南。

许可证

MIT © [Your Name]

提示: 初始化后，建议先阅读 AGENTS.md 了解项目的工作流程和可用功能。