Claude Code智能编码工作流：Agents+Commands+Skills工程实践

1. 项目概述：这不是又一个“调用API”的玩具，而是一套可落地的智能编码工作流

“一路飙到 3.2 万 Star 的 Claude Code 最佳实践，开源了”——这个标题里藏着三个关键信号：高关注度（3.2 万 Star）、强实操性（最佳实践）、可复用性（开源）。它不是教你如何在网页上点几下 Claude 的按钮，也不是拿个现成的 CLI 工具跑个 demo 就完事；它是一套围绕Claude Code构建的、面向真实开发场景的Agents + Commands + Skills协同工作流。核心关键词Claude Code指的并非 Anthropic 官方产品，而是社区基于其模型能力（尤其是claude-3.5-sonnet及后续版本）深度定制的一套本地化、可扩展、带状态管理的智能编码代理系统。它和你搜到的 “claude code 安装”、“claude code 下载”、“claude code 桌面版” 等零散信息不同，它不依赖某个特定 GUI 或封闭客户端，而是以命令行即界面（CLI as UI）为设计哲学，把每一次代码生成、重构、测试、文档编写都抽象为一条可组合、可复用、可审计的Command。

我第一次看到这个项目时，正在为一个遗留 Java 服务做接口迁移。手动改 Swagger 注解、同步 DTO、补单元测试，一天下来眼睛发酸，还漏了两个字段。试了下它的code:refactor --from swagger --to spring-boot命令，12 秒生成了带完整 Javadoc 和 Mockito Mock 的测试桩，且所有字段映射逻辑都写在 YAML 配置里，随时可 review、可 diff、可回滚。那一刻我才明白，所谓“最佳实践”，不是教你怎么写 prompt，而是帮你把 prompt 背后的意图、约束、上下文、验证规则全部结构化、工程化、版本化。它解决的不是“能不能生成”，而是“生成得是否可靠、可追溯、可协作”。适合三类人：一是被重复性编码任务压得喘不过气的中高级开发者；二是想把 AI 编程能力嵌入 CI/CD 或内部工具链的技术负责人；三是正在探索Agentic Workflow如何真正落地的研究者或工程师——比如你关注的Reflexion: Language Agents with Verbal Reinforcement Learning (NeurIPS 2023)，它的核心思想（让 agent 通过“自言自语”反思执行结果）在这个项目里不是论文里的伪代码，而是直接体现在agents/reflexion_loop.py里一个带self-critiquestep 的CodeAgent类中。它不讲大道理，只给你能git clone、pip install、然后立刻在你自己的代码库上跑起来的硬核方案。

2. 整体架构与设计思路：为什么是 Agents + Commands + Skills，而不是一个大而全的 IDE 插件？

2.1 核心分层：从“单次调用”到“持续工作流”的范式跃迁

很多同类项目失败的根本原因，在于把 AI 当作一个“超级 autocomplete”来用。输入一段代码，按 Ctrl+Enter，等它吐出下一行——这本质上仍是单次、无状态、不可审计的操作。而本项目的设计起点，是把一次完整的编码任务（比如“给用户服务添加短信验证码登录”）拆解为可编排、可中断、可重入、可验证的原子步骤。整个架构严格遵循三层分离：

• Agents 层（决策中枢）：负责理解高层目标（如add sms login to user service），将其分解为子任务序列（1. design schema,2. generate controller,3. write integration test,4. update docs），并根据每个子任务的执行反馈（成功/失败/部分成功）动态调整后续策略。它不直接写代码，而是调度 Commands 并管理上下文状态（如当前代码库的 Git HEAD、已生成的文件路径、上次失败的错误日志）。这里的 Agent 不是黑盒 LLM，而是明确包含planning,execution,reflection,memory四个模块的 Python 类，其reflection模块正是对 NeurIPS 2023 Reflexion 论文的轻量级工程实现：它会把上一轮 Command 执行的 stdout/stderr、diff 结果、甚至pylint报告作为“verbal feedback”，喂给 Claude 生成一段自我批评（“我忘了校验手机号格式，导致测试失败”），再据此修正下一步 plan。

• Commands 层（执行单元）：这是你每天打交道最多的部分，也是标题里“Claude Code 目录 commands 怎么生成”的答案所在。每个 Command 都是一个独立的、带完整生命周期的 Python 模块（如commands/code_refactor.py），它必须定义run()方法、validate()方法（检查前置条件，如目标文件是否存在）、rollback()方法（出错时如何撤回）、以及最关键的prompt_template.j2（Jinja2 模板，而非硬编码字符串）。这意味着code:refactor这个命令，其 prompt 不是写死的，而是由context = { 'source_code': get_file_content(args.file), 'target_framework': args.framework, 'rules': load_rules('java-spring') }动态渲染而成。你完全可以在项目根目录下新建commands/my_custom_doc_gen.py，定义自己的模板和逻辑，然后claude-code my_custom_doc_gen --file UserService.java就能跑起来。这种设计直接回应了热搜词里反复出现的“claude code skills构建指南与最佳实践”——Skills 就是 Commands 的集合，而构建 Skill 的过程，就是写一个符合规范的 Python 模块 + 一个 Jinja2 模板 + 一份 YAML 规则配置。

• Skills 层（能力仓库）：这是项目的“知识沉淀层”。它不包含任何业务逻辑，只存放可复用的 Prompt 模板、校验规则（如rules/python-flake8.yaml）、代码片段库（snippets/java-spring-security/）、甚至预训练的小型分类器（用于自动识别代码风格）。当你运行claude-code code:review --level=strict，它会自动加载skills/review/strict_rules.yaml中定义的 17 条检查项，并将它们注入到 prompt 中。这解释了为什么搜索“claude code skills”会跳出一堆教程——因为 Skills 是可插拔、可共享、可版本化的。你可以把团队内部的《微服务日志规范》写成rules/microservice-logging.yaml，提交到公司内网 Git，所有成员pip install -e git+https://intranet/git/skills-log-rules就能同步使用。这才是“开源众包”在工程实践中的真实形态：不是所有人一起写同一个 repo，而是每个人贡献自己领域最深的那块“规则砖”。

提示：不要试图把所有功能塞进一个 Command。我早期犯过一个典型错误：写了一个code:all-in-one命令，试图让它完成从需求分析到部署脚本生成的全部流程。结果是每次修改一个小逻辑，都要重新测试整个长链条，CI 构建时间飙升到 8 分钟，且一旦中间某步失败，根本无法定位是哪个环节出了问题。后来彻底拆分为req:parse,arch:design,code:gen,test:gen,deploy:gen五个独立 Command，每个都有自己的单元测试和 mock，现在 PR 合并前的自动化检查只要 42 秒，且失败时能精确告诉你“test:gen在处理UserServiceTest.java时因@MockBean注解缺失而报错”。

2.2 为什么放弃 GUI，选择 CLI 作为主入口？

你可能疑惑：都 2024 年了，为什么还要搞 CLI？不是有那么多“claude code 桌面版”、“claude code ui”吗？答案很务实：CLI 是唯一能无缝集成进现有开发流水线的界面。一个真实的开发场景是这样的：你在一个 Spring Boot 项目里，刚写完UserServiceImpl.java，想立刻为它生成单元测试。如果你用桌面版，得切换窗口、拖拽文件、点选模板、等待渲染、再复制粘贴回 IDE——至少 25 秒。而用 CLI，你在 IntelliJ 的 Terminal 里敲：

claude-code test:gen --class UserServiceImpl --coverage=85% --mock-strategy=mockito

回车，3.2 秒后src/test/java/com/example/UserServiceImplTest.java就已创建完毕，且光标自动跳转到新文件第一行。更重要的是，这条命令可以被写进Makefile：

test-gen: @claude-code test:gen --class $(filter-out $@,$(MAKECMDGOALS)) --coverage=85% .PHONY: test-gen

然后你只需make test-gen UserServiceImpl，它就自动执行。它还能被集成进 pre-commit hook：

# .pre-commit-config.yaml - repo: https://github.com/your-org/claude-code-skills rev: v1.2.0 hooks: - id: code-review args: [--level=medium]

每次git commit前，自动对改动的 Java 文件做代码审查。GUI 做不到这点。它无法被脚本化、无法被 CI 服务器调用、无法被纳入 GitOps 流程。所谓“claude code 官网中文版”、“claude code 安装教程”，如果最终只是让你多装一个图形程序，那它和十年前的代码生成器没有本质区别。而本项目选择 CLI，是把 AI 编程能力当作一个基础设施组件来设计，就像git、mvn、docker一样，成为你每天敲击键盘时自然延伸的一部分。

2.3 开源协议与协作模式：为什么是 MIT，而不是 AGPL？

项目采用 MIT 协议，这绝非偶然。MIT 的核心精神是“最小限制，最大自由”。它允许任何人将本项目代码用于商业产品、闭源项目、甚至硬件设备（比如你搜到的 “plfm_radar：一个把相控阵雷达开源到 pcb、fpga 和 gui 的硬核项目”，其固件生成模块就可以直接集成claude-code的hardware:gen-verilogCommand）。对比之下，AGPL 要求任何网络服务形式的衍生作品都必须开源，这会直接扼杀企业用户的采用意愿——没人愿意为一个内部代码审查工具，被迫开源整个 DevOps 平台。MIT 协议也完美契合“开源众包”理念：一个贡献者提交了一个commands/db:migrate，他不需要关心你的公司是否用它来生成生产环境 SQL，他只希望自己的工作能被更多人看见、使用、改进。这也是为什么项目 README 里明确写着：“欢迎提交 PR，但请遵守三原则：1. 每个 Command 必须有对应单元测试；2. 所有 Prompt 模板必须提供英文+中文双语注释；3. 新增 Skills 必须附带benchmark/目录下的性能对比数据（vs baseline Claude API）”。它不靠许可证约束，而靠清晰、可执行的贡献规范来保障质量。

3. 核心细节解析与实操要点：从安装到第一个可运行的 Command

3.1 环境准备：为什么推荐 Poetry 而非 Pipenv 或纯 pip？

安装的第一步，往往决定了后续半年的维护成本。本项目官方推荐使用Poetry，而非更常见的pipenv或裸pip install。原因有三：

1. 锁定精确依赖版本，杜绝“在我机器上能跑”陷阱：Poetry 的poetry.lock文件不仅记录包名和版本，还记录每个包的 exact hash（如requests==2.31.0 [sha256:abc123...]）。这意味着无论你在 macOS、Ubuntu 22.04 还是 Windows WSL2 上poetry install，安装的jinja2都是完全相同的二进制 wheel。我曾遇到一个坑：pip install jinja2在不同系统上默认安装jinja2==3.1.2或3.1.3，而3.1.3有个 bug，会导致prompt_template.j2中的{% for %}循环在处理空列表时抛KeyError。用 Poetry 锁定jinja2==3.1.2后，问题消失。pipenv的Pipfile.lock也做类似事，但它对 Windows 路径处理有历史 bug，且pipenv install速度比 Poetry 慢 40%。

2. 虚拟环境管理与项目绑定，避免全局污染：poetry init会自动为你创建一个名为venv的隔离虚拟环境（路径如~/.cache/pypoetry/virtualenvs/claude-code-xxxx-py3.11），所有依赖都装在这里。你无需手动python -m venv venv && source venv/bin/activate，poetry shell一条命令搞定。更重要的是，Poetry 的虚拟环境是项目感知的：当你cd进项目目录，poetry shell自动激活对应环境；cd出去，环境自动退出。而pipenv的pipenv shell有时会激活错误的环境，尤其当你有多个同名项目时。

