1. 总览与目的

本指南把 CLI 一键批改、结构化/AST 级改造 与 工程化审计/回滚 规范沉淀为可复制的团队实践，并以「Vibe Coding」的回合制提示脚本驱动你与 Claude/IDE Agent 的高效协作。核心宗旨：

• 能用 一条命令 解决的问题，绝不用十次小步编辑。
• 所有批量变更可预览、可回滚、可审计，并通过 PR/CI 把好质量关。
• 文本替换覆盖不了时，果断切换 comby/semgrep/ts-morph/jscodeshift 等语义手术刀。

2. 会话启动（Kickoff Prompt）

每次与 Claude/Agent 协作，请先发送以下开场白：

请读取仓库根目录的 claude.md（或本 HTML 的 Markdown 版）并严格遵循。
任何批量操作必须先输出：
1) 预览命令与预计命中数；
2) NULL 分隔文件清单命令；
3) 两套执行方案（A 文本替换流水线；B 语义/AST codemod）；
4) 验证步骤（tsc --noEmit、单测、回滚计划）。
请提供 macOS 与 GNU/Linux 双写（必要时附 PowerShell）。未经我确认，不得写回文件。

3. 核心原则

• CLI > 多步编辑 One pipeline > Many tiny edits。
• 先小样本 预览 → 计数 → 小样本验证 → 全量。
• 可逆性 备份或独立分支/工作树，确保可回滚。
• 范围收敛 通过扩展名/目录白名单与忽略目录缩小影响面。
• 语义优先 涉及语法/类型/导入重写时，切换到结构化/AST 工具。

4. 环境与工具

5. 安全基线：预览 → 备份 → 替换 → 验证 → 审计

5.1 预览与列文件

# 预览匹配（含行号）
rg -n -S -g '!node_modules' '<PATTERN>'

# 仅列文件（NULL 分隔）
rg -l -0 -S -g '!node_modules' '<PATTERN>'

5.2 替换（优先 sd）

# sd（跨平台更稳）
rg -l -0 -S -g '!node_modules' 'OLD' | xargs -0 sd 'OLD' 'NEW'

# macOS BSD sed（带备份）
rg -l -0 -S -g '!node_modules' 'OLD' | xargs -0 sed -i'.bak' 's/OLD/NEW/g'

# GNU sed（可加 .bak）
rg -l -0 -S -g '!node_modules' 'OLD' | xargs -0 sed -i 's/OLD/NEW/g'

5.3 验证与清理

git diff -- . ':!*.bak' | sed -n '1,200p'

# 类型与测试
tsc --noEmit
npm test -i   # 或 pnpm test -i

# 确认无误再删备份
fd -0 -e bak -E node_modules | xargs -0 rm

6. 决策树：文本替换 vs 结构化/AST 改造

1. 文本替换可行：模式稳定、上下文单一、对语义无影响 → 走 S&R。
2. 担心误伤字符串/注释：需要结构约束 → 走 comby/semgrep。
3. 涉及语法/类型/导入重写：需理解语法树/符号 → 走 ts-morph / jscodeshift。

7. 常用一键流水线（Find → Pipe → Transform）

7.1 按扩展名/子树限定

fd -0 -t f -e ts -e vue src -E node_modules | xargs -0 sd 'OLD' 'NEW'

7.2 多行模式（交给 perl 读整文件）

rg -l -0 -S 'PATTERN_SPANNING_LINES' \
  | xargs -0 perl -0777 -pe "s/PATTERN_SPANNING_LINES/REPLACEMENT/s" -i.bak

7.3 JSON 原位变更（无读写竞态）

jq '.compilerOptions.module="ESNext"' tsconfig.json | sponge tsconfig.json
git diff tsconfig.json

7.4 并发加速

fd -0 -t f -e ts -E node_modules | xargs -0 -P 8 sd 'OLD' 'NEW'

8. 结构化/语义改造工具食谱

8.1 comby（结构模板）

# 将 interface :[T] extends :[P] { :[body] } → interface :[T] { :[body] }
comby 'interface :[T] extends :[P] { :[body] }' \
      'interface :[T] { :[body] }' -matcher .ts -d src -i

8.2 semgrep --autofix（规则可复用）

# semgrep.yml
rules:
- id: drop-empty-extends
  languages: [typescript]
  pattern: |
    interface $T extends $P {}
  fix: |
    interface $T {}
  message: remove empty extends
  severity: INFO

semgrep --config semgrep.yml --autofix

8.3 ts-morph（TypeScript AST）

// scripts/codemod/remove-empty-extends.ts
import { Project, SyntaxKind } from "ts-morph";
const project = new Project({ tsConfigFilePath: "tsconfig.json" });
project.getSourceFiles("src/**/*.ts").forEach(sf => {
  sf.getInterfaces().forEach(i => {
    if (i.getHeritageClauses().length && i.getMembers().length === 0) {
      i.getHeritageClauses().forEach(h => h.remove());
    }
  });
});
await project.save();

pnpm ts-node scripts/codemod/remove-empty-extends.ts

8.4 jscodeshift（JS/TS 常见迁移）

适合 import 迁移、API 变更、命名重写；需先给出小样本 diff，再全量执行。

9. Vibe Coding 回合制脚本（人机协作）

1. Round 1 -- 任务定义：目标、范围与排除，要求输出预览/清单/两套方案/验证步骤与风险评估。
2. Round 2 -- 预览确认：Claude 给命中数；你运行预览/回贴样本；共同收敛模式与范围。
3. Round 3 -- 方案选择：在 A 文本与 B 语义间权衡；Claude 输出可复制命令（含平台差异）。
4. Round 4 -- 写回与验证：带备份或分支；立刻跑 tsc --noEmit 与单测。
5. Round 5 -- 审计/PR：粘贴命令、命中、scope、diff 片段与验证清单；CI 守门。

10. 场景模板库（可直接复用）

10.1 全局替换（安全基线）

我要把 OLD 全局替换为 NEW（仅 src/**/*.ts，排除 node_modules）。
请给：预览、NULL 清单、sd 与 sed 两套执行、macOS/GNU 双写、备份策略、验证命令、清理命令，并估算命中数。

10.2 interface extends 修复

定位 interface <Name> extends <Base>。优先去除空继承；若父接口改名做映射；
多继承冲突给出 type = & 替代。依次输出：1) 预览/父接口频次；
2) comby 方案（空体时删除 extends）；3) ts-morph 方案；4) 验证与回滚。

10.3 import 迁移（语义敏感）

把 from 'old-lib' 迁到 from 'new-lib'，处理默认导出/命名导出差异。
先 rg 预览→再 jscodeshift 小样本→再全量。输出脚本与运行命令、回滚方案。

10.4 JSON schema 统一

在 tsconfig.json 中把 compilerOptions.module 统一为 ESNext。
请输出 jq+sponge 命令、验证命令与失败回滚方式，并在 PR 贴差异片段。

11. PR/CI 守门与度量

11.1 PR 模板（Claude 自动生成建议）

### Mass Edit Summary
- Commands used: