hwd32/ai_soc_sw
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
6c09a9b6d4fbaf7f466fff5457d69545f2ab5c65
ai_soc_sw/hwd32h757/.trae/skills/ai-collab-setup/SKILL.md
T

1183 lines
35 KiB
Markdown
Raw Normal View History

init.
2026-05-26 16:43:31 +08:00
---
name: "ai-collab-setup"
description: "Creates complete '1 Human + 3 AI' collaboration framework with directory structure and AI constitution. Invoke when starting a new AI-assisted programming project."
---
# AI 协作框架快速搭建
## 功能
一键创建"1 人+3AI（Arch+Coder+Tester）"协作框架，包括：
- 完整的目录结构
- AI 角色定义与权限约定（AGENTS.md）—— R/W/RW/- 四态权限体系
- AI 配置文件（含 read_only_paths、forbidden_paths、description）
- 提示词模板（code-style.md、doc-template.md、bug-report.md）
- 工作流配置（5 阶段 + retry + escalation）
- 示例任务模板
- README 文档
## 使用方法
在新项目根目录执行：
```bash
# 调用此 skill
# skill 会自动创建所有必要的目录和文件
```
## 创建的内容
### 目录结构
```
.
├── AGENTS.md # AI 宪法（角色定义 + 权限约定 + R/W/RW/- 矩阵）
├── README.md # 项目说明
├── .gitignore
├── .ai/
│ ├── config/
│ │ ├── architect.json # Arch AI 配置（含 read_only_paths）
│ │ ├── coder.json # Dev AI 配置（含 read_only_paths）
│ │ ├── tester.json # QA AI 配置（含 read_only_paths）
│ │ └── workflow.json # 工作流配置（含 retry + escalation）
│ └── prompts/
│ ├── coding/ # 编码提示词
│ │ ├── README.md
│ │ ├── code-style.md # 代码风格规范
│ │ └── doc-template.md # impact.md / acceptance.md 模板
│ └── testing/ # 测试提示词
│ ├── README.md
│ └── bug-report.md # Bug 报告模板（BLOCKER/HIGH/MEDIUM/LOW）
├── docs/ # 项目级总体文档（Dev AI 编写，QA AI 只读）
│ ├── 01_产品需求/
│ ├── 02_系统架构/
│ ├── 03_开发规范/
│ ├── 04_部署运维/
│ └── 05_变更日志/
│ └── archived/ # 历史变更日志（按年月归档）
├── tools/ # 开发工具脚本（Dev AI 维护）
├── data/ # 训练数据（Dev AI 维护，QA AI 只读）
├── projects/
│ ├── P01_app/
│ │ ├── src/ # Dev AI 工作区（前端 + 后端 + 配置）
│ │ │ ├── server/ # NestJS 后端
│ │ │ ├── config/ # 构建配置
│ │ │ └── types/ # 全局类型
│ │ ├── tests/ # QA AI 工作区
│ │ ├── docs/
│ │ │ ├── 01_需求概要.md
│ │ │ ├── 02_架构设计.md
│ │ │ └── 03_接口定义.md
│ │ └── ENVIRONMENT.md
│ └── P02_training/
│ ├── src/
│ ├── tests/
│ ├── docs/
│ └── ENVIRONMENT.md
├── review/
│ ├── active/ # 活跃任务
│ │ ├── P01-001/
│ │ │ ├── task.md # 任务描述（人类创建，AI 只读）
│ │ │ ├── acceptance.md # 验收标准
│ │ │ ├── impact.md # 变更影响范围
│ │ │ └── feedback/ # 测试反馈
│ │ │ └── round1.md
│ │ ├── P01-002/
│ │ └── CROSS-001/
│ └── archived/ # 归档任务（按季度）
│ └── 2026-Q2/
├── shared/
│ ├── scripts/
│ ├── templates/
│ └── utils/
├── reports/
│ ├── test-results/ # 测试结果
│ └── quality-reports/ # 质量评审报告
└── .github/workflows/
```
### 核心文件
**AGENTS.md** - AI 宪法：
- 三个角色定义（人类、Dev AI、QA AI）
- R/W/RW/- 四态权限矩阵
- 工作流程（4 阶段 + 缺陷修复循环）
- retry 配置（max_rounds=3，escalation 规则）
- 沟通规范
- 命名规范
**AI 配置文件**：
- `.ai/config/coder.json` - Dev AI 权限和职责（含 read_only_paths、forbidden_paths）
- `.ai/config/tester.json` - QA AI 权限和职责（含 read_only_paths、forbidden_paths）
- `.ai/config/workflow.json` - 工作流配置（含 retry + escalation）
**提示词模板**：
- `.ai/prompts/coding/code-style.md` - 代码风格、命名规范、目录组织
- `.ai/prompts/coding/doc-template.md` - impact.md / acceptance.md 标准化模板
- `.ai/prompts/testing/bug-report.md` - Bug 报告模板，严重程度定义
**示例任务**：
- `review/active/P01-001/` - 示例任务（包含 task、acceptance、impact、feedback）
- `review/active/CROSS-001/` - 跨项目任务示例
## 执行命令
```bash
# 1. 创建目录结构
mkdir -p .ai/{config,prompts/{coding,testing}} \
projects/{P01_app,P02_training}/{src/{server,config,types},tests,docs} \
review/{active/{P01-001,P01-002,CROSS-001},archived/2026-Q2}/feedback \
shared/{scripts,templates,utils} \
reports/{test-results,quality-reports} \
.github/workflows
# 2. 创建 AGENTS.md
cat > AGENTS.md << 'EOF'
# AI 角色定义与权限约定
## 团队架构
```
┌─────────────────────────────────────────────┐
│ 人类负责人 │
│ 需求分析 · 架构设计 · 最终决策 │
└───────────────┬───────────┬─────────────────┘
│ │
┌───────────┴──┐ ┌────┴────────────┐
▼ ▼ ▼ ▼
┌───────────────┐ ┌──────────────┐ ┌───────────────┐
│ Arch AI │ │ Dev AI │ │ QA AI │
│ 需求分析 │ │ 代码编写 │ │ 测试设计 │
│ 架构设计 │ │ 文档生成 │ │ 测试执行 │
│ 技术选型 │ │ 影响评估 │ │ 质量保障 │
│ 跨模块协调 │ └──────────────┘ └───────────────┘
└───────────────┘
```
---
## 角色职责
### Arch AI (架构AI)
**职责范围：**
- ✅ 需求分析和产品规划
- ✅ 系统架构设计
- ✅ 技术选型和评估
- ✅ 跨模块协调和集成
- ✅ 编写架构文档 (`docs/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估变更影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
- ✅ 维护开发工具 (`tools/`)
- ✅ 维护训练数据 (`data/`)
- ✅ 指导 Dev AI 和 QA AI 工作
**可读但不可写：**
- 👁 AI 配置文件 (`.ai/`) —— 只读，了解团队规则
- 👁 测试代码 (`projects/*/tests/`) —— 只读，了解测试覆盖
- 👁 测试报告 (`reports/`) —— 只读，了解质量状况
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，了解问题
**禁止操作：**
- ❌ 无（架构 AI 拥有最高 AI 权限）
### Dev AI (编码AI)
**职责范围：**
- ✅ 编写业务代码 (`projects/*/src/`)
- ✅ 生成技术文档 (`projects/*/docs/`)
- ✅ 定义验收标准 (`review/*/acceptance.md`)
- ✅ 评估变更影响 (`review/*/impact.md`)
- ✅ 维护共享资源 (`shared/`)
**可读但不可写：**
- 👁 任务描述 (`review/*/task.md`) —— 只读，不可修改
- 👁 测试反馈 (`review/*/feedback/`) —— 只读，用于修 Bug
**禁止操作：**
- ❌ 修改测试代码 (`projects/*/tests/`)
- ❌ 修改测试报告 (`reports/`)
### QA AI (测试AI)
**职责范围：**
- ✅ 编写测试用例 (`projects/*/tests/`)
- ✅ 执行测试并生成报告 (`reports/`)
- ✅ 补充验收标准 (`review/*/acceptance.md`)
- ✅ 提交测试反馈 (`review/*/feedback/`)
**可读但不可写：**
- 👁 业务代码 (`projects/*/src/`) —— 只读，理解逻辑编写测试
- 👁 技术文档 (`projects/*/docs/`) —— 只读，了解接口设计
- 👁 项目级文档 (`docs/`) —— 只读，了解系统架构
- 👁 训练数据 (`data/`) —— 只读，了解数据分布
- 👁 共享资源 (`shared/`) —— 只读，了解工具函数
- 👁 任务描述 (`review/*/task.md`) —— 只读，了解测试目标
- 👁 验收标准 (`review/*/acceptance.md`) —— 只读，了解测试要求
**禁止操作：**
- ❌ 修改业务代码 (`projects/*/src/`)
- ❌ 修改技术文档 (`projects/*/docs/`)
- ❌ 修改共享资源 (`shared/`)
- ❌ 修改影响评估 (`review/*/impact.md`)
- ❌ 修改开发工具 (`tools/`)
- ❌ 修改测试反馈 (`review/*/feedback/`)
### 人类负责人
**职责范围：**
- ✅ 可以修改所有目录
- ✅ 审核 AI 输出质量
- ✅ 解决 AI 之间的冲突
- ✅ 最终决策和验收
---
## 工作流程
```
┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ 需求分析 │ ───→ │ 架构设计 │ ───→ │ 开发实现 │ ───→ │ 测试验证 │ ───→ │ 验收确认 │
│ (Arch AI) │ │ (Arch AI) │ │ (Dev AI) │ │ (QA AI) │ │ (人类) │
└──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘ └──────────────┘
↑ │
│ Bug → 修复 │
└──────────────────────┘
(最多 2 轮)
```
### 详细流程说明
**1. 需求分析阶段**
- Arch AI 分析用户需求，输出产品规划
- 输出: `docs/01_产品需求/PRD.md`、`review/{task_id}/task.md`
**2. 架构设计阶段**
- Arch AI 设计系统架构，技术选型
- 输出: `docs/02_系统架构/`、`review/{task_id}/impact.md`、`review/{task_id}/acceptance.md`
**3. 开发实现阶段**
- Dev AI 读取任务描述和验收标准，编写代码 + 文档
- 输出: `projects/*/src/`, `projects/*/docs/`
**4. 测试验证阶段**
**2. 开发实现阶段**
- Dev AI 读取任务描述，编写代码 + 文档
- 同时输出验收标准和变更影响范围
- 输出: `projects/*/src/`, `projects/*/docs/`, `review/{task_id}/impact.md`, `review/{task_id}/acceptance.md`
**3. 测试验证阶段**
- QA AI 根据验收标准编写测试，执行测试，生成报告
- 测试反馈写入 `review/{task_id}/feedback/round{round}.md`
- 输出: `projects/*/tests/`, `reports/test-results/`, `review/{task_id}/feedback/`
### 缺陷修复循环
| 规则 | 说明 |
|------|------|
| 最大轮次 | 3 轮（初始测试 + 最多 2 轮修复复查） |
| 循环范围 | 测试失败 → Dev AI 修复 → QA AI 复查 |
| 跳过项 | 修复轮次中 Dev AI **只修 Bug**，不重新写 acceptance/impact |
| 触发升级 | 第 3 轮仍有 BLOCKER 或 HIGH 级别 Bug → 暂停流转，待人类裁决 |
```
Round 1: Dev 开发 → QA 测试 → 3 个 Bug
Round 2: Dev 修复 → QA 复查 → 1 个 Bug（MEDIUM）
Round 3: Dev 修复 → QA 复查 → 0 个 Bug ✅ → 提交人类验收
```
如果 Round 3 仍有 BLOCKER/HIGH：
```
Round 3: Dev 修复 → QA 复查 → 仍 1 个 HIGH → ⚠️ 升级给人类裁决
```
**4. 验收确认阶段**
- 人类审核测试报告，确认任务完成或驳回
- 确认后任务状态更新为 DONE，移入 `review/archived/`
---
## 目录权限矩阵
> **图例**：`-` = 无权访问 &nbsp;&nbsp; `R` = 只读 &nbsp;&nbsp; `W` = 可写（含读） &nbsp;&nbsp; `RW` = 读写
| 目录路径 | Arch AI | Dev AI | QA AI | 人类 |
|---------|---------|--------|-------|------|
| `.ai/` | `R` | `-` | `-` | `RW` |
| `docs/` | `RW` | `RW` | `R` | `RW` |
| `tools/` | `RW` | `RW` | `-` | `RW` |
| `data/` | `RW` | `RW` | `R` | `RW` |
| `shared/` | `RW` | `RW` | `R` | `RW` |
| `projects/*/src/` | `RW` | `RW` | `R` | `RW` |
| `projects/*/tests/` | `R` | `-` | `RW` | `RW` |
| `projects/*/docs/` | `RW` | `RW` | `R` | `RW` |
| `review/*/task.md` | `RW` | `R` | `R` | `RW` |
| `review/*/acceptance.md` | `RW` | `RW` | `RW` | `RW` |
| `review/*/impact.md` | `RW` | `RW` | `-` | `RW` |
| `review/*/feedback/` | `R` | `R` | `RW` | `RW` |
| `reports/` | `R` | `-` | `RW` | `RW` |
| `.github/` | `-` | `-` | `-` | `RW` |
> **解析优先级**：当同一条路径被多个规则匹配时，`forbidden > read_only > allowed`。禁止规则永远优先。
>
> **默认行为**：任何未出现在上表中的路径，默认禁止所有 AI 访问（等效于 `-`）。
---
## 沟通规范
### Dev AI → QA AI
在 `review/{task_id}/` 目录提交：
- **验收标准** (`acceptance.md`) - 明确测试目标
- **变更影响范围** (`impact.md`) - 指导回归测试
- **环境准备** 参考项目级 `ENVIRONMENT.md`
### QA AI → Dev AI
在 `review/{task_id}/feedback/` 目录提交：
- **测试结果报告** (`round{round}.md`)
- **Bug清单** - 列出问题和严重程度
- **改进建议** - 代码优化建议
---
## 命名规范
### 项目命名
```
P01_项目名称 # P01 表示项目编号
```
### 任务编号
```
P01-001 # P01 项目编号 + 001 任务编号
```
### 分支命名
```
feature/P01-001-login # 功能开发
bugfix/P01-001-password # Bug修复
test/P01-001-testcases # 测试用例
```
### 提交信息
```
feat(P01-001): 实现用户登录功能
fix(P01-001): 修复密码验证问题
docs(P01-001): 更新接口文档
test(P01-001): 添加登录测试用例
```
---
## AI 配置文件说明
| 文件 | 说明 |
|------|------|
| `.ai/config/architect.json` | Arch AI 配置（权限、职责） |
| `.ai/config/coder.json` | Dev AI 配置（权限、职责） |
| `.ai/config/tester.json` | QA AI 配置（权限、职责） |
| `.ai/config/workflow.json` | 工作流配置（阶段、触发器） |
| `.ai/prompts/coding/` | 编码提示词模板 |
| `.ai/prompts/testing/` | 测试提示词模板 |
EOF
# 3. 创建 README.md
cat > README.md << 'EOF'
# AI 协作项目
一个"人+3AI"协作模式的 AI 辅助编程项目仓库。
---
## 目录结构
```
.
├── AGENTS.md # AI角色定义+权限约定+工作流
├── README.md
├── .gitignore
├── .ai/ # AI协作核心配置
│ ├── config/
│ │ ├── architect.json # Arch AI 配置
│ │ ├── coder.json # Dev AI 配置
│ │ ├── tester.json # QA AI 配置
│ │ └── workflow.json # 工作流配置
│ └── prompts/
│ ├── coding/ # 编码提示词模板
│ └── testing/ # 测试提示词模板
├── docs/ # 项目级总体文档
├── tools/ # 开发工具脚本
├── data/ # 训练数据
├── projects/ # 项目代码
│ ├── P01_app/ # 主应用项目
│ │ ├── src/ # 业务代码 (Dev AI)
│ │ ├── tests/ # 测试代码 (QA AI)
│ │ ├── docs/ # 项目文档 (Dev AI)
│ │ └── ENVIRONMENT.md # 项目级环境准备
│ └── P02_training/ # AI训练项目
│ ├── src/
│ ├── tests/
│ ├── docs/
│ └── ENVIRONMENT.md
├── review/ # 交接中心
│ ├── active/ # 活跃任务
│ └── archived/ # 已完成任务（按季度归档）
├── shared/ # 共享资源
│ ├── scripts/
│ ├── templates/
│ └── utils/
├── reports/ # 统一报告
│ ├── test-results/
│ └── quality-reports/
└── .github/ # CI/CD配置
└── workflows/
```
---
## 团队角色
| 角色 | 是谁 | 干什么 | 不干什么 |
|------|------|--------|----------|
| **人类负责人** | 你 | 下指令、审阅、做决策、定验收标准 | 不写代码、不写测试 |
| **Arch AI** | Claude/TRAE/元宝等 | 需求分析、架构设计、技术选型、跨模块协调 | 不写测试 |
| **Dev AI** | Claude/TRAE/元宝等 | 写业务代码+文档、修bug、写impact | 不动tests/、不跑测试 |
| **QA AI** | 扣子编程AI | 写测试、跑测试、写反馈 | 不动src/、不改业务代码 |
---
## 工作流程
1. **Arch AI** 分析需求，输出 `docs/01_产品需求/PRD.md` 和 `review/active/P01-001/task.md`
2. **Arch AI** 设计架构，输出 `docs/02_系统架构/`、`acceptance.md`、`impact.md`
3. **Dev AI** 在 `projects/P01_app/src/` 写代码，在 `docs/` 写文档
4. **你**审一眼，没问题就触发QA AI
5. **QA AI** 读 `task.md` + `acceptance.md` + `impact.md`，按 `ENVIRONMENT.md` 准备环境，在 `tests/` 写测试并执行，写 `feedback/round1.md`
6. **有bug** → 你看反馈 → 让Dev AI修 → 回到步骤3（round2）
**通过** → 你确认 → 任务关闭，报告归档到 `reports/`
---
## 任务状态流转
```
TODO → IN_PROGRESS → REVIEW → DONE → ARCHIVED（移入archived/季度目录）
```
`task.md` 中添加状态字段：
```
status: TODO | IN_PROGRESS | REVIEW | DONE | ARCHIVED
```
EOF
# 4. 创建 .gitignore
cat > .gitignore << 'EOF'
# Dependencies
node_modules/
vendor/
__pycache__/
*.pyc
*.pyo
venv/
# Build outputs
dist/
build/
*.log
*.out
# IDE
.vscode/
.idea/
*.swp
*.swo
# OS
Thumbs.db
.DS_Store
# Environment variables
.env
.env.local
.env.*.local
.env.production
# Test reports
reports/test-results/*.json
reports/test-results/*.xml
# Model files
models/
*.pt
*.pth
*.onnx
# Data files
data/
*.csv
*.jsonl
# Temporary files
*.tmp
*.temp
*.bak
EOF
# 5. 创建 AI 配置文件（新版：含 read_only_paths、forbidden_paths、description）
cat > .ai/config/architect.json << 'EOF'
{
"name": "Arch AI",
"role": "架构设计师",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"需求分析和产品规划",
"系统架构设计",
"技术选型和评估",
"跨模块协调和集成",
"编写架构文档",
"定义验收标准",
"评估变更影响",
"维护共享资源",
"维护开发工具",
"维护训练数据",
"指导 Dev AI 和 QA AI 工作"
],
"allowed_paths": [
"docs/",
"shared/",
"projects/*/src/",
"projects/*/docs/",
"review/*/acceptance.md",
"review/*/impact.md",
"review/*/task.md",
"tools/",
"data/"
],
"read_only_paths": [
".ai/",
"projects/*/tests/",
"reports/",
"review/*/feedback/"
],
"forbidden_paths": [],
"prompt_templates": {
"architecture": ".ai/prompts/architecture/",
"documentation": ".ai/prompts/architecture/"
}
}
EOF
cat > .ai/config/coder.json << 'EOF'
{
"name": "Dev AI",
"role": "代码开发者",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"编写业务代码",
"生成技术文档",
"定义验收标准",
"评估变更影响",
"维护共享资源"
],
"allowed_paths": [
"projects/*/src/",
"projects/*/docs/",
"shared/",
"review/*/acceptance.md",
"review/*/impact.md"
],
"read_only_paths": [
"review/*/task.md",
"review/*/feedback/"
],
"forbidden_paths": [
"projects/*/tests/",
"reports/"
],
"prompt_templates": {
"coding": ".ai/prompts/coding/",
"documentation": ".ai/prompts/coding/"
}
}
EOF
cat > .ai/config/tester.json << 'EOF'
{
"name": "QA AI",
"role": "测试工程师",
"description": "allowed_paths = 可写路径（含读）；read_only_paths = 只读路径；不在二者中的路径禁止访问。详细权限见 AGENTS.md 权限矩阵。",
"responsibilities": [
"编写测试用例",
"执行测试",
"生成测试报告",
"提供反馈"
],
"allowed_paths": [
"projects/*/tests/",
"reports/",
"review/*/acceptance.md",
"review/*/feedback/"
],
"read_only_paths": [
"projects/*/src/",
"projects/*/docs/",
"docs/",
"data/",
"shared/",
"review/*/task.md",
"review/*/acceptance.md"
],
"forbidden_paths": [
".ai/",
"tools/",
"review/*/impact.md",
"review/*/feedback/"
],
"prompt_templates": {
"testing": ".ai/prompts/testing/"
}
}
EOF
cat > .ai/config/workflow.json << 'EOF'
{
"workflow": "human-ai-collaboration",
"roles": ["human", "arch-ai", "dev-ai", "qa-ai"],
"stages": [
{
"name": "需求分析",
"actor": "arch-ai",
"output": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"]
},
{
"name": "架构设计",
"actor": "arch-ai",
"input": ["docs/01_产品需求/PRD.md", "review/{task_id}/task.md"],
"output": ["docs/02_系统架构/", "review/{task_id}/impact.md", "review/{task_id}/acceptance.md"]
},
{
"name": "开发实现",
"actor": "dev-ai",
"input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"],
"output": ["projects/*/src/", "projects/*/docs/"]
},
{
"name": "测试验证",
"actor": "qa-ai",
"input": ["review/{task_id}/task.md", "review/{task_id}/acceptance.md"],
"output": ["projects/*/tests/", "reports/test-results/", "review/{task_id}/feedback/round{round}.md"]
},
{
"name": "验收确认",
"actor": "human",
"input": ["review/{task_id}/feedback/", "reports/test-results/"]
}
],
"retry": {
"max_rounds": 3,
"loop": ["测试验证", "开发实现"],
"escalation": {
"trigger": "第 3 轮测试仍有 BLOCKER 或 HIGH 级别 Bug",
"action": "暂停任务流转，等待人类负责人裁决"
},
"skip_acceptance_on_retry": true
},
"ci_triggers": {
"on_push_to_main": ["run-tests", "generate-reports"],
"on_pr_open": ["run-tests", "code-review"],
"on_task_update": ["notify-qa-ai"]
}
}
EOF
# 6. 创建提示词模板
mkdir -p .ai/prompts/architecture
cat > .ai/prompts/coding/README.md << 'EOF'
# Dev AI 提示词库
| 文件 | 说明 |
|------|------|
| [code-style.md](code-style.md) | 代码风格、命名规范、目录组织 |
| [doc-template.md](doc-template.md) | impact.md / acceptance.md 等文档模板 |
EOF
cat > .ai/prompts/testing/README.md << 'EOF'
# QA AI 提示词库
| 文件 | 说明 |
|------|------|
| [bug-report.md](bug-report.md) | 测试反馈 / Bug 报告模板与格式规范 |
EOF
cat > .ai/prompts/architecture/README.md << 'EOF'
# Arch AI 提示词库
| 文件 | 说明 |
|------|------|
| [architecture-design.md](architecture-design.md) | 架构设计模板与规范 |
| [tech-selection.md](tech-selection.md) | 技术选型评估模板 |
EOF
cat > .ai/prompts/coding/code-style.md << 'EOF'
# Dev AI 代码风格规范
## 适用技术栈
| 层 | 技术 | 语言 |
|-----|------|------|
| 前端 | Taro 4 + React 18 | TypeScript 5.x |
| 样式 | Tailwind CSS 4 | — |
| 后端 | NestJS 10 | TypeScript 5.x |
| 训练 | PyTorch 2.0 | Python 3.10+ |
---
## 1. 文件命名
| 类型 | 规则 | 示例 |
|------|------|------|
| 页面组件 | kebab-case | `error-detail.tsx` |
| UI 组件 | kebab-case | `button.tsx` |
| 工具函数 | kebab-case | `format-date.ts` |
| 类型定义 | kebab-case | `error-entry.d.ts` |
| NestJS 模块 | kebab-case | `auth.module.ts` |
| Python 模块 | snake_case | `data_loader.py` |
## 2. 目录组织（前端）
```
src/
├── pages/{page-name}/ # 页面 —— 一个目录一个页面
│ ├── index.tsx
│ ├── index.config.ts
│ └── index.css
├── components/ # 通用组件
│ └── {component-name}/
│ └── index.tsx
├── lib/ # 工具函数、hooks
├── types/ # 全局类型声明
├── server/ # NestJS 后端
└── config/ # Taro 构建配置
```
## 3. 目录组织（NestJS 后端）
```
src/server/src/
├── modules/{name}/ # 一个模块一个目录
│ ├── {name}.module.ts
│ ├── {name}.controller.ts
│ ├── {name}.service.ts
│ ├── dto/
│ └── entities/
├── common/ # 共享：拦截器、守卫、管道
└── main.ts
```
## 4. 命名风格
**TypeScript：**
- 组件：PascalCase —— `ErrorCard`
- 函数/变量：camelCase —— `getUserProfile`
- 常量：UPPER_SNAKE —— `MAX_PAGE_SIZE`
- 接口/类型：PascalCase —— `ErrorEntry`
**Python：**
- 类：PascalCase —— `DataLoader`
- 函数/变量：snake_case —— `load_dataset`
- 常量：UPPER_SNAKE —— `BATCH_SIZE`
## 5. 导入顺序（TypeScript）
```
1. 第三方库
2. Taro 相关
3. 项目内部（@/ 别名）
4. 相对路径
5. 样式文件
```
## 6. 组件规范
- 优先使用函数组件，不用 class 组件
- 一个文件只有一个 export default 组件
- 组件 props 必须声明类型接口
- 跨端兼容：避免使用 `document`、`window`（用 Taro API 代替）
## 7. API 调用规范
- 前端统一使用 `@/network.ts` 中的 `Network.request`，不要直接调用 `Taro.request`
- 后端Controller 只做参数校验和路由，业务逻辑放在 Service
- API 响应统一使用 Envelope 格式 `{ code, msg, data }`
## 8. 不能做的事
- 不要在 `src/` 下写测试文件（测试在 `tests/`）
- 不要引入未经 package.json 声明的依赖
- 不要在组件中硬编码后端地址（用 `PROJECT_DOMAIN` 全局变量）
EOF
cat > .ai/prompts/coding/doc-template.md << 'EOF'
# Dev AI 文档模板
下面三个模板用于 Dev AI 在 `review/{task_id}/` 下产出标准化文件。
---
## A. impact.md 模板（变更影响范围）
```markdown
# {TASK_ID} - 变更影响范围
## 修改的文件
| 文件路径 | 修改类型 | 影响等级 |
|---------|---------|---------|
| projects/P01_soc_sw_app/src/server/src/modules/auth/auth.service.ts | 新增 | HIGH |
| projects/P01_soc_sw_app/src/server/src/modules/auth/dto/login.dto.ts | 新增 | MEDIUM |
> 影响等级：HIGH=核心逻辑变更 | MEDIUM=新增文件 | LOW=注释/格式
## 影响的功能模块
- [x] 用户认证模块
- [ ] 芯片验证模块（无影响）
## 需要回归测试的场景
- 场景1: 用户登录成功流程
- 场景2: 密码错误返回 401
- 场景3: Token 过期后刷新
## 环境依赖变更
- 新增依赖: bcrypt, @nestjs/jwt
- 数据库迁移: 新增 users 表
```
**要点：**
- `修改的文件` 必须使用从仓库根目录开始的完整路径
- 影响等级要实事求是，不要全写 HIGH
- `需要回归测试的场景` 要写**用户视角**的场景，不是代码内部细节
---
## B. acceptance.md 模板（验收标准）
```markdown
# {TASK_ID} - 验收标准
## 功能验收
- [ ] 用户可以注册新账户（邮箱+密码）
- [ ] 密码强度不足时提示明确错误信息
- [ ] 登录成功返回有效 JWT Token
## 非功能验收
- [ ] API 响应时间 < 200ms
- [ ] 密码使用 bcrypt 加密存储
- [ ] JWT Token 有效期 24 小时
## 测试覆盖要求
- 单元测试覆盖率: >= 80%
- 集成测试覆盖率: >= 60%
- E2E 测试场景: >= 3 个
## 验收通过条件
- 所有功能点验证通过
- 测试覆盖率达标
- 无重大安全漏洞
```
**要点：**
- 功能验收用「用户可以…」句式，让 QA AI 和人类都能看懂
- 每个功能点对应 task.md 里的一项交付物
- 非功能验收写具体的可测量指标，不要写「性能好」「代码整洁」
---
## C. 没有 task.md 模板
task.md 由人类负责人创建，Dev AI 只读不写。Dev AI 如需补充技术细节，写在 impact.md 的「技术备注」段落中，不要直接修改 task.md。
EOF
cat > .ai/prompts/testing/bug-report.md << 'EOF'
# QA AI Bug 报告模板
以下模板用于 QA AI 在 `review/{task_id}/feedback/round{round}.md` 中提交测试反馈。
---
## 模板
```markdown
# {TASK_ID} - 第 {N} 轮测试反馈
## 基本信息
- 测试时间: YYYY-MM-DD
- 测试项目: P01_soc_sw_app / P02_soc_sw_training / P03_soc_sw_web
- 测试环境: Node 20.x / Python 3.10
## 测试结果概览
| 指标 | 数值 |
|------|------|
| 测试用例总数 | N |
| 通过 | N |
| 失败 | N |
| 跳过 | N |
| 代码覆盖率 | XX% |
## 失败用例清单
### Bug #1: {简短标题}
- **严重程度**: BLOCKER / HIGH / MEDIUM / LOW
- **涉及文件**: `projects/...`（完整路径）
- **测试场景**: 用户登录时输入正确密码
- **预期结果**: 返回 200 和 JWT Token
- **实际结果**: 返回 500 Internal Server Error
- **复现步骤**:
1. POST /api/auth/login
2. body: {"email": "test@example.com", "password": "correct"}
- **建议修复**: 检查 auth.service.ts 第 42 行的异常处理
### Bug #2: ...
（同上格式）
## 改进建议（非 Bug）
- 建议 1: 登录接口缺少限流保护
- 建议 2: 密码重置的邮件模板可以更友好
## 下一步
- [ ] Dev AI 修复上述 Bug 后，QA AI 进行第 {N+1} 轮测试
- [ ] 如第 3 轮仍未通过，升级给人类负责人裁决
```
---
## 严重程度定义
| 级别 | 含义 | 举例 |
|------|------|------|
| BLOCKER | 核心功能不可用，无法继续测试 | 登录接口直接崩溃、数据库连不上 |
| HIGH | 功能逻辑错误，用户无法正常使用 | 登录成功但不返回 Token |
| MEDIUM | 功能可用但与预期有偏差 | 返回的日期格式不对、错误码不对 |
| LOW | 不影响功能的瑕疵 | 提示文案不友好、缺少空值校验 |
## 规则
1. **每轮反馈用新文件**：`round1.md` → `round2.md` → `round3.md`
2. **最多 3 轮**：第 3 轮仍有 BLOCKER/HIGH Bug → 在报告中标注「建议人类负责人介入」
3. **涉及文件必须用完整路径**：从仓库根目录开始，方便 Dev AI 定位
4. **改进建议不要超过 3 条**：聚焦最重要的
EOF
# 7. 创建示例任务
cat > review/active/P01-001/task.md << 'EOF'
# P01-001 - 示例任务
## 任务信息
- 任务编号：P01-001
- 项目：P01_app
- 创建时间：2026-05-22
- 负责人：Dev AI
- 状态：TODO
## 任务描述
这是一个示例任务，展示任务单的结构。实际使用时请替换为真实需求。
## 交付物
- `projects/P01_app/src/` 下的业务代码
- `projects/P01_app/docs/` 下的技术文档
EOF
cat > review/active/P01-001/acceptance.md << 'EOF'
# P01-001 - 验收标准
## 功能验收
- [ ] 功能点 1
- [ ] 功能点 2
## 非功能验收
- [ ] API 响应时间 < 200ms
## 测试覆盖要求
- 单元测试覆盖率: >= 80%
## 验收通过条件
- 所有功能点验证通过
- 测试覆盖率达标
EOF
cat > review/active/P01-001/impact.md << 'EOF'
# P01-001 - 变更影响范围
## 修改的文件
| 文件路径 | 修改类型 | 影响等级 |
|---------|---------|---------|
| projects/P01_app/src/example.ts | 新增 | HIGH |
## 影响的功能模块
- [x] 示例模块
## 需要回归测试的场景
- 场景1: 示例功能正常使用
## 环境依赖变更
- 无
EOF
cat > review/active/P01-001/feedback/round1.md << 'EOF'
# P01-001 - 第一轮测试反馈
## 基本信息
- 测试时间: 2026-05-22
- 测试项目: P01_app
- 测试环境: 待配置
## 测试结果概览
| 指标 | 数值 |
|------|------|
| 测试用例总数 | 0 |
| 通过 | 0 |
| 失败 | 0 |
| 跳过 | 0 |
| 代码覆盖率 | 0% |
## 反馈
待 Dev AI 完成开发后执行测试
EOF
# 8. 创建 P01-002 示例任务（占位）
mkdir -p review/active/P01-002/feedback
cat > review/active/P01-002/task.md << 'EOF'
# P01-002 - 待创建
## 任务信息
- 任务编号：P01-002
- 项目：P01_app
- 状态：TODO
## 任务描述
待人类负责人创建
EOF
cat > review/active/P01-002/acceptance.md << 'EOF'
# P01-002 - 验收标准
待 Dev AI 补充
EOF
cat > review/active/P01-002/impact.md << 'EOF'
# P01-002 - 变更影响范围
待 Dev AI 补充
EOF
echo "# feedback" > review/active/P01-002/feedback/README.md
# 9. 创建 CROSS-001 跨项目任务（占位）
mkdir -p review/active/CROSS-001/feedback
cat > review/active/CROSS-001/task.md << 'EOF'
# CROSS-001 - 跨项目任务
## 任务信息
- 任务编号：CROSS-001
- 项目：多个项目
- 状态：TODO
## 任务描述
待人类负责人创建
EOF
cat > review/active/CROSS-001/acceptance.md << 'EOF'
# CROSS-001 - 验收标准
待 Dev AI 补充
EOF
cat > review/active/CROSS-001/impact.md << 'EOF'
# CROSS-001 - 变更影响范围
待 Dev AI 补充
EOF
echo "# feedback" > review/active/CROSS-001/feedback/README.md
# 10. 创建项目环境文件
cat > projects/P01_app/ENVIRONMENT.md << 'EOF'
# P01_app - 环境准备
## 依赖
- Node.js >= 20.x
- pnpm >= 9.0.0
## 安装
pnpm install
## 运行
pnpm dev
EOF
cat > projects/P02_training/ENVIRONMENT.md << 'EOF'
# P02_training - 环境准备
## 依赖
- Python >= 3.10
- PyTorch >= 2.0
- CUDA >= 11.8 (GPU训练)
## 安装
pip install -r requirements.txt
EOF
# 11. 创建占位文件
echo "# src" > projects/P01_app/src/README.md
echo "# tests" > projects/P01_app/tests/README.md
echo "# docs" > projects/P01_app/docs/README.md
echo "# src" > projects/P02_training/src/README.md
echo "# tests" > projects/P02_training/tests/README.md
echo "# docs" > projects/P02_training/docs/README.md
echo "# scripts" > shared/scripts/README.md
echo "# templates" > shared/templates/README.md
echo "# utils" > shared/utils/README.md
echo "# test-results" > reports/test-results/README.md
echo "# quality-reports" > reports/quality-reports/README.md
echo "# workflows" > .github/workflows/README.md
echo "# 2026-Q2 archived tasks" > review/archived/2026-Q2/README.md
echo "✅ AI 协作框架创建成功！"
echo "📖 请阅读 AGENTS.md 了解协作规则"
echo "🚀 在 review/active/ 下创建你的第一个真实任务开始开发"
```
## 使用场景
**何时调用此 skill：**
- ✅ 启动新的 AI 辅助编程项目
- ✅ 需要建立标准化的 AI 协作流程
- ✅ 团队开始使用"1 人+2AI"模式
**不适用场景：**
- ❌ 纯人工开发项目
- ❌ 已有现成的协作框架
## 后续步骤
skill 执行后：
1. 阅读 `AGENTS.md` 了解协作规则和权限体系
2. 检查 `review/active/P01-001/` 示例任务结构
3. 根据实际需求修改 `AGENTS.md` 中的技术栈说明
4. 在 `review/active/` 下创建第一个真实任务
5. 开始协作开发
---
**Version**: 3.0
**Created**: 2026-05-23
**Updated**: 2026-05-23
**Based On**: SoC_SW AI Programming Project
**Changes from v2.2**:
- 新增 Arch AI（架构AI）角色，形成"1 人+3AI"协作模式
- 新增 .ai/config/architect.json 配置文件
- 新增架构设计阶段，工作流从 4 阶段扩展为 5 阶段
- 权限矩阵增加 Arch AI 列
- 新增 .ai/prompts/architecture/ 提示词目录
Reference in New Issue Copy Permalink