ClaudeCode：面向生产系统的AI诊断工具与工程决策助手-平芜编程栈

1. 这不是另一个“代码助手”，而是一把能拆解真实工程问题的手术刀

ClaudeCode 这个名字刚出来的时候，我第一反应是：又一个带 Code 后缀的 AI 工具？点开官网扫了一眼文档，没急着装插件，先在本地搭了个最小验证环境——用它读一段我们团队上周刚上线、但日志里反复报错的 Kafka 消费者重平衡逻辑。结果它没直接给我改好的代码，而是先画出三行文字：

“检测到消费者组order-processor-v3在rebalance_timeout_ms=60000下频繁触发REBALANCE_IN_PROGRESS；当前max_poll_records=500导致单次拉取耗时波动达 42~89ms；建议将session_timeout_ms从 10s 提至 45s，并拆分poll()中的业务处理为异步队列。”

那一刻我就知道，ClaudeCode 和市面上大多数“写代码快一点”的工具根本不在一个维度上。它不满足于当语法补全器或 Stack Overflow 搬运工，而是真正站在系统工程师视角，把一段代码当作可运行的活体系统来诊断。它能识别出@Scheduled(fixedDelay = 5000)和@Async注解共存时隐含的线程池饥饿风险；能从try-catch块里捕获的NullPointerException反推出上游 DTO 字段未做@NotNull校验；甚至能根据log.info("Processed {} items", list.size())这行日志，结合上下文判断出该 list 实际为空却未被拦截，进而定位到 MyBatis 的resultType配置错误。

这背后不是简单的模式匹配，而是对 Java/Python/Go 等主流语言的 AST（抽象语法树）深度解析能力，叠加对 Spring Boot、Django、FastAPI 等框架生命周期的语义理解。它不像 Copilot 那样依赖局部上下文猜意图，而是把整个项目结构、配置文件、日志格式、甚至 CI/CD 脚本都纳入推理范围。比如你给它看一个失败的 GitHub Actions 日志，它能直接指出.github/workflows/deploy.yml第 37 行run: npm run build缺少--max-old-space-size=4096参数，因为从前面npm install的内存占用曲线能看出 Node.js 堆已逼近 3.8GB。

所以如果你正被以下问题卡住：改了 3 天的 bug 依然复现不了、新同事看不懂遗留系统的调用链、线上慢 SQL 查不出根源、或者每次上线前都要手动核对 27 个配置项是否同步——ClaudeCode 不是锦上添花的玩具，而是能切开这些混沌问题的手术刀。它适合两类人：一类是每天和生产环境“搏斗”的后端/运维工程师，另一类是想快速吃透复杂开源项目的开发者——比如你想三天内搞懂 Apache Flink 的 Checkpoint 机制，直接把flink-runtime模块源码喂给它，它会按“触发条件→状态快照→网络传输→持久化落盘→故障恢复”这条主线给你梳理出 12 个关键类和它们的协作关系图。

别把它当成聊天机器人。它的价值，永远藏在你按下回车键之前——你输入的问题越具体、上下文越完整，它输出的解剖报告就越锋利。

2. 核心能力拆解：为什么它能看懂“代码背后的系统”

2.1 代码理解层：不止于语法，更懂框架语义与运行时契约

ClaudeCode 的底层能力，首先体现在对代码“活态”的理解深度。普通 LLM 看 Python 代码，可能只识别出for item in data:是循环；而 ClaudeCode 会结合data的类型注解（如List[Dict[str, Any]]）、上游fetch_data()函数的返回值契约（查看其 docstring 或类型定义），以及下游process_item(item)的参数签名，推断出这个循环实际承载的是“批量数据清洗管道”。这种理解直接决定了它能否给出有效建议。

举个真实案例：我们有个 Django 视图函数，接收request.GET.get('page')并传给Paginator。ClaudeCode 在分析时指出：“page参数未做int()强转且无默认值，当 URL 中缺失 page 参数时，Paginator.page(None)将抛出EmptyPage异常，但当前except EmptyPage块仅返回 HTTP 404，未记录原始请求参数。建议在try块首行添加logger.debug("Page param received: %s", request.GET.get('page'))。” —— 它不仅看出异常路径，还意识到日志缺失对问题排查的致命影响，这源于它对 Django 请求生命周期（request → view → response）和日志最佳实践的内建知识。

这种能力的关键支撑有三点：

