FIT Framework Claude Code 配置实战:基于 Slash Commands 的 AI 协作开发工作流

原创2026-10-15 09:27:201,891 阅读
文章标签:后端人工智能AI 应用Agent 框架RAGMCP 服务MCP Clients微服务插件系统流程编排依赖注入

FIT Framework Claude Code 配置实战:基于 Slash Commands 的 AI 协作开发工作流

本篇指南以 FIT Framework 仓库中的 .claude/README.md 为骨架,系统讲解该项目如何为 Claude Code 定制一套"规则驱动 + 命令驱动"的 AI 协作开发体系:从目录结构与项目规则的落地,到 PR、提交、依赖升级、任务管理等 Slash Commands 的完整用法,再到参数传递规则与故障排除。读完本文,你将掌握在 FIT Framework 多语言、多引擎(FIT / Waterflow / FEL)仓库中,让 Claude 遵循项目规范、按标准化工作流辅助开发与协作的具体方法。

一、为什么要为 Claude Code 单独建一套配置

FIT Framework 是一个跨 Java / Python 的企业级 AI 开发框架,同时承载 FIT 函数引擎、Waterflow 流式编排引擎和 FEL(Java 生态的 LangChain 替代方案)等多个子项目,模块划分深、构建链长、提交与 PR 规范严格。如果让 AI 助手在这个仓库里"自由发挥",很容易出现:commit message 格式不统一、未经确认就自动提交、PR 描述不完整、版权头年份过期、任务进度与 Issue 脱节等问题。

