开发工作流程指导 - 编码、测试、代码质量、MR/PR 创建和 CI/CD。用于开发任务、编码、功能实现、Bug 修复、单元测试、代码覆盖率、代码审查、CI/CD 流水线和 Git 操作。
The English summary is being prepared. Showing the original description.
Review the instructions the agent will receive before you install.
没有 Story，不写代码。
Developer 三不做：
{project_docs}/scrum/story/story-*.md，状态为 TODO/IN_PROGRESS例外（无需 Story）：用户直接指令、紧急生产修复、探索性调查
说明:
{project_docs}: 项目文档目录（通常为 docs/）{coverage_threshold}说明:
{coverage_threshold}: 方法/分支覆盖率阈值（默认 70%）强制标准：蛇形命名方式 (snake_case)
项目强制要求：所有代码文件、配置文件、脚本文件和目录必须使用蛇形命名方式（snake_case），即使用下划线 _ 连接单词，禁止使用连字符 -。
| 类型 | ✅ 正确 | ❌ 错误 |
|---|---|---|
| Go 源代码 | {PROJECT_NAME}.go, config_dev.go, health_handler.go | {PROJECT_NAME}.go, config-dev.go, health-handler.go |
| 配置文件 | config_dev.yaml, database_config.yaml | config-dev.yaml, database-config.yaml |
| Shell 脚本 | start_dev.sh, init_db.sh | start-dev.sh, init-db.sh |
| 目录命名 | service_event_watcher, scripts_database | service-event-watcher, scripts-database |
| API 定义 | {PROJECT_NAME}.api, user_service.api | {PROJECT_NAME}.api, user-service.api |
| 二进制文件 | {PROJECT_NAME}_api, {PROJECT_NAME}_cli | {PROJECT_NAME}-api, {PROJECT_NAME}-cli |
| 类型 | 允许格式 | 理由 |
|---|---|---|
| Go Modules | {PROJECT_NAME} | Go 社区标准，所有 Go 官方和第三方模块都使用连字符 |
| Go 包名 | 单个单词（main, config, handler） | Go 语言规范要求包名使用简短的单个小写单词 |
| 通用配置文件 | Makefile, Dockerfile, .gitlab-ci.yml, docker-compose.yml, go.mod | 开发工具的标准命名，修改会导致工具无法识别 |
| 文档文件 | epic-1-scaffolding.md, story-1-01-design.md | 文档文件使用连字符更便于阅读 |
在创建或重命名文件时，请按照以下清单检查：
_ 连接-（除非属于例外情况）CamelCase 或 PascalCase当发现不符合规范的文件时，按以下步骤重命名：
1. 使用 git mv 重命名（保留历史）
# 示例：重命名配置文件
git mv etc/config-dev.yaml etc/config_dev.yaml
# 示例：重命名 Go 源文件
git mv {PROJECT_NAME}.go {PROJECT_NAME}.go
# 示例：重命名目录
git mv sandbox/service-event-watcher sandbox/service_event_watcher
2. 更新所有引用 重命名文件后，必须更新所有引用该文件的地方：
3. 验证编译和测试
# 重新编译
make build
# 运行测试
make test
黄金规则：每次更新代码后，启动服务前必须重新构建容器镜像
容器使用的是编译产物（二进制/字节码等），不重新构建则代码更改不会生效。
# ❌ 错误：只重启服务
docker compose restart {service_name}
# ✅ 正确：重新构建并启动
docker compose up -d --build {service_name}
验证方法：检查容器内编译产物的时间戳是否为最近时间。
| 语言 | {test_cmd} | {coverage_cmd}（方法/分支覆盖率） | Mock 工具 |
|---|---|---|---|
| Go | go test ./... | go test -coverprofile=coverage.out | mockery, testify |
| Python | pytest | pytest --cov=. --cov-branch --cov-report=term-missing | unittest.mock |
| JavaScript | npm test | npm run test:coverage（需配置分支覆盖率） | jest.mock, sinon |
| Java | mvn test | mvn test jacoco:report（需配置分支覆盖率） | Mockito |
| TypeScript | npm test | npm run test:coverage -- --coverage | jest.mock |
| Rust | cargo test | cargo tarpaulin --out Html --branch | mockito |
说明：
-covermode=atomic 提高准确性--cov-branch 启用分支覆盖率jest.config.js 配置 coverageProvider: 'v8' 启用分支覆盖率pom.xml 配置 <instrMode>branch</instrMode>tarpaulin --branch 启用分支覆盖率# 1. 识别项目语言（查看 go.mod, package.json, pom.xml, Cargo.toml 等）
# 2. 从上表选择对应命令
# 3. 运行测试
{test_cmd}
# 生成覆盖率报告
{coverage_cmd}
说明:
coverage.out、.coverage、htmlcov/ 等目录覆盖率要求：
{coverage_threshold}（默认 70%）黄金规则：使用项目 SIT 测试框架，禁止自己编写测试脚本
| 框架 | {sit_run_cmd} | 报告位置 |
|---|---|---|
| 自定义脚本 | ./tests/sit/run_sit_tests.sh --auto | test_reports/sit_report-*.md |
| pytest集成 | pytest tests/integration/ | test_reports/integration_report.html |
| Maven Verify | mvn verify | target/site/jacoco/index.html |
# 使用项目 SIT 框架验证
{sit_run_cmd}
说明:
test_reports/核心原则：Spec → Scenario → Mock Data 三层对齐
基于设计规范（Spec）定义测试场景（Scenario），构建对齐的 Mock 数据，确保单元测试准确体现设计意图。
关键要求：
测试代码注释规范（使用 AAA 模式）：
// Spec: {design_doc} §{section}
// Scenario: {scenario_description}
func TestXXX(t *testing.T) {
// Arrange: 基于 spec 构建场景
// Act: 执行被测试的逻辑
// Assert: 验证 spec 要求
}
接口抽象原则：
说明:
{design_doc}: 设计文档名称{section}: 章节编号| 语言 | {fmt_cmd} | {lint_cmd} | {build_cmd} |
|---|---|---|---|
| Go | gofmt -w . 或 go fmt ./... | golangci-lint run 或 make lint | go build ./... |
| Python | black . | flake8 或 pylint | python -m build |
| JavaScript | prettier --write . | eslint . | npm run build |
| Java | google-java-format -i . | checkstyle | mvn package |
| Rust | cargo fmt | cargo clippy | cargo build --release |
{fmt_cmd}）{lint_cmd}）{test_cmd}）{coverage_threshold}）{sit_run_cmd}）说明:
Commit Message 格式：
<type>(<scope>): <subject>
<body>
<footer>
类型：feat, fix, refactor, docs, test, chore
默认行为：
git add + git commit（提交到本地分支）git push（不推送远程）{main_branch} 分支保护规则：
绝对禁止：未经明确授权直接 git push origin {main_branch}
YOLO 模式例外条件（必须同时满足）：
{main_branch} 之外的分支（feature/, dev, bugfix/ 等）{main_branch}（即使 YOLO 模式也不行）说明:
{main_branch}: 主分支名（通常为 master 或 main）核心概念：主干开发模式，支持并行开发多个任务
💡 辅助脚本：本 SKILL 附带了 Git Workflow 辅助脚本
git-workflow.skill.sh，简化 worktree 操作。安装（一次性）：
# 添加到 ~/.bashrc 或 ~/.zshrc echo 'source $(git rev-parse --show-toplevel)/.claude/skills/dev/scripts/git-workflow.skill.sh' >> ~/.bashrc source ~/.bashrc快速使用：
# 创建功能分支 worktree git-workflow.feature.start story-06-01 "pod handler" # 在 worktree 中同步上游 master/main git-workflow.feature.sync # 推送并创建 MR git-workflow.feature.submit # MR 合并后清理 worktree git-workflow.feature.finish story-06-01 # 列出所有 worktree 及其状态 git-workflow.worktree.list优势：1 条命令替代 6-8 步 Git 操作，自动检测项目配置，彩色输出提示
默认位置：项目根目录下的 .worktrees/{branch_name}/（不要用项目外的兄弟目录）
{project_root}/.worktrees/feat-story-06-01/../{project_name}-worktrees/、../worktrees/、/tmp/...为什么：留在项目根内 → 可发现、清理不误伤（兄弟目录易被当无关文件夹整体删除），且不破坏以项目根为基准的容器卷/bind mount（实测 netbox-lab 容器卷被兄弟目录 worktree 清理误伤，容器直接 exited）。
前置（创建前必做）：确保 .worktrees/ 在 .gitignore：
grep -qxF '.worktrees/' .gitignore 2>/dev/null || echo '.worktrees/' >> .gitignore
feat/{task_id}-{summary}fix/{bug_id}-{description}hotfix/{short_description}refactor/{short_description}# 1. 创建 worktree（项目根下的 .worktrees/ 内，已在前置步骤加入 .gitignore）
cd {project_root}
git worktree add .worktrees/{branch_name} -b {branch_name}
# 2. 在 worktree 中开发
cd .worktrees/{branch_name}
# ... 开发代码 ...
git add .
git commit -m "<type>(<scope>): <subject>"
# 3. 推送到远程（非 {main_branch} 分支）
git push origin {branch_name}
# 4. 创建 MR/PR（根据项目使用的平台）
# 5. MR/PR 合并后，清理 worktree
cd {project_root}
git worktree remove .worktrees/{branch_name}
git branch -d {branch_name}
说明:
{project_root}: 项目根目录{project_root}/.worktrees/，不要使用项目外的兄弟目录（见上文「Worktree 位置」铁律）git worktree prune 清理孤立 worktree{test_cmd}{sit_run_cmd}{test_cmd}，确保覆盖率达标{sit_run_cmd}MR/PR 创建 → Pipeline 监听 → 状态判断 → 成功/失败处理
↓ ↓
持续监听 Yolo Mode 修复
↓
重新推送 → 继续监听
↓
闭环验证
## 功能说明
[简述功能目标 + 核心改进点 3-5 条]
## 变更说明
### 新增文件 (N 个)
- `path/file` (X lines) - 简短说明
### 修改文件 (M 个)
- `path/file` - 修改说明
### 代码统计
- 新增: +X lines
- 删除: -Y lines
- 测试覆盖率: XX%
## 测试验证结果
| 场景 | 预期 | 实际 | 状态 |
|------|------|------|------|
| 场景1 | XXX | XXX | ✅ |
## 相关文档
- Story: `{project_docs}/scrum/story/story-*.md`
- Design: `{project_docs}/design/{layer}_design_v{version}.md`
## 验收标准
- [x] AC1
- [x] AC2
使用 CLI 工具（推荐）：
# GitLab
glab mr create --title "<type>(<scope>): <subject>" \
--target-branch {main_branch} --source-branch {branch_name}
# GitHub
gh pr create --title "<type>(<scope>): <subject>" \
--base {main_branch} --head {branch_name}
使用 REST API（备选）：
状态值：pending → running → success / failed / canceled / skipped
监控方式：
glab, gh）或 REST API 查询 Pipeline 状态CI 失败类型与处理：
| 失败类型 | 负责方 | 典型场景 |
|---|---|---|
| 编译错误 | Dev | 语法错误、类型不匹配、依赖缺失 |
| 测试失败 | Dev/QA | 断言失败、集成测试失败 |
| 超时 | Dev | 死锁、网络延迟、性能问题 |
| Runner 异常 | Ops | Runner 不可用、资源不足 |
触发条件：Pipeline 失败
5 步修复流程：
git fetch origin {main_branch} + git rebase origin/{main_branch}{test_cmd}, {fmt_cmd}, {build_cmd} 全部通过说明:
{build_cmd}: 构建命令（见上表）❌ 自写测试脚本代替项目 SIT 框架
✅ 使用项目 SIT 测试框架（{sit_run_cmd}）
❌ 直接 git add . && git commit && git push
✅ {fmt_cmd} && {lint_cmd} && {test_cmd} && {sit_run_cmd} → 然后 commit
❌ 修改代码后只重启容器（docker compose restart）
✅ 修改代码后重新构建（docker compose up -d --build）
项目文档：
CLAUDE.md - 项目概述、核心架构、开发规范{project_docs}/design/ - 设计文档目录{project_docs}/scrum/story/ - Story 文档目录SKILL 文档：
.claude/skills/qa/SKILL.md - QA 工作流程和测试规范.claude/skills/pm/SKILL.md - Scrum 工作流程.claude/skills/arch/SKILL.md - 架构设计规范Claude 执行时按优先级推断占位符：
高可推断性占位符（> 85%）：
{main_branch}, {project_root}, {project_docs}, {test_cmd}, {build_cmd}, {fmt_cmd}, {lint_cmd}, {vcs_platform}
中等可推断性（60-80%）：
{coverage_threshold}（默认 70%）, {sit_run_cmd}
版本: v5.2 创建日期: 2026-04-28 作者: Development Team 状态: 正式发布
更新日志:
.worktrees/（铁律）+ 前置 .gitignore 检查，废弃兄弟目录默认值与 {worktree_dir} 占位符No reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
架构师工作技能 - 架构设计、文档管理、语义化版本控制、设计审查。当用户提到架构、设计文档、版本管理、技术选型、系统设计、数据模型、API设计、文档审查、设计规范、架构决策、或需要创建/更新设计文档时，必须使用此技能。确保所有设计文档遵循语义化版本规范和命名约定。
The English summary is being prepared. Showing the original description.
代码提交与 MR 创建技能 - 自动生成语义化 commit message、创建符合规范的 GitLab Merge Request、验证飞书工作项关联。当用户提到 Git 提交、commit、push、推送代码、创建 MR、创建 PR、合并请求、或需要提交代码、推送代码、创建 MR/PR 时，必须使用此技能。支持交互式（对话）和非交互式（参数）两种模式。
The English summary is being prepared. Showing the original description.
DevOps 工作技能 - CI/CD 流程、容器化构建、Kubernetes 部署、基础设施即代码、监控告警。当用户提到部署、容器化、K8s、Helm、ArgoCD、CI/CD、监控、日志、或需要执行部署、排查线上问题时，必须使用此技能。
The English summary is being prepared. Showing the original description.
PM 编排技能 — 具备意图识别与动态路由能力的项目管理中枢。除了 pm 的全部 Story/Epic/Sprint 管理能力外，pm 能分析用户 prompt 的多领域意图，动态匹配所需的专业 skill（arch/dev/ued/qa/devops 等），生成编排计划并在用户确认后依次唤起各 skill 协同工作。当用户的请求涉及多个专业领域、需要跨 skill 协调、或者用户希望用一个 prompt 驱动完整的「设计→实现→验证」流程时，使用此技能。纯 Story 管理/迭代规划等单领域任务，pm 会直接处理而不路由。
The English summary is being prepared. Showing the original description.
QA 工作技能 — 测试分层架构、UT/API/SIT/E2E/UAT 测试、交叉验证策略、测试数据管理、测试报告管理。当用户提到测试、QA、质量保证、回归测试、单元测试、集成测试、验收测试、测试覆盖率、pytest、go test、E2E、Playwright、monkey test、fuzz test、RPC 测试、测试用例设计、TDD、测试框架、测试策略审查、问题排查、测试环境、测试数据、SIT 交叉验证、或需要设计/执行/增强测试策略时，必须使用此技能。确保所有测试活动遵循分层架构和业务正确性验证原则。
The English summary is being prepared. Showing the original description.
安全重构代码技能。当用户明确提到"重构"、"代码异味"或需要在TDD循环的Refactor阶段改进代码内部结构时使用。 **仅在以下场景触发**： - 用户明确说"重构这段代码" - 提到"代码异味"并要求改进 - TDD循环中的Refactor阶段 - 代码审查中需要改进内部结构但不改变功能 **注意**：如果用户只是说"优化"、"改进"或"提升性能"，不应该触发此技能，除非明确提到"重构"。
The English summary is being prepared. Showing the original description.