多粒度 AST 解析：它不只解析单个文件，而是构建跨文件的符号引用图。当你问“UserService.update_profile()最终调用了哪些数据库操作？”，它能顺着update_profile → UserRepository.save() → JdbcTemplate.update()这条链，穿透 Spring 的代理层，定位到实际执行的 SQL 模板。
框架感知引擎：内置主流框架的“行为模式库”。例如识别出@Transactional(propagation = Propagation.REQUIRES_NEW)时，会自动关联到事务传播机制的潜在陷阱（如新事务中无法读取未提交的父事务数据），并提示“此处若需读取父事务数据，请改用Propagation.SUPPORTS并确保调用方已开启事务”。
运行时契约推断：通过分析assert、if not x: raise ValueError、@validate_arguments等约束表达式，反向构建函数的前置/后置条件。当我们给它一段 Go 代码func parseConfig(cfg string) (*Config, error)，它能从if len(cfg) == 0 { return nil, errors.New("config empty") }推断出该函数的前置条件是cfg != ""，并在后续分析中以此为前提验证调用方是否做了空值检查。

提示：要激活这项能力，必须提供足够上下文。单独扔一个def calculate_tax(amount):给它，它只能泛泛而谈；但若附上# type: amount: float, currency: str的类型注解，以及调用处calculate_tax(order.total, order.currency)，它就能结合order类的定义，判断出total是否可能为负数，并建议增加if amount < 0: raise ValueError("Amount cannot be negative")。

2.2 系统诊断层：把日志、配置、监控数据变成可推理的证据链

ClaudeCode 最颠覆性的能力，是它能把传统上割裂的运维数据源，整合成一条连贯的因果链。这不是简单拼接，而是基于领域知识的主动关联。

我们曾遇到一个诡异问题：K8s 集群中某 Pod 内存使用率持续攀升至 95%，但top显示所有进程 RSS 总和仅 1.2GB。ClaudeCode 在分析kubectl describe pod输出、/proc/meminfo快照、以及应用 JVM 参数-Xmx2g -XX:MaxDirectMemorySize=512m后，给出结论：“检测到Cached内存占用达 3.8GB，远超Buffers和MemFree；结合 JVMMaxDirectMemorySize=512m，推测 Netty 的PooledByteBufAllocator未正确释放堆外内存。请检查ChannelHandler中ByteBuf.release()调用是否遗漏，并验证io.netty.leakDetection.level是否设为PARANOID。” —— 它把 Linux 内存管理、JVM 堆外内存机制、Netty 内存池实现细节全部串了起来。

这种诊断依赖三个核心模块：

日志模式引擎：能识别常见日志格式（Log4j2 的%d{ISO8601} [%t] %-5p %c{1} - %m%n、JSON 日志的{"level":"error","msg":"timeout"}），并提取关键字段。当它看到连续 5 条WARN [nioEventLoopGroup-3-1] i.n.u.ResourceLeakDetector - LEAK: ByteBuf.release() was not called，会立即关联到 Netty 内存泄漏。
配置一致性校验器：自动比对不同环境的配置差异。比如它发现application-prod.yml中spring.redis.timeout=2000，而application-dev.yml中为5000，同时RedisTemplate的setEnableTransactionSupport(true)在 prod 环境被注释掉，便会警告：“prod 环境 Redis 超时更短但禁用事务支持，高并发下易触发RedisConnectionFailureException，建议统一启用事务或延长超时。”
指标关联分析器：当提供 Prometheus 查询结果（如rate(http_request_duration_seconds_count{job="api"}[5m])和container_memory_usage_bytes{container="app"}），它能建立时间序列相关性。若发现 HTTP 错误率上升 300% 时内存使用率同步飙升，会建议检查@ControllerAdvice全局异常处理器是否在@ExceptionHandler中创建了大对象导致 GC 压力。

注意：它不会凭空生成监控数据。你需要明确提供kubectl top pods、cat /proc/meminfo、curl http://localhost:9090/metrics等原始输出。它的强大在于，能把这些碎片信息编织成一张网，而不是让你自己在黑暗中摸索连接点。

2.3 工程决策层：用成本-收益模型替代拍脑袋的技术选型

很多技术决策的失败，源于只考虑“能不能做”，忽略“值不值得做”。ClaudeCode 把工程经济学引入代码分析，强制你面对真实成本。

我们曾计划将一个 Python Flask 应用迁移到 FastAPI，理由是“性能更好”。ClaudeCode 在分析现有代码后给出评估：

迁移成本：需重写 17 个@app.route()装饰器为@app.get()，改造 9 个自定义RequestParser为 Pydantic 模型，替换flask-sqlalchemy为SQLModel（涉及 23 处db.session.add()调用）。预估工作量：3 人日。
收益测算：当前 QPS 1200，CPU 利用率峰值 45%；FastAPI 在同等负载下预计提升至 QPS 1800，CPU 降至 32%。但当前瓶颈在 PostgreSQL 连接池（max_connections=100已满），而非 Web 层。
替代方案：建议优先优化数据库连接池（pgbouncer配置调整），成本 0.5 人日，预计提升 QPS 至 1500+，且无需修改业务代码。

它甚至能计算技术债利息：分析出utils/date_helper.py中存在 4 个重复的datetime.strptime()调用，每个调用平均耗时 0.8ms。按日均 200 万次调用计算，年浪费 CPU 时间 = 0.0008s * 2e6 * 365 ≈ 584,000 秒 ≈ 6.76 天。而重构为缓存strptime函数的成本仅 2 小时，ROI（投资回报率）高达 80 倍。

这种决策支持的核心，是它内嵌的工程成本知识图谱：

对每种语言/框架，预置了典型操作的基准耗时（如 Pythonjson.loads()解析 1KB JSON 平均 0.3ms，Gojson.Unmarshal()为 0.05ms）；
对常见云服务，了解其计费模型（如 AWS Lambda 按 GB-秒计费，内存配置每提升 128MB，单价增加 12%）；
对开发流程，量化了变更影响（如修改一个被 37 个模块 import 的constants.py，平均需额外 2.3 小时进行回归测试）。

当你问“该不该用 Redis 缓存这个查询？”，它不会只说“可以”，而是列出：

当前查询平均耗时 120ms，缓存后降至 2ms，节省 118ms/次；
预估日均调用量 50 万，年节省 CPU 时间 = 118e-3 * 5e5 * 365 ≈ 21,550,000 秒；
Redis 实例月成本 $25，年 $300；
缓存失效策略（LRU）可能导致热点数据被挤出，需增加cache warming逻辑，开发成本 1 人日；
结论：净收益显著，但需同步实施缓存预热。

3. 实操指南：从零开始构建你的第一个 ClaudeCode 分析工作流

3.1 环境准备：轻量级 CLI + 企业级 IDE 插件双轨并行

ClaudeCode 提供两种主流接入方式，我强烈建议新手从 CLI 入手，老手再上 IDE 插件——因为 CLI 能让你看清它“吃了什么、吐出什么”，避免 IDE 插件的黑盒感。

CLI 方式（推荐入门）：

安装官方 CLI 工具：pip install claudecode-cli（Python 3.8+）；
获取 API Key：登录 claudecode.dev 控制台，进入API Keys页面创建新密钥（注意：生产环境务必启用 IP 白名单和密钥轮换）；
初始化配置：claudecode init --api-key sk-xxx --model claude-3-opus-20240229；
创建分析目录：mkdir ~/claudecode-analysis && cd ~/claudecode-analysis；

构建最小上下文包：

# 复制核心源码（限制在 5000 行内，避免 token 超限） find ../src -name "*.py" -exec head -n 100 {} \; > context.py # 附加关键配置 cp ../config/application-prod.yml ./config.yml # 附上最近 100 行错误日志 tail -n 100 ../logs/app-error.log > recent-errors.log

实操心得：不要试图把整个 Git 仓库丢给它。ClaudeCode 的 token 限制（Opus 模型约 200K tokens）意味着它需要你做“外科医生式”的上下文裁剪。我的经验是：聚焦在问题发生点的上下游 3 个文件（如报错的 Controller、调用的 Service、被调用的 DAO），加上直接相关的配置片段和精确的错误日志。一次分析只解决一个具体问题，效率远高于“全盘扫描”。

IDE 插件方式（VS Code / JetBrains）：

VS Code：安装ClaudeCode Assistant插件，配置ClaudeCode: Api Key和ClaudeCode: Model；
JetBrains：在Settings → Plugins搜索ClaudeCode，安装后重启；
关键设置：务必开启ClaudeCode: Include Project Structure（让插件自动索引项目依赖关系），并关闭ClaudeCode: Auto-Suggest on Type（避免干扰编码节奏，改为手动Ctrl+Shift+P → ClaudeCode: Analyze Selection）。

注意：IDE 插件的“智能上下文”功能虽强，但首次索引大型项目（>10 万行）可能耗时 5-8 分钟。建议在非高峰时段运行，或预先用 CLI 生成project-index.json文件供插件复用。