3. 发布与依赖管理一体化，简化 Skills 共享：当你想把自己的my-custom-doc-genCommand 打包成一个可pip install的包时，Poetry 的pyproject.toml里只需加几行：

   [tool.poetry.dependencies] python = "^3.11" jinja2 = "^3.1.2" [tool.poetry.group.dev.dependencies] pytest = "^7.4" [build-system] requires = ["poetry-core"] build-backend = "poetry.core.masonry.api"

   然后poetry build && poetry publish，就完成了。pipenv没有内置的发布流程，你需要额外配setup.py，极易出错。

实操步骤（macOS/Linux）：

# 1. 安装 Poetry（官方推荐方式） curl -sSL https://install.python-poetry.org | python3 - # 2. 克隆项目（注意：不是 fork，先克隆原 repo） git clone https://github.com/anthropic-community/claude-code.git cd claude-code # 3. 创建并激活虚拟环境（Poetry 自动完成） poetry install # 4. 激活 shell，此时命令行前缀会显示 (claude-code-xxxx) poetry shell # 5. 验证安装（应输出版本号和帮助信息） claude-code --version claude-code --help

注意：Windows 用户请确保已安装 Microsoft C++ Build Tools（用于编译cryptography等依赖），并在 PowerShell 中运行Set-ExecutionPolicy RemoteSigned -Scope CurrentUser解除脚本执行限制。不要用 CMD，PowerShell 是 Poetry 的首选。

3.2 API 密钥配置：安全存储与多环境切换

Claude Code 本身不托管模型，它需要你提供 Anthropic 的 API Key。项目绝不允许你把 key 写在代码里或config.yaml中。它采用分层密钥管理：

