SDD（OpenSpec规格驱动开发）+ AI Agent 原生协作的开发工程标准框架。 适用于 React/Vue + Spring Boot/FastAPI 的技术栈组合。
- 如何使用这套规范
- 应用场景：三种项目布局
- 一键裁剪命令（支持多选组合）
- OpenSpec 使用指南
- Makefile 命令参考
- CI/CD 流水线
- Git Worktree 使用指南
- CodeBuddy IDE 配置
- WorkBuddy 记忆系统
- Skills 技能系统
- 编码规范与代码质量
- 安全规范与扫描
- 环境变量配置
- 数据库操作流程
- 完整开发流程
- 多 IDE 协作
- 项目结构
- 技术栈
- 设计理念
- 相关文档
无论哪种平台，运行 dev / build / ci 前需安装对应工具链（本仓库是规范模板，frontend/、backend/ 仅含骨架配置，需先初始化真实项目并装好依赖才能跑通）：
| 工具 | 用途 | 安装方式 |
|---|---|---|
pnpm |
前端依赖 / 构建 / 测试 | npm i -g pnpm 或 corepack enable |
java + Gradle |
后端 (Java) 构建 | JDK 17，./gradlew 自带无需单独装 |
poetry |
后端 (Python) 依赖 | pip install poetry |
trivy |
安全扫描（可选） | 见 Trivy 官方文档 |
docker |
容器化（可选） | Docker Desktop |
# 1. 克隆或复制本仓库作为模板
git clone <this-repo-url> my-new-project
cd my-new-project
# 2. 移除模板的 .git 历史，重新初始化
rm -rf .git
git init
git add -A
git commit -m "chore: init from WorkBuddy standard"
# 3. 用 openspec 提出需求（/opsx:propose），或编辑 openspec/specs/ 主规范
# 4. 选择技术栈，进入对应子目录开始开发
cd frontend/react # 或 frontend/vue
pnpm install
pnpm dev
# 4b. 后端（Java 首次需生成 Gradle Wrapper，生成后 gradlew/gradle-wrapper.jar 需提交）
cd backend/java && gradle wrapper --gradle-version 8.7 && ./gradlew build
# 或
cd backend/python && poetry install
# 4c. 本地基础设施（PostgreSQL + Redis）
docker compose up -d # 或 make docker-up
# 5. 将真实项目文件添加到 Git
# ⚠ 锁文件必须提交：pnpm-lock.yaml、poetry.lock、gradle wrapper
git add -A
git commit -m "chore: project init with WorkBuddy standard"# 1. 将本仓库的核心文件复制到你的项目中
# 必选文件（这些是 AI 上下文的基石）：
#
# your-project/
# ├── AGENTS.md # 单文件权威入口
# ├── openspec/ # OpenSpec 规格驱动工作区（按需 init）
# ├── skills/ # Skill 定义
# ├── .codebuddy/ # CodeBuddy IDE 配置
# ├── .workbuddy/ # WorkBuddy 记忆系统
# ├── Makefile # 自动化命令（按需修改 target）
# ├── .gitlab-ci.yml # CI/CD 流水线（可选）
# ├── .env.example # 环境变量模板
# ├── .eslintrc.json # ESLint 共享配置
# └── .prettierrc # Prettier 共享配置
# 2. 修改 AGENTS.md 中的技术栈描述，
# 使其匹配你项目的实际技术栈
# 3. 用 openspec init 初始化，并通过 /opsx:propose 沉淀需求，
# 使其反映你项目的现状
# 4. 根据技术栈选择后端 rules，删除不需要的
# 例如纯 Java 后端 → 删除 .codebuddy/rules/react-spec.mdc 和 vue-spec.mdc
# 5. 提交变更，AI 助手启动后会自动读取 AGENTS.md手动删目录、删规则文件容易出错。脚本 scripts/scaffold.ps1 可按布局一键删除无关 frontend/ / backend/ 子树与 .codebuddy/rules/*.mdc，并把 AGENTS.md 的目录树与布局说明裁剪到对应形态（支持任意组合）。
# Windows (PowerShell) —— 布局可多选，空格分隔即可
powershell -File ./Make.ps1 init -Layout backend-python
powershell -File ./Make.ps1 init -Layout frontend-react
powershell -File ./Make.ps1 init -Layout backend-java frontend-vue # Java 后端 + Vue 前端
powershell -File ./Make.ps1 init -Layout backend-java backend-python # 同时保留两种后端
powershell -File ./Make.ps1 init -Layout full # 前后端一体（默认）
# 预览（不实际删除/改写）
powershell -File ./Make.ps1 init -Layout backend-java frontend-vue -DryRun# Linux / macOS / Git Bash
make init LAYOUT=backend-python
make init LAYOUT="backend-java frontend-vue" # Java + Vue
make init LAYOUT=full可选布局（可任意组合）：backend-java / backend-python / frontend-react / frontend-vue / full。脚本会删除无关子树与规则文件，并把 AGENTS.md 的目录树、布局说明裁剪到对应形态。裁剪前建议先提交或备份当前仓库（脚本会真正删除文件）。
┌─────────────────────────────────────────────────────────────┐
│ AI 启动流程 │
│ 1. 读取 AGENTS.md（单文件入口，含全部规范引用） │
│ 2. 读取 openspec/specs/ 主规范与 openspec/changes/（了解进度） │
│ 3. 按需用 /opsx:* 提出、实施、归档变更 │
│ 4. 加载 .codebuddy/rules/*.mdc（编码规范） │
│ 5. 按任务类型匹配 skills/ 中的 Skill，执行对应工作流 │
└─────────────────────────────────────────────────────────────┘
| 任务类型 | 对应 Skill | 说明 |
|---|---|---|
| 数据库 / ORM / 建表 | scaffold-database |
生成数据模型和 Migration |
| Docker / K8s / 部署 | scaffold-deploy |
生成部署配置 |
| 测试 / 覆盖率 | scaffold-test |
生成测试代码 |
OpenSpec（github.com/Fission-AI/OpenSpec）是一套面向 AI 编码助手的规范驱动开发（Spec-Driven Development, SDD）框架，MIT 开源。核心目标：在写任何代码之前，让人与 AI 就"要构建什么"达成书面一致，从而消除"需求只存在于聊天历史"的不确定性。
核心工作流（propose → apply → archive）：
/opsx:propose "你的需求" # 生成变更提案：proposal.md + specs + design.md + tasks.md
/opsx:apply # AI 按 tasks.md 逐项实施
/opsx:archive # 归档变更，合并进 openspec/specs/ 主规范目录结构：
openspec/
├── specs/ # 主规范（已实现能力的"真相源"，每个 capability 一个目录）
│ ├── project-overview/spec.md
│ ├── auth/spec.md
│ └── users/spec.md
├── changes/ # 变更提案（propose → apply → archive 流转）
│ └── archive/ # 已归档变更
└── config.yaml # OpenSpec 配置
主规范用纯 Markdown + SHALL/WHEN/THEN 表达需求，无需学习新语法。
# 前提：Node.js 20.19+，安装 CLI
npm install -g @fission-ai/openspec@latest
# 在项目根初始化（本仓库已初始化，并启用 CodeBuddy 支持）
openspec init --tools codebuddy
# 查看已存在的 specs
openspec list --specs初始 specs：
| capability | spec.md | 内容 |
|---|---|---|
project-overview |
openspec/specs/project-overview/spec.md | 项目背景、目标、非功能需求 |
auth |
openspec/specs/auth/spec.md | 注册/登录/刷新/登出 + API 契约 |
users |
openspec/specs/users/spec.md | 用户 CRUD + API 契约 |
日常开发流程：
# 1. 提出需求，AI 生成变更提案
/opsx:propose "实现用户注册登录"
# 2. 确认提案后，AI 按 tasks.md 实施
/opsx:apply
# 3. 实现完成，归档并合并进 openspec/specs/ 主规范
/opsx:archive铁律：变更 API 必须先走 OpenSpec 变更提案并同步 openspec/specs/ 主规范，再修改代码。
统一响应格式（必须遵守）：
{
"code": 0,
"message": "success",
"data": {},
"requestId": "uuid"
}错误码约定：
| 范围 | 含义 |
|---|---|
0 |
成功 |
1xxx |
参数校验错误 |
2xxx |
认证/授权错误 |
3xxx |
业务逻辑错误 |
5xxx |
服务端内部错误 |
9xxx |
第三方服务错误 |
数据模型： 表结构与字段约定在 openspec/specs/ 相关 capability 中描述，代码侧以 ORM 模型（MyBatis-Plus Entity / SQLAlchemy Model）与迁移脚本为准。命名规范：表名 snake_case 复数、必备 id/created_at/updated_at、软删除用 deleted_at。
跨平台说明：下表命令以
make为例（适用于 Linux / macOS / Git Bash）。 Windows (PowerShell) 请用等价的Make.ps1：把make <target>换成powershell -File ./Make.ps1 <target>（例如powershell -File ./Make.ps1 dev、powershell -File ./Make.ps1 ci；若装了 PowerShell 7+ 也可写pwsh ./Make.ps1 <target>）。
### 开发
| 命令 | 说明 |
|------|------|
| `make help` | 显示所有可用命令 |
| `make install` | 安装前后端全部依赖 |
| `make dev` | 启动开发环境（前端 dev server + 后端 bootRun/uvicorn） |
```powershell
# Windows (PowerShell)
powershell -File ./Make.ps1 help # 查看所有可用命令
powershell -File ./Make.ps1 dev # 启动开发环境
powershell -File ./Make.ps1 ci # 本地模拟 CI 流水线
# 若已安装 PowerShell 7+，也可把 powershell -File 替换为 pwsh
### 构建与测试
| 命令 | 说明 |
|------|------|
| `make build` | 构建前端 + 后端（跳过测试） |
| `make test` | 运行全部测试（前端 + 后端） |
| `make test-coverage` | 运行测试 + 生成覆盖率报告 |
| `make performance-test` | 运行性能测试（Gatling） |
### 代码质量
| 命令 | 说明 |
|------|------|
| `make lint` | 代码检查（ESLint + Checkstyle + Ruff） |
| `make format` | 代码格式化（Prettier + Spotless + Ruff） |
### 安全与合规
| 命令 | 说明 |
|------|------|
| `make security-scan` | SAST 安全扫描（Trivy） |
| `make sast-scan` | 代码安全审计（Bandit + OWASP Dependency Check） |
| `make compliance-check` | 合规检查（硬编码密钥 + .env 提交 + 敏感日志） |
| `make dependency-scan` | 依赖漏洞扫描（pnpm audit + OWASP + Safety） |
### 容器化
| 命令 | 说明 |
|------|------|
| `make docker-build` | 构建 Docker 镜像（基于根目录 `Dockerfile`，默认 Python FastAPI；若为 Java 后端请替换） |
| `make docker-up` | 启动 Docker Compose 服务（PostgreSQL + Redis + app） |
| `make docker-down` | 停止 Docker Compose 服务 |
> 根目录 `docker-compose.yml` 提供本地基础设施（PostgreSQL + Redis）与应用服务；环境变量来自 `.env`。
### 工具
| 命令 | 说明 |
|------|------|
| `make clean` | 清理所有构建产物 |
| `make db-migrate` | 运行数据库迁移（Flyway / Prisma） |
| `make db-studio` | 打开 Prisma Studio（数据可视化） |
| `make sync-skills` | 同步 `skills/` 到 `.claude/` 和 `.codex/` |
| `make ci` | 本地模拟 CI 流水线（lint → test → security → compliance → build） |
---
## CI/CD 流水线
### 流水线阶段
Build → Test → Security → Compliance → Docker → Deploy
### 各阶段说明
| 阶段 | Job | 触发条件 | 失败策略 |
|------|-----|----------|----------|
| **Build** | 前端构建 + Java 构建 + Python 依赖安装 | MR / main / develop | 阻断 |
| **Test** | 前端测试 + Java 测试 + Python 测试（含覆盖率） | MR / main | 阻断 |
| **Security** | Trivy 高危扫描 + Bandit 审计 + 依赖扫描 | MR / main | Trivy 阻断，其余告警 |
| **Compliance** | 硬编码密钥检测 + .env 提交检测 | MR | 阻断 |
| **Docker** | 构建并推送镜像到 Registry | main / tags | 阻断 |
| **Deploy** | 部署到 staging（develop） / production（tags，手动触发） | develop / tags | 阻断 |
### 手动触发生产部署
```bash
# 打 tag 触发生产部署（部署步骤需手动点击确认）
git tag v1.0.0
git push origin v1.0.0
# 在推送代码前，本地模拟完整 CI 流水线
make ci
# 单独运行某个阶段
make lint
make test
make security-scan
make compliance-check
make buildGit Worktree 允许你在同一仓库的不同分支上同时工作，无需 clone 多份代码。每个 worktree 是一个独立的目录，可以独立进行开发、构建、测试。
本项目的所有 worktree 统一放在 worktrees/ 目录下，该目录已加入 .gitignore，随用随建，用完即删。
project-root/
├── worktrees/ ← 全部 worktree 放这里（gitignored）
│ ├── feature-payment/ ← feature/payment 分支
│ ├── fix-login-bug/ ← fix/login-bug 分支
│ └── hotfix-v1.2.1/ ← hotfix/v1.2.1 分支
# ── 创建 Worktree ─────────────────────────────────────────
# 基于当前分支创建新 worktree + 新分支
git worktree add worktrees/feature-xxx -b feature/xxx
# 基于指定分支创建
git worktree add worktrees/feature-xxx -b feature/xxx main
# 基于已有分支创建（不新建分支）
git worktree add worktrees/hotfix-v1.2.1 hotfix/v1.2.1
# ── 查看 Worktree ─────────────────────────────────────────
# 列出所有 worktree
git worktree list
# ── 切换工作 ──────────────────────────────────────────────
# 每个 worktree 独立，直接在对应目录下开发即可
cd worktrees/feature-xxx
pnpm install
pnpm dev
# ── 清理 Worktree ─────────────────────────────────────────
# 删除 worktree（先确保分支已合并/推送）
git worktree remove worktrees/feature-xxx
# 清理已删除但未 remove 的 worktree 记录
git worktree prune
# 手动删除（prune 后再清理目录不会报错）
# git worktree remove 会自动调用 prune# 1. 从主分支创建 feature 分支的 worktree
git worktree add worktrees/feature-user-auth -b feature/user-auth main
# 2. 进入 worktree 目录开发
cd worktrees/feature-user-auth
# ... 写代码、测试、commit ...
# 3. 同时在主分支处理 hotfix（不切换目录）
git worktree add worktrees/hotfix-critical-fix -b hotfix/critical-fix main
cd worktrees/hotfix-critical-fix
# ... 修复、commit、push、合入 MR ...
# 4. 回到 feature 继续开发
cd worktrees/feature-user-auth
# 主分支的代码完全不受影响
# 5. 开发完成，合入主线后清理
git checkout main # 先切回主 worktree
git pull
git worktree remove worktrees/feature-user-auth
git worktree remove worktrees/hotfix-critical-fix# AI 助手通常绑定到特定 worktree。并行开发时：
# - worktree-1 (feature-A): 让 AI 开发模块 A
# - worktree-2 (feature-B): 让另一个 AI 会话开发模块 B
# 两个 AI 互不干扰，各自遵循 AGENTS.md 中的同一套规范
# 注意事项：
# - 同一分支不能同时在两个 worktree 中检出
# - 构建产物（node_modules, build/）在每个 worktree 中独立
# - 如果 AI 生成了通用文件（如 skills/、openspec/），需要 cherry-pick 到其他 worktree| 注意事项 | 说明 |
|---|---|
| 同一分支只能在一个 worktree 中检出 | 不能同时在两个目录编辑同一分支 |
worktrees/ 已 gitignored |
worktree 目录本身不提交，由每个开发者本地维护 |
共享 .git 对象 |
多个 worktree 共享同一 .git 目录，空间占用小 |
| 构建产物独立 | 每个 worktree 的 node_modules、build/ 互不影响 |
| 变更互不可见 | 切换 worktree 依赖文件系统，AI 助手需手动告知当前 worktree |
{
"hooks": { ... }, // 会话钩子（自动触发）
"rules": { ... }, // 编码规则（alwaysApply）
"enableAllProjectRules": true,
"permissions": { ... } // 命令权限控制
}| Hook | 触发时机 | 作用 |
|---|---|---|
SessionStart |
AI 会话启动时 | 自动注入团队规范上下文 |
PostToolUse |
写入/修改文件后 | 检测硬编码密钥、console.log 等违规 |
Hook 脚本位置： .codebuddy/hooks/inject-team-standards.sh
Hook 检查项：
- 硬编码密钥检测（
password=,secret=,api_key=） console.log遗留检测（前端文件）- 文件命名规范告警
项目内置 4 条 always-apply 规则（文件位于 .codebuddy/rules/）：
| 规则文件 | 覆盖范围 |
|---|---|
java-coding-style.mdc |
Java 后端：分层架构、命名、Controller/Service 模板 |
react-spec.mdc |
React 前端：组件结构、Hooks、Zustand Store 模板 |
vue-spec.mdc |
Vue 前端：<script setup>、Composables、Pinia Store 模板 |
security-rules.mdc |
通用安全：密钥管理、JWT、XSS、SQL 注入、数据脱敏 |
# 1. 在 .codebuddy/rules/ 目录创建 .mdc 文件
# 例如: .codebuddy/rules/go-coding-style.mdc
# 2. 在 .codebuddy/settings.json 中注册
# "go-coding-style": {
# "path": ".codebuddy/rules/go-coding-style.mdc",
# "alwaysApply": true
# }| 策略 | 说明 |
|---|---|
| Allow | pnpm install, pnpm run, gradle, poetry, make, git, docker |
| Deny | rm -rf, git push --force, git reset --hard |
┌─────────────────────────────────────────┐
│ Layer 1: 项目架构记忆 │
│ 来源: AGENTS.md + .codebuddy/rules/ │
│ 生命周期: 持久化（随项目演进更新） │
│ 作用: 让 AI 始终知道项目规范和技术栈 │
├─────────────────────────────────────────┤
│ Layer 2: 会话上下文记忆 │
│ 来源: 当前会话任务进度 │
│ 生命周期: 最多保留 5 个会话 │
│ 作用: AI 知道"上次做到哪了" │
├─────────────────────────────────────────┤
│ Layer 3: 知识库记忆 │
│ 来源: ADR / 踩坑记录 / 技术债务 │
│ 生命周期: 长期（跨会话持久化） │
│ 作用: 关键决策不丢失 │
└─────────────────────────────────────────┘
.workbuddy/memory/
├── memory.toml # 三层记忆系统开关和来源配置
├── context.md # 最近变更上下文（AI 自动维护）
└── knowledge.md # 架构决策记录 + 踩坑记录 + 技术债务
# 1. 在 knowledge.md 中记录架构决策（ADR）
## 架构决策记录
### ADR-001: 选用 PostgreSQL 而非 MySQL
- 日期: 2026-08-06
- 状态: 已采纳
- 理由: 更好的 JSON 支持 + 更丰富的索引类型
# 2. 记录踩坑经验（AI 后续会主动规避）
## 踩坑记录
### Node.js 20 与某些 npm 包不兼容
- 解决方案：package.json 中设置 engines.node >= 20.0.0
# 3. 记录技术债务（AI 会提醒你在合适时机清理）
## 技术债务
### 用户模块缺少单元测试（优先级: P1, 计划 v1.2 清理）Skill 是领域知识模板文件（SKILL.md），告诉 AI 在特定场景下该如何工作。每个 Skill 包含：
| 要素 | 说明 |
|---|---|
name |
Skill 唯一标识 |
description |
Skill 功能描述 |
triggers |
触发关键词列表（用户输入匹配时自动激活） |
| 工作流程 | 分步骤的 SOP（标准操作流程） |
| 规范要求 | 该领域必须遵守的约束 |
| 检查清单 | 生成代码后的自检项 |
skills/
├── scaffold-database/
│ └── SKILL.md # Frontmatter + 工作流 + 规范 + 检查清单
├── scaffold-deploy/
│ └── SKILL.md
└── scaffold-test/
└── SKILL.md
当用户输入匹配 triggers 关键词时，AI 自动加载对应 Skill：
用户: "帮我创建一个用户表" → 触发 scaffold-database
用户: "写 Docker 部署文件" → 触发 scaffold-deploy
用户: "给 UserService 补单元测试" → 触发 scaffold-test
# 1. 创建 Skill 目录和文件
mkdir -p skills/scaffold-notification
# 2. 编写 SKILL.md（必须包含 Frontmatter）
cat > skills/scaffold-notification/SKILL.md << 'EOF'
---
name: scaffold-notification
description: 消息通知模块开发规范，支持邮件/短信/站内信/推送。
triggers:
- "消息通知"
- "发送邮件"
- "推送"
- "站内信"
- "短信"
---
# Skill: scaffold-notification
## 工作流程
1. 读取 openspec/specs/ 中通知相关需求
2. ...
## 规范要求
- ...
## 检查清单
- [ ] ...
EOF
# 3. 同步到其他 IDE
make sync-skills
# 4. 提交到 Git（跨队友共享）
git add skills/scaffold-notification/
git commit -m "feat(skills): add scaffold-notification skill"Skill 主定义在 skills/，通过 make sync-skills 自动同步到：
skills/ # 主定义（手动编辑这里）
├─→ .claude/skills/ # Claude Code 副本
└─→ .codex/skills/ # Codex 副本
| 场景 | 规范 |
|---|---|
| 文件命名 | 组件用 PascalCase，非组件用 kebab-case |
| 缩进 | 2 空格 |
| 行宽 | 100 字符 |
| 引号 | 单引号 |
| 分号 | 必须 |
| 尾逗号 | 全部添加 |
| 换行符 | LF |
| 场景 | Java | Python |
|---|---|---|
| 类名 | PascalCase | PascalCase |
| 方法/函数 | camelCase | snake_case |
| 常量 | UPPER_SNAKE_CASE | UPPER_SNAKE_CASE |
| 缩进 | 4 空格 | 4 空格 |
| 行宽 | 120 字符 | 100 字符 |
# 前端 Lint
cd frontend/react && pnpm run lint
# Java Checkstyle
cd backend/java && ./gradlew checkstyleMain
# Python Ruff
cd backend/python && poetry run ruff check .
# 一键全部检查
make lint# 前端格式化
cd frontend/react && pnpm run format
# Java 格式化
cd backend/java && ./gradlew spotlessApply
# Python 格式化
cd backend/python && poetry run ruff format .
# 一键全部格式化
make format<type>(<scope>): <subject>
| type | 用途 |
|---|---|
feat |
新功能 |
fix |
Bug 修复 |
refactor |
重构 |
perf |
性能优化 |
style |
格式调整 |
docs |
文档变更 |
test |
测试变更 |
chore |
构建/工具 |
分支命名： feature/<描述> / fix/<描述> / hotfix/<描述> / release/<版本>
在任何 MR 合入前，确认以下项：
- 无硬编码密钥/密码/Token（使用
.env环境变量） - 密码使用 BCrypt / Argon2 加密存储
- JWT Access Token 有效期 ≤ 2h，Refresh Token 有效期 ≤ 7d
- Token 使用 HttpOnly Cookie 或内存存储，禁止存 localStorage
- 所有接口有权限校验（接口级 + 数据级）
- 用户输入已做参数校验（Controller 层）
- 响应不返回
password字段（使用 VO / Schema 控制） - 未使用字符串拼接 SQL（使用参数化查询）
- 未使用
dangerouslySetInnerHTML/v-html（否则必须 DOMPurify） - 日志中敏感信息已脱敏
make security-scan # SAST 扫描（Trivy，查高危/严重漏洞）
make sast-scan # 代码安全审计（Bandit + OWASP Dependency Check）
make dependency-scan # 依赖漏洞扫描（pnpm audit + Safety）
make compliance-check # 合规检查（硬编码密钥 + .env 提交 + 敏感日志）| 检查项 | 正则 | 阻断级别 |
|---|---|---|
| 硬编码密钥 | password\s*=\s*"[^"]+" |
阻断 |
| .env 文件提交 | git ls-files '*.env'（排除 .env.example） |
阻断 |
| 敏感日志打印 | console.log.*password 等 |
阻断 |
手机号：138****1234
身份证：320***********1234
邮箱：u***@example.com
密码：******
Token：eyJhbG ****... （仅记录前 6 位 + 省略）
| 分类 | 变量 | 说明 |
|---|---|---|
| 应用配置 | APP_NAME, APP_ENV, APP_DEBUG, APP_PORT |
基础配置 |
| 数据库 | APP_DATABASE_URL, APP_DB_* |
数据源 |
| Redis | APP_REDIS_URL, APP_REDIS_* |
缓存 |
| JWT | APP_JWT_SECRET, APP_JWT_ACCESS_EXPIRES, APP_JWT_REFRESH_EXPIRES |
认证 |
| API | APP_API_BASE_URL, APP_CORS_ORIGINS |
接口 |
APP_SMTP_* |
邮件 | |
| 第三方 | APP_WECHAT_*, APP_OSS_* |
外部服务 |
- 全部 UPPER_SNAKE_CASE
- 统一
APP_前缀 - 敏感信息必须走环境变量，禁止硬编码
# 1. 创建本地环境变量文件
cp .env.example .env
# 2. 编辑 .env，填入真实值
# ⚠ .env 已在 .gitignore 中，不会被提交
# 3. Java 读取
# application.yml: ${APP_DB_PASSWORD}
# 4. Python 读取
# pydantic-settings: Field(validation_alias="APP_DB_PASSWORD")
# 5. 前端读取（Vite）
# import.meta.env.VITE_API_BASE_URL# 1. 在 openspec/specs/ 相关 capability 中补充数据模型需求
# 2. AI 生成 Migration（或手动创建）
# 命名: V{序号}__{描述}.sql
# 3. 运行迁移
make db-migrate
# 4. AI 自动生成对应的实体代码
# Java: Entity + Mapper (MyBatis-Plus)
# Python: Model (SQLAlchemy)# 1. 在 openspec/specs/ 相关 capability 中修改数据模型需求
# 2. 创建新的 Migration 文件
# ⚠ 禁止修改已执行的 Migration 文件
# 3. 运行迁移
make db-migrate
# 4. 同步更新对应的 Entity / Model# 打开 Prisma Studio（Python 项目）
make db-studio- 表名：snake_case 复数（
user_orders） - 列名：snake_case（
created_at） - 必备字段：
id、created_at、updated_at - 软删除：按需添加
deleted_at - 所有字段必须有数据库 COMMENT
- Migration 使用 Flyway 命名：
V{序号}__{描述}.sql
1. 需求阶段
├── /opsx:propose "功能" → 生成 proposal.md + specs + design.md + tasks.md
└── 确认提案内容（为什么做、做什么、验收标准）
2. 设计阶段
├── 在提案 specs/ 中补充需求场景与 API 契约
└── 在 design.md 中确定技术方案与数据模型
3. 开发阶段
├── 创建 worktree：git worktree add worktrees/feature-xxx -b feature/xxx
├── /opsx:apply：AI 按 tasks.md 逐项实施（读取 openspec/ → 遵循 rules/ → 匹配 skills/）
├── 本地运行：make dev
└── 本地测试：make test
4. 质量阶段
├── make lint # 代码检查
├── make format # 代码格式化
├── make security-scan # 安全扫描
├── make compliance-check # 合规检查
└── make test-coverage # 覆盖率确认 ≥ 80%
5. 提交阶段
├── git add + git commit（遵循 <type>(<scope>): <subject> 格式）
└── git push → 触发 CI 流水线
6. 合入阶段
├── MR Review → CI 自动运行 lint/test/security/compliance
├── 全部通过后合入 → 自动构建 Docker 镜像
└── 打 tag 触发生产部署（手动确认）
7. 清理阶段
├── git worktree remove worktrees/feature-xxx
└── /opsx:archive：归档变更，合并进 openspec/specs/ 主规范
用户: "帮我实现用户注册功能"
AI:
1. /opsx:explore → 明确方案
2. /opsx:propose "用户注册功能" → 生成变更提案
3. 读取 openspec/specs/auth/spec.md → 确认需求与 API 契约
4. 加载 .codebuddy/rules/ → 遵循对应技术栈规范
5. 生成 Controller + Service + DTO + VO（Java）
（或 Route + Service + Schema + Model（Python））
6. 检查安全规范（密码加密、JWT、参数校验）
7. 实现完成后 /opsx:archive 归档并同步主规范
| IDE / 工具 | 配置文件 | Skills 副本 | 说明 |
|---|---|---|---|
| CodeBuddy | .codebuddy/ |
直接读 skills/ |
完整支持 rules + hooks |
| Claude Code | .claude/ |
.claude/skills/ |
通过 make sync-skills 同步 |
| Codex | .codex/ |
.codex/skills/ |
通过 make sync-skills 同步 |
| WorkBuddy | .workbuddy/ |
直接读 skills/ |
记忆系统 + MCP 连接器 |
| Cursor / Copilot / Windsurf | 根目录文件 | 通过 AGENTS.md |
上下文由 AGENTS.md 提供 |
# 场景：A 用 CodeBuddy，B 用 Claude Code，共享同一仓库
# 1. 两人共享同一套规范
# - AGENTS.md：两人各自的 AI 启动时都读取
# - openspec/：两人基于同一套规范（specs + changes）开发
# - skills/：两人共用同一套 Skill 模板
# 2. A 新增了一个 Skill
# A: 编辑 skills/scaffold-notification/SKILL.md
# A: make sync-skills
# A: git push
# B: git pull（自动获得新 Skill）
# 3. B 更新了编码规则
# B: 编辑 .codebuddy/rules/go-coding-style.mdc
# B: git push
# A: git pull（AI 下次启动自动生效）project-root/
├── AGENTS.md # 单文件权威上下文入口（AI 必读）
├── openspec/ # OpenSpec 规格驱动工作区
│ ├── specs/ # 主规范（每个 capability 一个目录/spec.md）
│ │ ├── project-overview/ # 项目总览
│ │ ├── auth/ # 认证模块
│ │ └── users/ # 用户管理
│ ├── changes/ # 变更提案（propose → apply → archive）
│ └── config.yaml # OpenSpec 配置
├── skills/ # 跨 IDE Skill 定义（手动编辑这里）
│ ├── scaffold-database/SKILL.md # 数据库模块 Skill
│ ├── scaffold-deploy/SKILL.md # 部署配置 Skill
│ └── scaffold-test/SKILL.md # 测试代码 Skill
├── .codebuddy/ # CodeBuddy IDE 专有配置
│ ├── settings.json # Hooks + Rules 引用 + 权限控制
│ ├── rules/ # 团队规则文件 (.mdc)
│ │ ├── java-coding-style.mdc
│ │ ├── react-spec.mdc
│ │ ├── vue-spec.mdc
│ │ └── security-rules.mdc
│ └── hooks/ # Hook 触发脚本
│ └── inject-team-standards.sh
├── .workbuddy/ # WorkBuddy 记忆系统
│ └── memory/ # 三层记忆配置（需提交 Git）
│ ├── memory.toml # 记忆系统配置
│ ├── context.md # 会话上下文
│ └── knowledge.md # 知识库（ADR / 踩坑 / 技术债务）
├── .claude/skills/ # Claude Code Skill 副本（同步自 skills/）
├── .codex/skills/ # Codex Skill 副本（同步自 skills/）
├── frontend/
│ ├── react/ # React 18+ / TypeScript / Vite / Ant Design
│ │ ├── package.json
│ │ └── src/
│ │ ├── components/ # 通用组件
│ │ ├── pages/ # 页面组件
│ │ ├── hooks/ # 自定义 Hooks
│ │ ├── stores/ # Zustand Store
│ │ ├── services/ # API 请求层
│ │ ├── utils/ # 工具函数
│ │ ├── types/ # TypeScript 类型
│ │ └── styles/ # 全局样式
│ └── vue/ # Vue 3.4+ / TypeScript / Vite / Element Plus
│ ├── package.json
│ └── src/
│ ├── components/
│ ├── pages/
│ ├── composables/ # Vue Composables
│ ├── stores/ # Pinia Store
│ ├── services/
│ ├── utils/
│ ├── types/
│ └── styles/
├── backend/
│ ├── java/ # Spring Boot 3.x / Java 17 / Gradle / MyBatis-Plus
│ │ ├── build.gradle
│ │ └── src/main/
│ │ ├── controller/ # 控制器（参数校验 + 调用 Service）
│ │ ├── service/ # 业务逻辑 + 事务管理
│ │ ├── repository/ # MyBatis-Plus Mapper
│ │ ├── entity/ # 数据实体 (PO)
│ │ ├── dto/ # DTO / VO
│ │ └── config/ # Security / CORS / Swagger
│ └── python/ # FastAPI / Python 3.12 / Poetry / SQLAlchemy
│ ├── pyproject.toml
│ └── app/
│ ├── api/ # 路由控制层
│ ├── services/ # 业务逻辑层
│ ├── models/ # SQLAlchemy Model
│ ├── schemas/ # Pydantic Schema
│ └── core/ # Security / CORS / OpenAPI
├── worktrees/ # Git Worktree 目录 (gitignored)
├── .gitlab-ci.yml # CI/CD 6 阶段流水线
├── Makefile # 自动化命令入口（dev/test/security/deploy）
├── .env.example # 环境变量模板（不提交 .env）
├── .eslintrc.json # ESLint 共享配置（TypeScript 严格模式）
├── .prettierrc # Prettier 共享配置（多语言覆盖）
├── .mcp.json # MCP 连接器配置（context7 / playwright）
├── .gitignore # 覆盖 Node / Java / Python / Docker / IDE
└── WorkBuddy 生产级项目工程标准化规范.md # 原始规范文档
| 层级 | 技术 | 说明 |
|---|---|---|
| 前端框架 | React 18+ / Vue 3.4+ | SPA 应用 |
| 语言 | TypeScript 5.x | 类型安全 |
| 构建 | Vite 5+ | HMR 极速构建 |
| UI 库 | Ant Design 5.x / Element Plus | 企业级组件 |
| 状态管理 | Zustand / Pinia | 轻量级 |
| 后端框架 | Spring Boot 3.x (Java 17) / FastAPI (Python 3.12) | REST API |
| ORM | MyBatis-Plus / SQLAlchemy 2.0 | 数据访问 |
| 数据库 | PostgreSQL 16 | 主存储 |
| 缓存 | Redis 7 | 缓存 + 分布式锁 |
| 消息队列 | Kafka / RabbitMQ | 异步解耦 |
| 对象存储 | MinIO / S3 | 文件存储 |
| 注册中心 | Nacos | 服务发现 + 配置 |
| 构建工具 | pnpm / Gradle / Poetry | 包管理 |
规格（Spec）是代码的权威定义，代码是实现。
openspec/specs/ 主规范 → 需求（SHALL/WHEN/THEN）→ 代码
openspec/changes/ → 变更提案 → propose → apply → archive
铁律：变更 API 必须先走 OpenSpec 变更提案并同步 openspec/specs/ 主规范，再修改代码。
AGENTS.md是单文件上下文入口，AI 启动时优先读取skills/是领域知识模板，按任务类型自动调度.codebuddy/、.workbuddy/、.claude/、.codex/各 IDE 平等支持- AI 生成代码必须遵循 AGENTS.md 和
.codebuddy/rules/中定义的规范 - Hook 机制在写入文件后自动进行合规检查
- 规范层：
.codebuddy/rules/security-rules.mdc强制安全编码 - 检查层：Hook 脚本实时检测硬编码密钥
- 扫描层：
make security-scan+ CI 阶段自动 SAST - 合规层：
make compliance-check+ CI 阶段阻断违规
| 文档 | 说明 |
|---|---|
| AGENTS.md | 权威上下文入口（AI 必读，含全部编码规范速查） |
| openspec/specs/ | OpenSpec 主规范（项目总览 / 认证 / 用户管理） |
| openspec/changes/ | OpenSpec 变更提案与归档 |
| openspec/config.yaml | OpenSpec 配置 |
| .gitlab-ci.yml | CI/CD 流水线定义（6 阶段自动门禁） |
| Makefile | 自动化命令入口（24 个 target） |