3.2 核心分析指令：从“查错”到“架构演进”的 5 种实战命令

ClaudeCode 的指令设计高度场景化。以下是我在生产环境中验证过的 5 个高频命令，覆盖从紧急救火到长期规划：

指令 1：精准定位崩溃根源（analyze-crash）

claudecode analyze-crash \ --source-file src/main/java/com/example/OrderService.java \ --error-log logs/error-20240520.log \ --stack-trace "java.lang.NullPointerException: Cannot invoke 'String.length()' because 'id' is null" \ --context-files src/main/resources/application.yml

它会输出：

根因定位：OrderService.processOrder()第 87 行调用userCache.get(id)返回 null，因id来自request.getParameter("userId")未校验；
修复建议：在processOrder()首行添加if (id == null || id.trim().isEmpty()) throw new IllegalArgumentException("userId required");；
防御加固：建议在UserCache的get()方法中增加Objects.requireNonNull(id, "Cache key cannot be null")断言。

指令 2：安全合规审计（audit-security）

claudecode audit-security \ --source-dir ./src \ --ruleset owasp-top10-2021 \ --output-format markdown

输出包含：

高危漏洞：src/utils/CryptoHelper.java使用Cipher.getInstance("AES")未指定模式和填充（默认 ECB，不安全），应改为Cipher.getInstance("AES/GCM/NoPadding")；
敏感信息泄露：src/config/DatabaseConfig.java中硬编码password = "dev123"，建议改用@Value("${db.password}")从环境变量注入；
合规差距：未实现 GDPR 要求的用户数据删除钩子（@EventListener监听UserDeletedEvent），需在UserRepository添加deleteByUserId()方法。

指令 3：性能瓶颈诊断（diagnose-performance）

claudecode diagnose-performance \ --profile-data jfr-recording.jfr \ --source-dir ./src \ --hot-methods "com.example.api.OrderController.handleRequest"

输出：

热点方法：handleRequest()中orderValidator.validate()占用 68% CPU 时间；
深层原因：validate()调用AddressService.geocode()发起外部 HTTP 请求，平均耗时 420ms；
优化方案：
- 短期：为geocode()添加@Cacheable(key="#address")（需配置 Redis CacheManager）；
- 长期：将地址解析服务下沉为内部 gRPC 调用，P99 延迟可降至 15ms。

指令 4：技术债可视化（visualize-tech-debt）

claudecode visualize-tech-debt \ --git-repo . \ --since "2023-01-01" \ --output debt-report.html

生成交互式 HTML 报告，包含：

债务分布图：按模块统计TODO注释数量（auth-service: 12 个，payment-gateway: 3 个）；
腐化趋势：utils/目录下DateHelper.java的圈复杂度从 2022 年的 8 升至 2024 年的 23，违反complexity < 15规则；
修复优先级：基于impact_score = (bug_rate * 0.4) + (test_coverage * 0.3) + (dev_velocity * 0.3)计算，auth-service的TokenGenerator类得分最高（0.92），应优先重构。

指令 5：架构演进推演（simulate-architecture）

claudecode simulate-architecture \ --current-arch current-arch.yaml \ --target-arch microservices.yaml \ --constraints "max-downtime: 30m, budget: $5000/month" \ --output migration-plan.md

输出分阶段迁移计划：

Phase 1（Week 1-2）：将user-service拆分为独立服务，使用 Spring Cloud Gateway 作路由，成本 $1200；
Phase 2（Week 3-4）：为order-service添加 Saga 模式补偿事务，需开发 3 个补偿接口，成本 $2100；
Phase 3（Week 5）：灰度发布，监控error_rate < 0.1%且p95_latency < 800ms后全量切换。

3.3 上下文构建技巧：如何喂给它“恰到好处”的信息

ClaudeCode 的输出质量，70% 取决于你提供的上下文质量。以下是经过 23 个真实项目验证的黄金法则：

法则 1：遵循“3-3-3”上下文原则

3 个文件：问题文件 + 其直接调用者 + 被调用者（如OrderController.java→OrderService.java→OrderRepository.java）；
3 个配置片段：application.yml中相关配置、Dockerfile的资源限制、CI/CD 脚本中的关键步骤；
3 行日志：错误发生前 1 行（INFO: Starting order processing）、错误行（ERROR: NullPointerException）、错误后 1 行（WARN: Falling back to default handler）。

