# 变更审计记录：Kiro → Claude Code 全量迁移

| 字段 | 值 |
|------|-----|
| 日期 | 2026-04-05 15:36:04 |

## 操作摘要

NeoZQYY 项目从 Kiro IDE 迁移到 Claude Code。将 Kiro 的 steering 文档、hooks、skills、agents、MCP 配置、审计脚本全部迁移为 Claude Code 对应架构：steering → CLAUDE.md，hooks → `.claude/hooks/` Python 脚本，skills → `.claude/commands/`，MCP → `.mcp.json`，审计脚本合并为 `scripts/audit/prescan.py`。

迁移完成后，删除 `.kiro/` 下已迁移的目录（agents、hooks、scripts、settings、skills、state），仅保留 `specs/`（历史需求文档）和 `steering/`（原始对照）。

## 变更文件

### 新增

| 文件 | 说明 |
|------|------|
| `CLAUDE.md` | 根项目指导文件，合并所有 `inclusion: always` steering 文档 |
| `apps/etl/connectors/feiqiu/CLAUDE.md` | ETL 子目录指导，DWD 12 条 + DWS 26 条权威规范 |
| `db/CLAUDE.md` | 数据库子目录指导，双 Schema RLS 规则、迁移格式 |
| `.mcp.json` | MCP 配置，从 `.kiro/settings/mcp.json` 迁移 |
| `.claude/settings.json` | 注册 3 个 hooks（SessionStart / PostToolUse / Stop） |
| `.claude/hooks/session_start_context.py` | SessionStart hook，启动时报告项目状态 |
| `.claude/hooks/post_edit_audit_reminder.py` | PostToolUse hook，高风险文件编辑后提醒审计 |
| `.claude/hooks/stop_audit_check.py` | Stop hook，会话结束前检查未审计变更 |
| `.claude/commands/audit.md` | /audit 自定义命令，5 步审计流程 |
| `.claude/commands/doc-sync.md` | /doc-sync 命令，从 `steering-readme-maintainer` skill 迁移 |
| `.claude/commands/db-docs.md` | /db-docs 命令，从 `bd-manual-db-docs` skill 迁移 |
| `scripts/audit/prescan.py` | 合并 Kiro audit_flagger.py + change_compliance_prescan.py |

### 修改

| 文件 | 说明 |
|------|------|
| `.gitignore` | 增加 `.claude/settings.local.json`，简化 `.kiro/state/` 规则 |

### 删除

| 目录/文件 | 原因 |
|-----------|------|
| `.kiro/agents/` | Kiro agent 定义 → Claude Code Agent 工具内联 prompt 替代 |
| `.kiro/hooks/` | Kiro hook JSON → `.claude/hooks/` Python 脚本 |
| `.kiro/scripts/` | Kiro 审计脚本 → `scripts/audit/prescan.py` 合并 |
| `.kiro/settings/` | Kiro MCP 配置 → `.mcp.json` |
| `.kiro/skills/` | Kiro 技能 → `.claude/commands/` |
| `.kiro/state/` | Kiro 运行时状态文件，Claude Code 不需要 |

## 改动注解

### 高风险文件

- **`db/CLAUDE.md`**（risk: dir:db）— 新建的数据库子目录指导文件，内容为从 Kiro steering 提取的双 Schema RLS 规则和迁移 SQL 模板。纯文档，不影响数据库结构或数据。无 DDL 变更。

### 根目录文件

- **`CLAUDE.md`** — 项目核心指导文件。合并 6 份 Kiro steering 文档，新增审计流程、子代理原则、脚本规范等章节。所有后续 Claude Code 会话都会自动加载此文件。
- **`.mcp.json`** — 去掉 git MCP（Claude Code 原生支持）、去掉 autoApprove、测试库默认启用、生产库默认禁用。
- **`.gitignore`** — 增加 Claude Code 本地配置文件排除规则。

### 审计系统

- **`scripts/audit/prescan.py`** — 合并两个 Kiro 脚本为一个，去掉 `.kiro/state/` 依赖，输出 JSON 到 stdout，支持 `--files` 参数过滤。
- **`.claude/hooks/`** — 三个 hook 脚本分别覆盖 Kiro 的 session-summary、pre-change-guard、run-audit-writer hook 的核心功能。

### 删除的 `.kiro/` 子目录

6 个目录（agents、hooks、scripts、settings、skills、state）包含约 25 个文件，全部已有 Claude Code 对应物。保留 `specs/` 和 `steering/` 做历史对照。

## 数据库变更

无。本次变更不涉及任何 DDL、迁移脚本、表结构或数据修改。

## 风险与回滚

| 风险点 | 等级 | 说明 |
|--------|------|------|
| CLAUDE.md 内容遗漏 | 低 | 原始 steering 文档保留在 `.kiro/steering/`，可随时对照补充 |
| hooks 行为差异 | 低 | Kiro hooks 已不可用，Claude Code hooks 为全新实现，无兼容性问题 |
| MCP 配置变更 | 低 | 仅去掉冗余 server，测试库配置不变 |
| db/CLAUDE.md 误导 | 低 | 纯文档指导，不执行任何 SQL |

**回滚要点**：
1. 删除新增的 12 个文件
2. `git checkout` 恢复 `.gitignore`
3. `git checkout` 恢复 `.kiro/` 下被删除的目录
4. 无数据库回滚需要

## 验证

1. 确认 CLAUDE.md 被 Claude Code 自动加载：
   ```bash
   # 新开 Claude Code 会话，检查是否识别项目结构
   claude "这个项目有哪些子系统？"
   ```

2. 确认 prescan.py 正常运行：
   ```bash
   cd c:/Project/NeoZQYY && python scripts/audit/prescan.py
   ```

3. 确认 `.kiro/` 已迁移目录不再存在：
   ```bash
   ls -d c:/Project/NeoZQYY/.kiro/agents c:/Project/NeoZQYY/.kiro/hooks c:/Project/NeoZQYY/.kiro/scripts c:/Project/NeoZQYY/.kiro/settings c:/Project/NeoZQYY/.kiro/skills c:/Project/NeoZQYY/.kiro/state 2>&1
   ```

## 合规检查

| 检查项 | 状态 |
|--------|------|
| CLAUDE.md 与原 steering 内容一致 | ✓ 已逐份对照合并 |
| 飞球数据规范完整迁移 | ✓ DWD 12 条 + DWS 26 条均在 ETL CLAUDE.md |
| 审计流程可用 | ✓ prescan.py + /audit 命令 + gen_audit_dashboard.py |
| MCP 测试库可用 | ✓ pg-etl-test + pg-app-test 保留 |
| 无数据库变更需同步 | ✓ 本次无 DDL |
| `.kiro/` 保留目录合理 | ✓ specs（历史需求）+ steering（对照参考） |