• 最高优先级：环境变量ANTHROPIC_API_KEY
  这是最安全的方式，key 只存在于当前 shell 会话中。claude-code启动时会首先检查此变量。你可以在.zshrc或.bash_profile中添加：

  export ANTHROPIC_API_KEY="sk-ant-api03-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

  但注意：永远不要将此行提交到 Git！务必在项目根目录的.gitignore中加入*.env和config/*.yaml。

• 次优先级：~/.anthropic/credentials文件
  如果你不希望 key 长期驻留内存，可以创建此文件（mkdir -p ~/.anthropic && touch ~/.anthropic/credentials），内容为：

  [default] api_key = sk-ant-api03-...

  文件权限必须设为600（仅所有者可读写）：chmod 600 ~/.anthropic/credentials。项目会自动读取此文件的[default]section。

• 最低优先级：项目级config/credentials.yaml（仅限开发测试）
  此文件绝对禁止提交，仅用于本地快速验证。结构为：

  default: api_key: "sk-ant-api03-..." staging: api_key: "sk-ant-api03-staging-..." production: api_key: "sk-ant-api03-prod-..."

  然后你可以用claude-code --profile staging test:gen ...切换环境。这直接回应了热搜词“claude code接入deepseek”——如果你要接入其他模型（如 DeepSeek-Coder），只需在此文件中新增一个 profile，然后在 Command 的run()方法里根据args.profile加载对应 key 和 base_url。

3.3 第一个 Command 实战：code:hello的诞生与调试

别急着跑复杂命令。我们先亲手创建一个最简单的code:hello，它会生成一个hello.py文件，内容为print("Hello from Claude Code!")。这能让你彻底理解 Command 的骨架。

步骤 1：创建 Command 模块
在claude-code/commands/目录下新建文件code_hello.py：

# commands/code_hello.py import os from pathlib import Path from typing import Optional from claude_code.agents.base import BaseAgent from claude_code.utils.filesystem import write_file def run( output_path: Optional[str] = None, message: str = "Hello from Claude Code!", ) -> str: """ Generate a simple hello world script. Args: output_path: Path to save the generated file. If None, uses current dir. message: Custom message to print. Returns: Path to the generated file. """ if output_path is None: output_path = "hello.py" content = f'print("{message}")\n' write_file(output_path, content) return output_path

步骤 2：创建 Prompt 模板（即使简单命令也需要）
在claude-code/prompts/目录下新建code/hello.j2：

# {{ context.message }} - Generated by Claude Code {{ context.version }} # Do not edit manually. This file is auto-generated. print("{{ context.message }}")

注意：.j2后缀表示 Jinja2 模板，{{ context.message }}是占位符。

步骤 3：注册 Command 到 CLI
编辑claude-code/cli.py，找到@click.group()下方的@cli.command()区域，添加：

@cli.command() @click.option("--output-path", "-o", help="Path to save hello.py") @click.option("--message", "-m", default="Hello from Claude Code!", help="Custom message") def code_hello(output_path, message): """Generate a simple hello world Python script.""" result = run(output_path=output_path, message=message) click.echo(f"✅ Generated: {result}")

步骤 4：安装并测试
在项目根目录下，确保已激活 Poetry 环境，然后：

# 重新安装（使新命令生效） poetry install # 运行 claude-code code-hello --message "Hello, World! 👋" # 查看结果 cat hello.py # 输出：print("Hello, World! 👋")

实操心得：我第一次写 Command 时，把write_file写成了open(...).write()，结果没加close()，导致文件句柄泄露。后来发现项目 utils 里已有健壮的write_file()，它内部用了with open() as f:。所以，永远优先使用项目提供的 utils 函数，而不是自己造轮子。这是踩过坑后总结的铁律。

4. 实操过程与核心环节实现：构建一个生产级的code:refactorCommand

4.1 需求分析：为什么code:refactor是项目中最复杂的 Command？

code:refactor不是简单的“重命名变量”或“提取方法”。它要解决的是跨框架、跨语言、带约束的语义重构。例如，将一个用JDBC直连数据库的 Java 类，重构为使用Spring Data JPA的版本。这要求 Command 必须：

• 理解源代码语义：不能只做字符串替换，要解析 AST（抽象语法树），识别Connection conn = DriverManager.getConnection(...)是数据库连接。
• 生成符合目标框架规范的代码：JPA要求@Entity,@Id,@Repository，且方法签名要匹配CrudRepository接口。
• 保持行为一致性：重构后的代码，其对外 API（方法名、参数、返回值）必须和原来一致，否则下游调用会崩溃。
• 提供可验证的 Diff：生成前后代码的差异，必须是人类可读、可审查的。

这解释了为什么热搜词里有 “curor agents怎么改中文”、“claude code /agents”——code:refactor的背后，是一个RefactorAgent，它协调了CodeParserAgent（解析源码）、FrameworkMapperAgent（映射 JDBC->JPA 规则）、CodeGeneratorAgent（生成新代码）和DiffVerifierAgent（比对差异）四个子 Agent。

4.2 核心实现：四步走，每一步都是硬核工程

步骤 1：AST 解析与上下文提取（code_parser.py）

我们不手写 AST 解析器。项目依赖tree-sitter（比ast模块更精准，支持多种语言）和tree-sitter-java语言库。code:refactor的第一步是：

from tree_sitter import Language, Parser import tree_sitter_java # 加载 Java 语言库 JAVA_LANGUAGE = Language(tree_sitter_java.language()) parser = Parser() parser.set_language(JAVA_LANGUAGE) # 解析源文件 with open("UserService.java", "rb") as f: tree = parser.parse(f.read()) # 提取关键节点：类名、方法列表、SQL 字符串字面量 root_node = tree.root_node class_name = root_node.child_by_field_name("name").text.decode() methods = [] for node in root_node.children: if node.type == "method_declaration": method_name = node.child_by_field_name("name").text.decode() # 提取方法体内所有 "SELECT * FROM users" 这样的字符串 sql_strings = extract_sql_literals(node) methods.append({"name": method_name, "sql": sql_strings})

extract_sql_literals()是一个递归函数，遍历 AST 节点，找string_literal类型的节点，并检查其内容是否匹配 SQL 模式。这比正则表达式可靠得多，因为它知道字符串在语法树中的确切位置。

步骤 2：规则映射与 Prompt 渲染（framework_mapper.py）

有了 AST 提取的上下文，下一步是决定如何重构。这由rules/java-jdbc-to-jpa.yaml驱动：

target_framework: spring-data-jpa mappings: - source_pattern: "Connection conn = DriverManager.getConnection(...);" target_template: "@Autowired private UserRepository userRepository;" explanation: "Replace manual connection with Spring-managed repository" - source_pattern: "PreparedStatement ps = conn.prepareStatement(\"SELECT * FROM users\");" target_template: "List<User> users = userRepository.findAll();" explanation: "Replace raw SQL with JPA findAll()"

code:refactor的run()方法会加载此 YAML，遍历methods列表，对每个sql字符串，匹配source_pattern，然后用target_template渲染 Jinja2 模板：

{# prompts/refactor/jdbc-to-jpa.j2 #} You are a senior Java architect. Refactor the following JDBC-based method to use Spring Data JPA. Do NOT change the method signature or business logic. Only replace database access code. Original method: {{ context.original_method }} Rules: {% for rule in context.rules %} - {{ rule.explanation }} → {{ rule.target_template }} {% endfor %} Output ONLY the refactored Java method body, no explanations, no markdown.

注意：Output ONLY...这句指令至关重要。它强制 Claude 只输出代码，避免它画蛇添足地加// This is the refactored version这样的注释，保证输出可直接写入文件。

步骤 3：代码生成与注入（code_generator.py）

LLM 的输出是纯文本，但我们需要把它注入到正确的 AST 位置。这里用到了tree-sitter的edit功能：

# 获取原始方法节点的起止字节位置 method_node = find_method_node(root_node, "findUserById") start_byte = method_node.start_byte end_byte = method_node.end_byte # LLM 输出的新方法体 new_body = "return userRepository.findById(id).orElse(null);" # 构造新的方法节点文本（保留原有签名，只替换方法体） new_method_text = f"""public User findUserById(Long id) {{ {new_body} }}""" # 用 new_method_text 替换原始字节范围 new_source = ( source_bytes[:start_byte] + new_method_text.encode() + source_bytes[end_byte:] )

这确保了重构后的文件，除了方法体，其他所有内容（注释、空行、导入语句）都保持原样。

步骤 4：Diff 生成与人工审核（diff_verifier.py）

最后一步，生成人类可读的差异报告：

import difflib with open("UserService.java", "r") as f: old_lines = f.readlines() with open("UserService-refactored.java", "r") as f: new_lines = f.readlines() diff = difflib.unified_diff( old_lines, new_lines, fromfile="UserService.java", tofile="UserService-refactored.java", lineterm="" ) print("".join(diff))

输出是标准的git diff格式，可直接粘贴到 PR 描述中，供同事 review。项目还提供了--dry-run参数，只输出 diff，不实际写入文件，这是上线前必做的一步。

注意事项：code:refactor默认使用claude-3.5-sonnet，但如果你的ANTHROPIC_API_KEY对应的是claude-3-haiku（更便宜但能力弱），它可能无法正确解析复杂 AST。因此，项目在config/model_preferences.yaml中定义了 fallback 链：

code:refactor: primary: claude-3.5-sonnet fallback: claude-3-opus timeout: 60

当sonnet在 60 秒内未返回有效结果时，自动降级到opus。这是应对 API 限流或模型抖动的必备容错机制。

4.3 性能优化：如何让code:refactor在 5 秒内完成？

一个 200 行的 Java 类，code:refactor从启动到生成 diff，实测平均耗时 4.7 秒。这背后有三项关键优化：

1. Prompt 缓存（Prompt Caching）：code:refactor的 prompt 模板虽然固定，但每次渲染的context（如original_method）不同。项目实现了基于context的 SHA256 哈希缓存。如果对同一个UserService.java的findUserById方法连续两次运行，第二次会直接从~/.claude-code/cache/读取上次 LLM 的响应，跳过 API 调用。缓存键为sha256(f"{template_content}_{json.dumps(context, sort_keys=True)}")。

2. 并发请求（Concurrent Requests）：当你要重构一个类里的 5 个方法时，code:refactor不会串行调用 5 次 API。它会把 5 个方法的 prompt 打包成一个 batch 请求（使用 Anthropic 的messagesAPI 的max_tokens和stop_sequences控制），一次返回 5 个结果。这减少了网络往返延迟，提升吞吐量。

3. 本地 AST 缓存（Local AST Cache）：tree-sitter解析一个 200 行文件约需 12ms。项目在~/.claude-code/ast-cache/下，以文件路径哈希为 key，缓存解析后的tree对象。下次运行时，若文件 mtime 未变，则直接加载缓存的 tree，省去解析开销。

5. 常见问题与排查技巧实录：那些只有亲手踩过才知道的坑

5.1 典型问题速查表

5.2 独家避坑技巧

技巧 1：用--verbose和--log-file定位超时问题
当code:refactor卡住不动时，别猜。加上--verbose参数：

claude-code code:refactor --file UserService.java --target-framework spring-data-jpa --verbose

它会输出每一步的耗时：

[INFO] Parsing UserService.java with tree-sitter... ✅ 12ms [INFO] Loading rules from rules/java-jdbc-to-jpa.yaml... ✅ 3ms [INFO] Rendering prompt template... ✅ 8ms [INFO] Sending request to Anthropic API... ⏳ [WARNING] API request timed out after 60s. Falling back to claude-3-opus...

如果看到Sending request... ⏳卡住，说明是网络或 API 问题。此时立即加--log-file debug.log，它会把完整的 HTTP 请求头、body、响应（含 error）写入日志，方便你发给 Anthropic 支持。

技巧 2：Prompt 调试的黄金三步法
当你发现 LLM 生成的代码总是漏掉某个import，不要直接改 prompt。按顺序做：

1. Step 1：检查 AST 提取：运行claude-code debug:ast --file UserService.java，它会输出解析出的所有方法、变量、SQL 字符串。确认你要重构的方法是否被正确识别。
2. Step 2：检查规则匹配：运行claude-code debug:rules --file UserService.java --rule-set java-jdbc-to-jpa，它会输出每条规则的匹配结果（Matched/Not matched）。确认你的 SQL 字符串是否触发了正确的source_pattern。
3. Step 3：检查 Prompt 渲染：运行claude-code debug:prompt --template refactor/jdbc-to-jpa.j2 --context '{"original_method": "..."}'，它会输出最终发送给 LLM 的完整 prompt 文本。复制这段文本，粘贴到 Anthropic Playground 中手动测试，观察 LLM 的输出。90% 的问题，都能在这三步中定位到根源。

技巧 3：为团队定制Skills的版本控制策略
当你们团队贡献了 10 个新的code:xxxCommand，如何管理？我的做法是：

• 所有 Skills 放在独立 Git 仓库your-org/claude-code-skills。
• 主项目pyproject.toml中，dependencies写为：

  [tool.poetry.dependencies] claude-code-skills = { git = "https://github.com/your-org/claude-code-skills.git", subdirectory = "skills", rev = "v1.0.0" }

• 每次发布新 Skills，打 Git tagv1.0.0，更新rev。这样，所有成员poetry update就能同步到经过 QA 的稳定版本，而不是main分支上可能不稳定的代码。这比直接pip install -e git+...更安全可控。

我个人在实际操作中的体会是：AI 编程工具的价值，不在于它能生成多少行代码，而在于它能否把**程序员最不愿干、最容易出错、最