法则 2：用“问题描述模板”替代模糊提问
❌ 低效提问：“这个代码怎么改？”
✅ 高效模板：

【现象】：用户提交订单后，前端显示“支付超时”，但支付网关日志显示交易成功。 【复现步骤】：1. 访问 /order/create；2. 输入金额 99.99；3. 点击支付；4. 30 秒后页面跳转失败。 【已排查】：确认 `PaymentGatewayClient` 的 `timeoutMs=30000`，`Ribbon` 的 `ConnectTimeout=5000`，`ReadTimeout=10000`。 【期望结果】：支付成功后跳转至 `/order/success?orderId=12345`。 【当前代码】：见 attached OrderController.java 第 142-158 行。

法则 3：主动提供“否定性证据”
很多问题的突破点，在于排除法。告诉 ClaudeCode “什么已经被验证过无效”，能极大缩小推理空间。例如：

“已验证：1.redis-cli PING返回PONG；2.application.yml中spring.redis.host配置正确；3. 同一 Pod 内其他服务可正常访问 Redis。但OrderService.cacheOrder()仍抛出RedisConnectionFailureException。”

法则 4：善用“领域术语”锚定理解
在提问中嵌入准确术语，能激活它的领域知识库。例如：

说 “@Transactional传播行为” 而非 “事务怎么传”；
说 “Pulsar的ackTimeout机制” 而非 “消息确认超时”；
说 “React的useEffect清理函数” 而非 “组件卸载时做的事”。

4. 避坑指南：那些只有踩过才懂的实战教训

4.1 Token 陷阱：为什么你的“完整项目分析”总失败？

最常被忽视的坑，是盲目追求“上下文越多越好”。ClaudeCode 的 Opus 模型虽支持 200K tokens，但实际分析中，有效上下文窗口远小于此。

我曾把一个 8 万行的 Spring Boot 项目（含所有*.java、*.yml、*.sql）打包喂给它，结果得到一长串Context length exceeded错误。后来发现，问题出在三个地方：

冗余注释膨胀：项目中大量// TODO: Refactor this method、/* This is a temporary fix */等注释，占用了 35% 的 token；
日志样本失真：我提供了 10MB 的app.log，其中 90% 是INFO级别健康检查日志，真正有用的ERROR日志仅 23 行；
二进制文件污染：误将target/classes/目录下的.class文件加入分析包，这些字节码被当作乱码解析，严重消耗 token。

解决方案：

预处理脚本（我日常使用）：

# 清理注释和空行 find ./src -name "*.java" | xargs sed -i '/^\s*\/\//d; /^\s*$/d' # 提取关键日志（仅 ERROR + WARN + 前后 3 行） grep -A3 -B3 -E "(ERROR|WARN)" logs/app.log | grep -v "^--$" > clean-logs.log # 排除二进制和构建产物 find . -name "*.class" -o -name "node_modules" -o -name "target" | xargs rm -rf

动态上下文加载：对超大项目，用claudecode load-context --dir ./src/core --depth 2先加载核心模块，分析后再用claudecode extend-context --file ./src/integration/PaymentAdapter.java按需追加。

实操心得：在claudecode init时，务必设置--max-tokens 150000（留 50K 余量给模型推理）。我的经验是，一个中等复杂度的微服务（3-5 个模块），有效上下文控制在 80K tokens 内效果最佳——相当于 1200 行精炼代码 + 50 行关键配置 + 200 行错误日志。

4.2 框架幻觉：当它“自信地编造”不存在的 API

ClaudeCode 的强项是理解主流框架，但面对小众或自研框架时，会出现“幻觉”——即基于训练数据中的相似模式，虚构出看似合理实则不存在的 API。

我们有个自研的DataSyncEngine，其配置类名为SyncConfig，有一个setBatchSize(int size)方法。ClaudeCode 在分析时却建议：“请调用SyncConfig.setBatchSize(int size, TimeUnit unit)以支持动态批处理”，并给出了一个完全不存在的重载方法签名。

识别幻觉的 3 个信号：

过度具体：建议的方法名包含非常规参数（如TimeUnit），而原框架文档从未提及；
缺乏上下文依据：建议中未引用任何你提供的源码行号或配置片段；
违反语言规范：如建议 Java 方法返回Optional<Void>（Java 不允许Void泛型）。

应对策略：