为此,仓库在根目录下维护了一套 .claude/ 配置,用**规则(project-rules.md)约束 AI 的行为边界,用命令(commands/*.md)把高频操作固化为可复用的 Slash Commands,再用快速参考(QUICK-REFERENCE.md)与项目指令(CLAUDE.md)**在启动时加载到 AI 的上下文中。

二、配置目录结构与各文件职责

根据 .claude/README.md 的说明,配置目录结构如下:

.claude/
├── README.md              # 本文件(配置总览与使用指南)
├── QUICK-REFERENCE.md     # 快速参考指南(任务管理)
├── project-rules.md       # 项目规则和规范(Claude 会自动遵循)
├── CLAUDE.md              # 项目指令(Claude Code 启动时加载)
├── settings.json          # 权限与插件配置
└── commands/              # 自定义 Slash Commands

各文件的职责分工(结合 .claude/CLAUDE.md 的"配置架构"一节)可以概括为一条加载链:

.claude/CLAUDE.md(快速参考,启动时加载)
    ↓
.claude/project-rules.md(详细规则,强制遵循)
    ↓
.claude/commands/(Slash Commands 实现)
  • CLAUDE.md:存放项目基础信息(构建命令、编码规范、测试要求、工具使用偏好),是每次会话启动时 AI 最先接触的指令;
  • project-rules.md:定义强制规则与执行流程,README 中列举了其中两条代表性规则(文件权限管理、PR 提交规范),完整版共六条,见下文;
  • QUICK-REFERENCE.md:面向日常协作的速查手册,收录所有 Slash Commands 表格、自然语言示例和完整工作流;
  • commands/ 目录:每个 .md 文件对应一个 Slash Command,通过 YAML front matter 声明 name、description、usage,正文给出 AI 执行该命令时的完整流程、输出文件清单和错误处理。

从当前仓库实际文件看,commands/ 目录包含 20 个命令文件:create-pr.md、create-task.md、plan-task.md、implement-task.md、review-task.md、complete-task.md、block-task.md、check-task.md、sync-issue.md、sync-pr.md、commit.md、upgrade-dependency.md、test.md、test-integration.md、analyze-issue.md、analyze-security.md、refine-task.md、refine-title.md、create-release-note.md、release.md、close-security.md 等,覆盖 PR 生命周期、任务生命周期、安全告警处理和发布流程。

三、项目规则:AI 协作的行为底线

.claude/README.md 明确要求 Claude 在处理项目时必须遵循 project-rules.md。该文件定义了六条规则,按"关键(🔴)/ 重要(🟡)"分级:

规则 级别 说明
Commit Message 中文格式 🔴 关键 提交信息必须使用中文描述
禁止自动提交 🔴 关键 不自动执行 git commit / git add
版权年份更新 🔴 关键 修改文件时更新版权头年份
任务状态管理 🔴 关键 执行命令后立即更新任务状态
PR 规范 🟡 重要 遵循 PR 模板
任务语义识别 🟡 重要 自然语言转命令执行

3.1 规则 1:Commit Message 中文格式

基础格式为 <type>(<scope>): <中文描述>,其中:

  • type:feat / fix / docs / refactor / test / chore;
  • scope:fit / waterflow / fel(可省略);
  • subject:中文描述,按 CLAUDE.md 要求控制在 20 字以内。

标准提交格式(需在消息末尾附加生成标记与署名):

git commit -m "$(cat <<'EOF'
feat(fit): 添加用户认证功能

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
EOF
)"

使用 HEREDOC 格式传递消息,是为了避免命令行转义问题。

3.2 规则 2:禁止自动提交

这是 README 中特别强调的核心原则:AI 绝对不要自动执行 git commit 或 git add,除非用户明确使用 /commit 命令(或明确说出"修复后直接提交")。完成代码修改后,正确的做法是:告知用户修改了哪些文件,并提醒用户使用 /commit 提交。这一约束同样被写进 commit.md 与 CLAUDE.md 的关键规则中,防止 AI 在无人确认的情况下污染 Git 历史。

3.3 规则 3:PR 提交规范

创建 PR 前必须满足:所有测试通过(mvn clean install)、代码已格式化、公共 API 有 Javadoc、版权头年份已更新。AI 的执行流程为:

  1. 读取 PR 模板 .github/PULL_REQUEST_TEMPLATE.md;
  2. 用 git diff [base-branch]...HEAD 分析分支分叉后的所有变更;
  3. 检查远程分支状态,必要时推送;
  4. 用 gh pr create + HEREDOC 格式创建 PR,结尾附加 🤖 Generated with [Claude Code] 标记。

3.4 规则 4:版权年份更新

修改任何带版权头的文件时,先动态获取当前年份(date +%Y,禁止硬编码),再将旧年份更新为当前年份,例如 Copyright (C) 2024-2025 → Copyright (C) 2024-2026。要点是:只更新当前修改的文件,不批量更新项目中所有文件。commit.md 中还给出了提交前完整的版权检查流程与更新示例。

3.5 规则 5:任务语义识别

AI 需要把自然语言意图映射到对应命令,例如:"分析 issue XXX" → /analyze-issue,"设计方案" → /plan-task,"实施/实现" → /implement-task,"查看状态/进度" → /check-task,"同步进度/更新 issue" → /sync-issue。执行流程是:识别意图 → 查找任务(.ai-workspace)→ 执行工作流 → 更新状态 → 告知用户。查找任务的优先级为:按任务 ID(TASK-xxx)→ 按 Issue 号(#207)→ 按关键词搜索。

3.6 规则 6:任务状态管理

执行任何命令后,必须立即更新任务状态。强制更新映射如下:

命令 必须更新的字段
/analyze-issue current_step、updated_at、assigned_to
/plan-task current_step、updated_at
/implement-task current_step、updated_at
/review-task current_step、updated_at
/complete-task status、completed_at、updated_at
/block-task status、blocked_at、blocked_reason

任务状态字段包括:status(active / blocked / completed)、current_step、updated_at、assigned_to,并在任务文件中维护"工作流进度"清单,如:

- [x] requirement-analysis (claude, 2026-01-03)
- [x] technical-design (进行中)
- [ ] implementation (待执行)

四、Slash Commands 使用指南

.claude/README.md 的核心章节是按场景组织的命令用法。以下命令均可在仓库 .claude/commands/ 目录中找到对应的实现文件。

4.1 创建 Pull Request

# 创建 PR(自动推断目标分支)
/pr

# 创建 PR 到 main 分支
/pr main

# 创建 PR 到指定分支
/pr develop

工作流程:自动读取 PR 模板 → 查看最近的 PR 示例 → 分析当前分支的变更 → 按模板格式创建 PR。

对应实现文件为 create-pr.md,其中补充了目标分支的推断规则:当前在核心分支上(main 或 大版本.小版本.x 版本分支)则目标分支即当前分支;当前在特性分支上则从 git log 的分支标记中找到最近的父核心分支;无法确定时询问用户。创建 PR 前还会用 gh pr list --limit 3 --state merged 查看最近 3 个已合并 PR 作为格式参考,并通过 git diff <target-branch>...HEAD --stat 汇总变更统计。

4.2 更新现有 PR

# 更新 PR #369 的描述
/pr-update 369

4.3 提交变更

# 交互式提交(会询问提交信息)
/commit

# 使用指定消息提交
/commit "feat: add new feature"

对应实现文件 commit.md 指出:该命令已迁移到官方插件,实际调用 commit-commands 插件命令(也可用 /commit-commands:commit-push-pr 一键完成提交 + 推送 + 创建 PR)。同时该文件强调两条 CRITICAL 前置检查:提交前必须检查用户本地修改(git status --short + git diff,在用户修改基础上做增量编辑,不覆盖用户实现),以及提交前必须检查并更新版权头年份。

4.4 升级依赖

# 升级 swagger-ui 从 5.30.0 到 5.30.2
/upgrade-dep swagger-ui 5.30.0 5.30.2

自动化流程:创建功能分支 → 更新依赖文件 → 运行编译测试 → 提交变更 → 创建 PR。

对应实现文件为 upgrade-dependency.md,它给出了跨生态的依赖更新方式:Maven 项目更新 pom.xml 中的 <version>,Node.js 项目更新 package.json 的 dependencies,Gradle 项目更新 build.gradle 的 implementation 声明;如果依赖包含静态资源(如 swagger-ui 的 HTML/CSS/JS),需同步更新版本号引用、CDN 链接和文档说明。验证环节支持三种构建系统:mvn clean package -Dmaven.test.skip=true、npm install && npm run build、./gradlew clean build -x test,并建议随后运行完整测试套件。

4.5 审查 PR

# 审查 PR #369
/review 369

审查内容:PR 标题和描述是否符合规范 → 代码变更的合理性 → 安全问题检查 → 测试覆盖情况 → 生成审查报告。

对应实现文件为 review-task.md,审查维度包括代码质量与编码规范、Bug 与潜在问题、测试覆盖率与质量、错误处理与边界情况、性能与安全问题、与方案的一致性;问题按"🔴 必须修复 / 🟡 建议修改 / 🟢 优化建议"三级分类,输出结构化审查报告 review.md。可选参数 --pr-number 可额外调用 /pr-review-toolkit:review-pr 做多维度深度审查。

4.6 检查和修复权限

# 检查并修复所有文件和目录权限
/fix-permissions

自动化流程:从 README.md 获取正确的所有者信息 → 扫描所有文件和目录 → 识别权限不一致的文件 → 自动修复为正确的所有者 → 生成检查报告。其设计动机对应 README 中"规则 1: 文件权限管理"——所有新建/修改的文件必须设置正确的所有者权限,且避免硬编码用户名和用户组,而是动态从参考文件获取。

4.7 任务管理命令

# 分析 GitHub Issue 并创建任务
/analyze-issue 207

# 设计技术方案
/plan TASK-20251227-104654

# 实施任务
/implement TASK-20251227-104654

# 查看任务状态
/check-task TASK-20251227-104654

# 同步进度到 Issue
/sync-issue TASK-20251227-104654

对应的命令实现文件(注意与 README 中命令名的对应关系):

  • /analyze-issue → analyze-issue.md:用 gh issue view <issue-number> --json number,title,body,labels 获取 Issue 信息,创建任务目录与 task.md,按工作流执行需求分析并输出 analysis.md;
  • /plan-task → plan-task.md:读取需求分析,对比备选方案,输出包含"方案决策 / 技术方案 / 实施步骤 / 文件清单 / 验证策略 / 影响评估 / 风险控制"的 plan.md;
  • /implement-task → implement-task.md:按方案实施代码并编写测试,运行 mvn test、npm test 或 pytest 验证,输出 implementation.md,且明确不自动执行 git commit;
  • /check-task → check-task.md:在 active / completed / blocked 目录中查找任务,输出包含基本信息和上下文文件清单的状态报告;
  • /sync-issue → sync-issue.md:汇总各阶段核心要点,用 gh issue comment {issue-number} --body "$(cat <<'EOF' ... EOF)" 发布到对应 Issue。

除了上述命令,QUICK-REFERENCE.md 还列出了更多工具命令:/fix-permissions、/test(执行完整测试流程)、/test-integration、/code-review:code-review 等,并提供了自然语言替代用法——例如输入"分析 issue 207"、"帮我分析 fastjson 迁移需求"即可触发 /analyze-issue 207;输入"实施 TASK-xxx"即可触发 /implement-task,实现"对话式驱动"。

五、参数传递规则

Slash Commands 支持参数,.claude/README.md 归纳了三条规则:

1. 单个参数——空格分隔,参数直接跟在命令后:

/pr main

main 是目标分支参数。

2. 多个参数——按顺序传递:

/upgrade-dep swagger-ui 5.30.0 5.30.2
  • swagger-ui:包名
  • 5.30.0:原版本
  • 5.30.2:新版本

3. 带空格的参数——使用引号包裹:

/commit "feat: add new feature"

这条规则在 project-rules.md 的"自定义命令"一节有完全一致的表述(单参数 /pr main、多参数 /upgrade-dep swagger-ui 5.30.0 5.30.2、带空格 /commit "feat: new feature"),可作为参数解析行为的交叉印证。

六、任务驱动的完整工作流

6.1 任务 ID 与文件路径约定

任务 ID 格式为 TASK-{yyyyMMdd-HHmmss},例如 TASK-20251227-104654。任务相关文件按状态分目录存放:

  • 活动任务:.ai-workspace/active/TASK-xxx/task.md
  • 已完成:.ai-workspace/completed/TASK-xxx.md
  • 已阻塞:.ai-workspace/blocked/TASK-xxx.md

上下文文件与任务目录同级:

  • 需求分析:analysis.md
  • 技术方案:plan.md
  • 实现报告:implementation.md
  • 审查报告:review.md

6.2 从 Issue 到提交的标准流程

QUICK-REFERENCE.md 给出了完整命令链:

# 1. 分析 Issue
/analyze-issue 207

# 2. 审查需求分析(人工)
# 查看 .ai-workspace/active/TASK-xxx/analysis.md

# 3. 设计技术方案
/plan TASK-xxx

# 4. 审查技术方案(人工)⚠️ 必需
# 查看 .ai-workspace/active/TASK-xxx/plan.md

# 5. 同步进度到 Issue(可选,推荐在重要节点)
/sync-issue TASK-xxx

# 6. 实施任务
/implement TASK-xxx

# 7. 代码审查
/code-review:code-review

# 8. 同步最终进度(可选)
/sync-issue TASK-xxx

# 9. 提交代码(人工确认后)
/commit

6.3 人工检查点

工作流中设置了四个需要人工确认的节点(前两个为建议、两个为必需):

  1. 需求分析后:确认需求理解正确(建议);
  2. 技术方案设计后:审查方案是否合理(必需)——plan-task.md 与 implement-task.md 都要求方案必须经人工审查批准后才可进入实施;
  3. 代码审查后:确认审查结果和修改建议(建议);
  4. 最终提交前:确认所有变更无误(必需)。

6.4 任务生命周期与状态流转

任务状态支持 active / blocked / completed 三种流转,对应命令为:

  • /complete-task <task-id>:校验所有前置条件(工作流步骤全部完成、审查批准、代码已提交合并)后,将 status 更新为 completed、current_step 更新为 finalize,并将任务目录从 active 移动到 completed 归档,详见 complete-task.md;
  • /block-task <task-id> <a href="https://link.gitcode.com/i/87fd44a3b454c232b71198b8b08fe262" target="_blank">--reason <阻塞原因>]:遇到无法继续的问题时,详细记录"阻塞信息"(问题描述、根本原因、尝试的方案、需要的帮助、解除阻塞条件),将任务移入 blocked 目录,详见 [block-task.md;
  • 代码审查发现问题时用 /refine-task <task-id> 修复:读取审查报告,按"必须修复 → 建议修改 → 优化建议"的优先级逐项修复,输出 refinement-report.md 后重新进入审查,详见 refine-task.md。

七、最佳实践

.claude/README.md 归纳了三条最佳实践:

1. 使用 Slash Commands——优先使用自定义命令,而不是手动描述任务:

  • ✅ /pr 3.5.x
  • ❌ "请帮我创建一个PR到3.5.x分支"

2. PR 创建流程——始终使用 /pr 命令,确保自动遵循项目规范、完整填写 PR 模板、参考最近的 PR 格式。

3. 依赖升级——使用 /upgrade-dep 自动化整个流程:创建分支 → 更新文件 → 测试验证 → 提交并创建 PR。

QUICK-REFERENCE.md 进一步补充了何时用命令、何时用自然语言的取舍:精确任务、标准流程、批量操作适合 Slash Commands;探索性任务、灵活表达、上下文对话适合自然语言。并给出四点提示:优先使用 Slash Commands(更精确、快速、标准化)、自然语言作为补充、明确任务 ID 避免歧义、遵循工作流不跳过人工检查点。

八、安全与权限配置

配置目录中的 settings.json 定义了 Claude 的操作边界:

  • allow:授权 git:*、mvn:*、npm:*、gh:* 及构建/测试脚本(如 .ai-agents/scripts/run-test.sh)等常规操作,并允许有限的清理命令(仅限 build、dynamic-plugins、target、node_modules、dist 等构建产物目录);
  • deny:禁止 sudo rm、根目录/主目录的递归删除,禁止读取 .env、secrets/**、**/*.key、**/*.pem、credentials.* 等敏感文件——这与 CLAUDE.md 中"不要提交敏感文件"的安全注意事项一致;
  • ask:对 git push origin main/master、git push --force、git rebase、npm publish、mvn deploy 等高风险操作要求人工确认;
  • enabledPlugins:启用了 code-review、commit-commands、context7、feature-dev、pr-review-toolkit、security-guidance 等官方插件,为代码审查、提交、安全等场景提供插件能力。

九、常用命令速查

README 中给出的项目级常用命令(适用于本仓库的 Java 构建与运行):

# 编译项目
mvn clean install

# 快速编译(跳过测试)
mvn -B clean package -Dmaven.test.skip=true

# 运行测试
mvn test

# 启动应用
./fit start

# 查看 Git 状态
git status

# 查看 PR 列表
gh pr list

# 查看某个 PR
gh pr view 369

注意:mvn clean install 是 CLAUDE.md 定义的基线命令(会自动运行所有测试),也是所有 PR 提交前必须通过的门禁;./fit start 启动 FIT 运行时依赖 Node.js,默认端口 8080。

十、故障排除

.claude/README.md 给出了常见问题与解决方案,此处结合命令实现文件补充说明:

问题 解决方案
Claude 没有遵循 PR 模板 使用 /pr 命令而不是手动描述(命令会自动读取 .github/PULL_REQUEST_TEMPLATE.md)
PR 描述格式不对 使用 /pr-update <pr-number> 命令更新
文件权限错误 使用 /fix-permissions 命令自动检查和修复
想要自定义命令 在 .claude/commands/ 目录创建新的 .md 文件,通过 YAML front matter 声明 name / description / usage 即可注册为新的 Slash Command

QUICK-REFERENCE.md 补充了任务管理相关的 FAQ:

  • 如何知道任务当前在哪一步? 使用 /check-task TASK-xxx;
  • 忘记任务 ID 怎么办? 执行 ls .ai-workspace/active/ 查看活动任务列表,或通过 Issue 号搜索:grep -r "#207" .ai-workspace/active/;
  • 可以跳过某些步骤吗? 工作流是推荐流程,可以灵活调整,但不建议跳过人工检查点;
  • 多个 AI 如何协作? 所有 AI 都可以读取 .ai-workspace/ 下的任务和上下文文件,实现无缝切换;
  • 什么时候应该同步进度到 Issue? 建议在完成重要阶段后(需求分析、技术方案、实现完成)、遇到阻塞问题需要讨论时、长时间任务定期更新时使用 /sync-issue,避免在每个小步骤都同步而产生过多评论。

十一、总结

FIT Framework 的 .claude/ 配置是一套完整的"AI 协作开发治理方案":project-rules.md 定义行为底线,commands/ 目录把高频操作固化为标准命令,QUICK-REFERENCE.md 提供速查入口,settings.json 划定权限边界。这套体系特别适合模块多、构建链长、规范严格的复杂仓库——它既保证了 AI 输出的 commit、PR、文档符合项目规范,又通过"任务 ID + 人工检查点"的设计让每个关键决策都保留人类审查的入口。

如果你需要在 FIT Framework 仓库中启用这套协作模式,只需在项目根目录下启动 Claude Code,它便会自动加载 CLAUDE.md 与 project-rules.md,随后即可通过 /pr、/commit、/upgrade-dep、/analyze-issue、/plan-task、/implement-task、/review-task、/sync-issue 等命令驱动标准工作流;完整的命令与自然语言对照表可随时查阅 .claude/QUICK-REFERENCE.md。

登录后查看全文
fit-framework