John Qiu
7eed2b8f10
Karpathy 四原则融合到 req 技能工作流 (REQ-20260421-0003): - dev-coding: 新增 Step 0「验证优先」(Goal-Driven Execution) - dev-review: 五视角 → 六视角，新增 Scope 审计者 (Simplicity + Surgical) - review-checklist/general: 新增 Karpathy 反模式速查表 - karpathy-guidelines-plugin: 新增独立插件，含四原则全文 + 与 req 工作流映射
611 lines
14 KiB
Markdown
611 lines
14 KiB
Markdown
---
|
||
name: dev-coding
|
||
description: 软件编码开发技能。用于代码编写、功能实现、重构优化。集成 ai-proj CLI 进行任务管理和进度跟踪。核心支持 Go 后端 + Vue/React 前端开发。
|
||
---
|
||
|
||
# 软件编码开发 Skill (dev-coding)
|
||
|
||
## 概述
|
||
|
||
本技能用于软件编码实现，核心覆盖：
|
||
- Go 后端 (Gin + GORM)
|
||
- Vue 3 / React 前端
|
||
|
||
集成 **ai-proj CLI** 进行任务管理。
|
||
|
||
**不包含**（由其他技能/插件负责）：
|
||
- 开发设计（API 契约、任务拆分）→ `req-design`
|
||
- 代码评审 → `dev-review`（批次2）
|
||
- iOS 开发 → `dev-ios`（插件）
|
||
- Android 开发 → `dev-android`（插件）
|
||
- MCP 开发 → `dev-mcp`（插件）
|
||
|
||
---
|
||
|
||
## ai-proj 任务管理
|
||
|
||
### 开发任务工作流
|
||
|
||
```
|
||
1. 查看/创建任务 → 2. 启动任务 → 3. 编码实现 → 4. 完成任务 → 5. 记录文档
|
||
```
|
||
|
||
### 任务操作速查
|
||
|
||
| 操作 | CLI 命令 | 说明 |
|
||
|------|----------|------|
|
||
| 查看任务列表 | `ai-proj task list` | 查看项目所有任务 |
|
||
| 创建任务 | `ai-proj task create` | 创建新任务 |
|
||
| 创建子任务 | `ai-proj task create --parent-id` | 分解任务 |
|
||
| 启动任务 | `ai-proj task start --id` | 开始执行 |
|
||
| 完成任务 | `ai-proj task complete --id` | 标记完成 |
|
||
| 更新任务 | `ai-proj task update --id` | 更新状态/描述 |
|
||
| 查看详情 | `ai-proj task get --id` | 完整任务信息 |
|
||
| 记录文档 | `ai-proj task append-doc --id` | 附加文档 |
|
||
|
||
### 开始新任务
|
||
|
||
```bash
|
||
# 1. 查看任务列表
|
||
ai-proj task list --status todo,in_progress
|
||
|
||
# 2. 启动任务
|
||
ai-proj task start --id <taskId>
|
||
|
||
# 3. 完成后
|
||
ai-proj task complete --id <taskId>
|
||
|
||
# 4. 记录文档
|
||
ai-proj task append-doc --id <taskId> --content "实现说明"
|
||
```
|
||
|
||
---
|
||
|
||
## 项目类型速查
|
||
|
||
### 当前项目生态
|
||
|
||
| 项目 | 类型 | 后端 | 前端 |
|
||
|------|------|------|------|
|
||
| TWMS | 仓储物流 | Go+Gin+MySQL | Vue 3 |
|
||
| AI-Proj | 项目管理 | Go+Gin+PostgreSQL | React 18 |
|
||
| DICIAI | 进销存SaaS | Go+Gin+MySQL | Vue 3 |
|
||
|
||
---
|
||
|
||
## Step 0：验证优先（Karpathy: Goal-Driven Execution）
|
||
|
||
**编写任何代码前，必须先写验证脚本。** 规则来源：Karpathy "Goal-Driven Execution" 原则。
|
||
|
||
> "Define success criteria. Loop until verified."
|
||
> "Fix the bug" → "Write a test that reproduces it, then make it pass"
|
||
|
||
### 执行流程
|
||
|
||
```
|
||
① 写验证脚本（按类型选择）
|
||
② 运行一遍，确认全部 FAIL（证明功能确实不存在 / bug 确实存在）
|
||
③ 编码实现
|
||
④ 再次运行验证脚本，全部 PASS → 完成
|
||
```
|
||
|
||
### 后端验证脚本模板
|
||
|
||
实现 API 前，先写好所有 curl 命令并标注期望结果：
|
||
|
||
```bash
|
||
# 验证脚本：REQ-XXXX [功能名]
|
||
BASE="http://localhost:8080"
|
||
TOKEN="<JWT>"
|
||
|
||
echo "=== T1: 正常创建 ==="
|
||
curl -s -X POST "$BASE/api/v1/xxx" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{"name":"test"}' | jq '.code'
|
||
# 期望: 0
|
||
|
||
echo "=== T2: 缺少必填字段 ==="
|
||
curl -s -X POST "$BASE/api/v1/xxx" \
|
||
-H "Authorization: Bearer $TOKEN" \
|
||
-d '{}' | jq '.code'
|
||
# 期望: 非 0（参数错误）
|
||
|
||
echo "=== T3: 跨租户访问 ==="
|
||
curl -s -X GET "$BASE/api/v1/xxx/999" \
|
||
-H "Authorization: Bearer $TOKEN_OTHER_TENANT" | jq '.code'
|
||
# 期望: 403
|
||
```
|
||
|
||
**先运行 → 全部 FAIL → 编码 → 再次运行 → 全部 PASS**
|
||
|
||
### 前端验证脚本模板
|
||
|
||
实现页面前，先列出所有 `data-testid` 和期望的 DOM 状态：
|
||
|
||
```
|
||
验证清单（编码前先确认这些状态不存在 / 行为不正确）：
|
||
- data-testid="xxx-btn-submit" 点击 → 列表刷新，行数增加 1
|
||
- data-testid="xxx-table" 行数 === API 返回 total
|
||
- data-testid="xxx-input-name" 空值提交 → 显示「请输入名称」提示
|
||
```
|
||
|
||
### 与 VP 三件套的关系
|
||
|
||
| VP 协议 | 验证优先对应 |
|
||
|---------|------------|
|
||
| VP-Data | 先在环境建好测试数据（curl 确认成功） |
|
||
| VP-Steps | **即为本节验证脚本** — 编码前写好，编码后执行 |
|
||
| VP-Pass | 验证脚本每条命令的期望输出值 |
|
||
|
||
---
|
||
|
||
## Go 后端开发
|
||
|
||
### 分层架构
|
||
|
||
```
|
||
backend/
|
||
├── cmd/main.go # 入口点
|
||
├── internal/
|
||
│ ├── controller/handlers/ # HTTP 处理层
|
||
│ ├── biz/services/ # 业务逻辑层
|
||
│ ├── store/database/ # 数据访问层
|
||
│ └── middleware/ # 中间件
|
||
├── pkg/
|
||
│ ├── model/ # 数据模型
|
||
│ ├── errno/ # 错误定义
|
||
│ ├── api/ # API 类型
|
||
│ └── util/ # 工具函数
|
||
└── configs/migrations/ # 配置和迁移
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
```go
|
||
// 包声明和导入组织
|
||
package main
|
||
|
||
import (
|
||
// 标准库
|
||
"context"
|
||
"fmt"
|
||
|
||
// 第三方
|
||
"github.com/gin-gonic/gin"
|
||
|
||
// 项目内部
|
||
"project/internal/pkg/errno"
|
||
)
|
||
|
||
// 错误处理 (Errno 模式)
|
||
if err != nil {
|
||
core.WriteResponse(c, errno.ErrBind, nil)
|
||
return
|
||
}
|
||
|
||
// 接口定义
|
||
type IStore interface {
|
||
Users() UserStore
|
||
}
|
||
|
||
// 服务注入
|
||
type userBiz struct {
|
||
ds store.IStore
|
||
}
|
||
|
||
func NewUserBiz(ds store.IStore) *userBiz {
|
||
return &userBiz{ds: ds}
|
||
}
|
||
```
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 构建
|
||
make build
|
||
go build -o ./_output/main ./cmd/main.go
|
||
|
||
# 运行
|
||
./_output/main --config ./configs/config.yaml
|
||
|
||
# 测试
|
||
make test
|
||
go test -v ./...
|
||
|
||
# 代码检查
|
||
make lint
|
||
golangci-lint run
|
||
|
||
# Swagger 文档
|
||
make swagger
|
||
swag init -g cmd/main.go
|
||
```
|
||
|
||
### 数据库模型
|
||
|
||
```go
|
||
type UserM struct {
|
||
Id int64 `gorm:"column:id;primary_key"`
|
||
Username string `gorm:"column:username;not null"`
|
||
CreateTime int64 `gorm:"column:create_time"`
|
||
UpdateTime int64 `gorm:"column:update_time"`
|
||
DeletedAt soft_delete.DeletedAt `gorm:"column:deleted_at"`
|
||
}
|
||
|
||
func (m *UserM) TableName() string { return "users" }
|
||
|
||
func (m *UserM) BeforeCreate(tx *gorm.DB) error {
|
||
m.CreateTime = time.Now().Unix()
|
||
m.UpdateTime = m.CreateTime
|
||
return nil
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## 前端 data-testid 规范
|
||
|
||
编写或修改前端组件时，**所有可交互元素必须加 `data-testid`**。
|
||
|
||
**命名格式:** `<模块>-<元素类型>[-<标识>]`
|
||
|
||
```vue
|
||
<!-- ✅ 正确 -->
|
||
<a-input data-testid="product-input-name" v-model:value="form.name" placeholder="商品名称" />
|
||
<a-button data-testid="product-btn-submit" type="primary">创建商品</a-button>
|
||
<a-select data-testid="product-select-brand" v-model:value="form.brandId" />
|
||
<a-table data-testid="product-table" :dataSource="list" />
|
||
|
||
<!-- ❌ 错误 — 交互元素无 data-testid -->
|
||
<a-input v-model:value="form.name" placeholder="商品名称" />
|
||
<a-button type="primary">创建商品</a-button>
|
||
```
|
||
|
||
**必须加:** 输入框、选择器、开关、按钮（提交/取消/删除）、表格、模态框确认按钮、导航菜单项
|
||
**不需要加:** 纯展示文本、图标、布局容器（Row/Col/Space）
|
||
|
||
---
|
||
|
||
## Vue 3 前端开发
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
frontend/src/
|
||
├── api/ # API 服务 (按模块分组)
|
||
│ ├── wms/ # 仓储管理
|
||
│ ├── oms/ # 订单管理
|
||
│ └── system/ # 系统管理
|
||
├── views/ # 页面组件
|
||
├── components/ # 可复用组件
|
||
├── store/modules/ # Pinia 状态
|
||
├── router/ # 路由配置
|
||
├── utils/
|
||
│ ├── request.ts # Axios 拦截器
|
||
│ └── permission.ts # 权限检查
|
||
└── i18n/ # 国际化
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
```typescript
|
||
// API 服务层
|
||
// api/user/model/index.ts
|
||
export interface User {
|
||
id: number;
|
||
username: string;
|
||
}
|
||
|
||
// api/user/index.ts
|
||
import request from '@/utils/request';
|
||
import type { ApiResult, PageResult } from '@/api';
|
||
import type { User } from './model';
|
||
|
||
export async function getUsers(params: UserParams) {
|
||
const res = await request.get<ApiResult<PageResult<User>>>(
|
||
'/v1/users',
|
||
{ params }
|
||
);
|
||
if (res.status === 200) {
|
||
return res.data;
|
||
}
|
||
return Promise.reject(new Error(res.data.message));
|
||
}
|
||
```
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 安装依赖
|
||
npm install
|
||
pnpm install # DICIAI 使用 pnpm
|
||
|
||
# 开发
|
||
npm run dev
|
||
|
||
# 构建
|
||
npm run build:prod
|
||
npm run build:test
|
||
|
||
# 代码检查
|
||
npm run lint:eslint
|
||
```
|
||
|
||
---
|
||
|
||
## React 前端开发
|
||
|
||
### 项目结构
|
||
|
||
```
|
||
frontend/src/
|
||
├── pages/ # 页面组件
|
||
├── components/ # 可复用组件
|
||
├── services/ # API 服务
|
||
├── hooks/ # 自定义 Hooks
|
||
├── contexts/ # Context Providers
|
||
├── types/ # TypeScript 类型
|
||
├── utils/ # 工具函数
|
||
└── config/ # 配置
|
||
```
|
||
|
||
### 代码规范
|
||
|
||
```typescript
|
||
// Context 集成
|
||
<QueryProvider>
|
||
<AuthProvider>
|
||
<TimerProvider>
|
||
<ConfigProvider locale={zhCN}>
|
||
<Router>
|
||
<Routes />
|
||
</Router>
|
||
</ConfigProvider>
|
||
</TimerProvider>
|
||
</AuthProvider>
|
||
</QueryProvider>
|
||
|
||
// API 服务
|
||
const api = axios.create({
|
||
baseURL: API_BASE_URL,
|
||
timeout: 120000,
|
||
});
|
||
|
||
api.interceptors.request.use((config) => {
|
||
const token = TokenManager.getToken();
|
||
if (token) {
|
||
config.headers.Authorization = `Bearer ${token}`;
|
||
}
|
||
return config;
|
||
});
|
||
```
|
||
|
||
### 常用命令
|
||
|
||
```bash
|
||
# 开发
|
||
npm start
|
||
|
||
# 构建
|
||
npm run build
|
||
|
||
# 测试
|
||
npm test
|
||
npm run test:e2e
|
||
```
|
||
|
||
---
|
||
|
||
## 通用开发规范
|
||
|
||
### API 响应格式
|
||
|
||
```json
|
||
{
|
||
"code": 0,
|
||
"message": "success",
|
||
"data": {}
|
||
}
|
||
```
|
||
|
||
### 分页参数
|
||
|
||
```json
|
||
{
|
||
"page": 1,
|
||
"limit": 20,
|
||
"sort": "created_at",
|
||
"order": "desc"
|
||
}
|
||
```
|
||
|
||
### 认证方式
|
||
|
||
- JWT Token
|
||
- Header: `Authorization: Bearer <token>`
|
||
|
||
### 错误处理
|
||
|
||
```go
|
||
// Go
|
||
if err != nil {
|
||
core.WriteResponse(c, errno.ErrXxx, nil)
|
||
return
|
||
}
|
||
|
||
// TypeScript
|
||
try {
|
||
const result = await api.call();
|
||
} catch (error) {
|
||
message.error(error.message);
|
||
}
|
||
```
|
||
|
||
---
|
||
|
||
## Git 工作流
|
||
|
||
### 提交规范
|
||
|
||
| 类型 | 说明 |
|
||
|------|------|
|
||
| feat | 新功能 |
|
||
| fix | Bug 修复 |
|
||
| docs | 文档 |
|
||
| refactor | 重构 |
|
||
| test | 测试 |
|
||
| chore | 杂项 |
|
||
|
||
### 双电脑同步 (au-dev / cn-dev)
|
||
|
||
```bash
|
||
# 离开时
|
||
git add -A
|
||
git commit -m "WIP: sync from $(hostname)"
|
||
git push origin $(git branch --show-current)
|
||
|
||
# 到达时
|
||
git fetch origin
|
||
git pull origin $(git branch --show-current)
|
||
```
|
||
|
||
---
|
||
|
||
## Docker 部署
|
||
|
||
### 标准配置
|
||
|
||
```yaml
|
||
# docker-compose.yml
|
||
services:
|
||
backend:
|
||
build: ./backend
|
||
ports:
|
||
- "8080:8080"
|
||
depends_on:
|
||
- db
|
||
- redis
|
||
|
||
frontend:
|
||
build: ./frontend
|
||
ports:
|
||
- "80:80"
|
||
|
||
db:
|
||
image: mysql:8.0
|
||
# 或 postgres:15
|
||
|
||
redis:
|
||
image: redis:alpine
|
||
```
|
||
|
||
### 常用端口
|
||
|
||
| 服务 | 端口 |
|
||
|------|------|
|
||
| Backend | 8080 / 9099 |
|
||
| Frontend | 80 / 3000 |
|
||
| MySQL | 3306 |
|
||
| PostgreSQL | 5432 |
|
||
| Redis | 6379 |
|
||
|
||
---
|
||
|
||
## Push 前必须通过：变更包单元测试
|
||
|
||
**在 `git push` 或 `/pr create` 之前，必须跑所有变更文件对应包的单元测试。**
|
||
|
||
```bash
|
||
# 找出变更的 Go 文件所在包，跑对应测试
|
||
PKGS=$(git diff --name-only origin/main...HEAD | grep '\.go$' | grep -v '_test\.go' | sed 's|/[^/]*$||' | sort -u | sed 's|^|./|' | tr '\n' ' ')
|
||
|
||
if [ -n "$PKGS" ]; then
|
||
echo "Running tests for changed packages: $PKGS"
|
||
go test -v -count=1 $PKGS
|
||
else
|
||
echo "No Go files changed, skipping tests"
|
||
fi
|
||
```
|
||
|
||
**规则：**
|
||
- 测试通过 → 继续 push + `/pr create`
|
||
- 测试失败 → 尝试自动修复，修复后重跑
|
||
- 修复成功 → 继续 push
|
||
- **修复失败 → 禁止 push，向用户报告失败原因，等待指示**
|
||
- 仅改了 `_test.go` → 同样需要跑（验证测试本身通过）
|
||
- 无 Go 文件变更（纯前端/文档） → 跳过
|
||
|
||
---
|
||
|
||
## 最佳实践
|
||
|
||
1. **任务驱动** - 使用 ai-proj 管理所有开发任务
|
||
2. **分层清晰** - Controller → Service → Repository
|
||
3. **接口先行** - 先定义接口再实现
|
||
4. **小步提交** - 频繁提交，每次做一件事
|
||
5. **测试覆盖** - 核心逻辑必须有测试
|
||
6. **文档同步** - 代码变更同步更新文档
|
||
|
||
## 相关技能
|
||
|
||
| 技能 | 用途 |
|
||
|------|------|
|
||
| `req-design` | 开发设计（API 契约、任务拆分）— dev-coding 的输入 |
|
||
| `dev-test` | 测试与质量门禁 |
|
||
| `dev-review` | 代码评审（五视角扫描）|
|
||
| `dev-ios` | iOS 开发（插件，按需加载）|
|
||
| `dev-android` | Android 开发（插件，按需加载）|
|
||
| `dev-mcp` | MCP bridge 开发（插件，按需加载）|
|
||
|
||
---
|
||
|
||
## CLAUDE.md 架构检查机制（REQ-20260416-0017 P0-5）
|
||
|
||
**原则：本 skill 不硬编码任何项目的架构细节，从项目 CLAUDE.md 读取**。
|
||
|
||
### 为什么
|
||
|
||
同一套 skill 要支持多个技术栈（Go+Gin / React+AntD / Vue+Element / Python+FastAPI）。如果把分层、命名、目录结构写死在 SKILL.md 里，跨项目就会冲突。
|
||
|
||
devflow-claude 的做法（借鉴）：skill 只管**流程和模板**，项目架构由 CLAUDE.md 的 "Architecture" / "项目架构" 章节定义。
|
||
|
||
### 执行前检查
|
||
|
||
开始编码任务前，skill 先检查项目根 `CLAUDE.md`：
|
||
|
||
```bash
|
||
# 检查 CLAUDE.md 是否含架构关键词
|
||
if [ -f "CLAUDE.md" ]; then
|
||
if grep -qiE "(架构|分层|目录结构|tech stack|architecture|project structure)" CLAUDE.md; then
|
||
echo "✅ 检测到项目架构信息"
|
||
else
|
||
echo "⚠️ CLAUDE.md 缺少架构描述"
|
||
echo " dev-coding 需要架构信息来生成准确的文件路径和分层顺序"
|
||
echo ""
|
||
echo " 📋 建议操作:"
|
||
echo " - 查看预置架构片段: ai-proj-helper/skills-dev/dev-coding-plugin/templates/claude-md-snippets/"
|
||
echo " - 选择匹配技术栈的片段，补充到 CLAUDE.md 的 '## Architecture' 章节"
|
||
echo ""
|
||
echo " ⚠️ 继续执行，但生成的文件路径可能不够准确"
|
||
fi
|
||
else
|
||
echo "⚠️ 未找到项目 CLAUDE.md，建议创建"
|
||
fi
|
||
```
|
||
|
||
### 架构片段模板库
|
||
|
||
位于 `skills-dev/dev-coding-plugin/templates/claude-md-snippets/`：
|
||
|
||
| 文件 | 适用场景 |
|
||
|------|---------|
|
||
| `go-gin-gorm.md` | Go + Gin + GORM 后端（ai-proj backend 风格） |
|
||
| `react-antd.md` | React + TypeScript + Ant Design（ai-proj frontend 风格） |
|
||
| `vue-element.md` | Vue 3 + Element Plus（coolbuy-paas 风格） |
|
||
| `mcp-typescript.md` | MCP bridge TypeScript（mcp-task-bridge 风格） |
|
||
| `generic.md` | 通用空白骨架 |
|
||
|
||
### 非阻断原则
|
||
|
||
架构信息缺失时**仅警告不阻止**。用户仍可继续，但会被告知"生成的建议可能不够准确"。
|