强制要求引用：在提问中明确写 “所有建议必须基于我提供的SyncConfig.java第 45-67 行代码”；
交叉验证：对任何“新 API”建议，立刻用grep -r "setBatchSize.*TimeUnit" ./src搜索代码库；
启用严格模式：CLI 中添加--strict-mode true，此时它会对不确定的建议标注[CONFIDENCE: LOW]并说明依据不足。

4.3 安全边界：为什么绝不能让它接触生产密钥？

这是红线中的红线。ClaudeCode 的设计原则是“不存储用户数据”，但任何上传到云端的文本，理论上都存在泄露风险。

我们曾因疏忽，在调试时把application-prod.yml全量上传，其中包含：

cloud: aws: access-key: AKIA... # 生产 AWS 密钥 secret-key: 87aF... # 生产 AWS 密钥 aliyun: oss: endpoint: https://oss-cn-hangzhou.aliyuncs.com access-key: LTAI... # 生产阿里云密钥

虽然 ClaudeCode 官方声明“所有请求经加密传输，且不持久化存储”，但作为负责任的工程师，我们必须假设：

传输链路中某个中间代理存在漏洞；
服务商内部审计日志意外暴露；
未来某次安全事件导致历史请求被追溯。

铁律清单：

✅允许上传：脱敏后的日志（user_id=***,email=***@***.com）、公开的 API 文档、开源框架源码；
❌绝对禁止：任何含access-key、secret-key、password、private-key、jwt-secret的文件；
⚠️谨慎处理：数据库连接字符串（必须替换jdbc:mysql://host:3306/db?user=prod&password=xxx为jdbc:mysql://host:3306/db?user=masked&password=***）；
🔒强制措施：在 CI/CD 流水线中加入grep -r -E "(access_key|secret_key|password|private_key|jwt_secret)" ./config/ && exit 1检查。

个人体会：我现在的标准操作是，所有上传前必过一道sed脚本：
sed -i 's/password: .*/password: "***"/g; s/access-key: .*/access-key: "AKIA***"/g; s/secret-key: .*/secret-key: "***"/g' config.yml
宁可多花 10 秒，也不赌万分之一的风险。

4.4 成本失控：如何避免账单变成“惊喜”

ClaudeCode 按 token 计费，而 token 消耗极易失控。一个未经优化的分析请求，可能消耗 50 万 tokens，按 $0.015/1K tokens 计算，就是 $7.5——这还只是单次分析。

我们团队曾因一个自动化脚本失误，连续 3 小时每分钟发起一次全量分析，最终账单高达 $2100。根源在于：

脚本未设置--max-tokens限制；
错误地将./logs/目录下所有日志（含 30 天归档）打包上传；
未启用--dry-run模式预估 token 消耗。

成本管控四步法：

预估先行：每次分析前，先运行claudecode estimate-tokens --files context.py config.yml errors.log，确认在预算内；
分级计费：为不同场景设置不同模型：
- 紧急故障排查：用claude-3-opus-20240229（$0.015/1K tokens）；
- 日常代码审查：用claude-3-sonnet-20240229（$0.003/1K tokens）；
- 文档生成：用claude-3-haiku-20240307（$0.00025/1K tokens）；
用量监控：在claudecode-cli配置中启用--usage-report true，每日邮件发送 token 消耗 Top 5 请求；
熔断机制：在脚本中加入if [ $(claudecode estimate-tokens ...) -gt 100000 ]; then echo "ABORT: Too many tokens"; exit 1; fi。

5. 进阶场景：超越代码，驱动工程效能的真实案例

5.1 案例一：用 ClaudeCode 重构遗留系统文档（某金融风控平台）

背景：一个运行 8 年的 Java 风控引擎，核心规则引擎RuleEvaluator.java有 12,000 行，无单元测试，文档仅有一份 2016 年的 Word 手册，且与代码严重脱节。

ClaudeCode 工作流：

静态分析：claudecode analyze-source --file RuleEvaluator.java --output ast-graph.dot，生成 AST 图谱，识别出 47 个核心规则类（CreditScoreRule、FraudPatternRule等）；
动态行为推断：提供 500 行生产日志（含INFO: Executing rule CreditScoreRule with score=720），让它反推各规则的触发条件和输出格式；
接口契约生成：claudecode generate-contract --input RuleEvaluator.java --output openapi.yaml，自动生成 OpenAPI 3.0 规范，包含所有规则的requestBody和responses；
文档合成：claudecode generate-docs --openapi openapi.yaml --template finance-rules.md，产出带执行流程图、输入输出示例、错误码表的 Markdown 文档。