메뉴
用于大规模重构。冻结 old db 作为基线观察，使用 new db 持续建设新结构，并通过 migration_plan.md 管理旧模块到新模块的迁移设计、进度和退出条件。
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
| name | refactor-migration |
| description | 用于大规模重构。冻结 old db 作为基线观察，使用 new db 持续建设新结构，并通过 migration_plan.md 管理旧模块到新模块的迁移设计、进度和退出条件。 |
这个技能用于处理“需要一边对照旧系统，一边建设新系统”的重构任务。
业务目标只有三个：
old db，作为重构前基线new dbmigration_plan.md 跟踪承接关系、状态和退出条件old db: 只读基线，不再写入new db: 当前工作库，持续记录新结构migration_plan.md: 迁移映射与进度的唯一业务视图不要把 old db 当作当前事实，也不要把 new db 当作历史档案。
先明确旧模块如何承接到新模块，再开始大规模改动。 如果承接关系还不清晰，不要急着更新大批量结构文档。
描述重构时，优先说明：
不要只描述代码移动或目录调整。
开始前先备份当前数据库到 .agent_cache/.backup，形成只读基线：
STAMP=$(date +%Y%m%d-%H%M%S)
BASE=".agent_cache/.backup/refactors/$STAMP"
mkdir -p "$BASE"
cp docs/workspace_docs.db "$BASE/workspace_docs.old.db"
cp docs/modular_arch.db "$BASE/modular_arch.old.db"
此后：
docs/workspace_docs.db 继续作为 new dbdocs/modular_arch.db 继续作为 new db.agent_cache/.backup/.../*.old.db 只用于观察旧系统，不允许继续写入在与本次重构最接近的叶子目录下创建 migration_plan.md。
最小表结构如下：
| Old Module | New Module | Business Capability | Status | Exit Criteria | Notes |
|------------|------------|---------------------|--------|---------------|-------|
| order | order_v2 | 订单创建与查询 | doing | 所有读写流量切换完成 | 查询已迁移，写入未迁移 |
| billing | billing_v2 | 账单结算 | todo | 对账链路通过回归验证 | 依赖新账户接口 |
| user | user_v2 | 用户资料管理 | done | 旧接口下线 | 已切流 |
规则：
Status 只用 todo / doing / done / blockedBusiness Capability 必须是业务能力，不是技术动作Exit Criteria 必须可验证对新结构的所有正式记录，都写入当前工作库：
workspace-docsmodular-arch示例：
python3 .agents/skills/workspace-docs/scripts/agent_docs.py set "src/order_v2" \
-d "新订单域模块，承接订单创建与查询能力" \
-n "对应 migration_plan.md 中的 order -> order_v2"
python3 .agents/skills/modular-arch/scripts/mod_arch.py register order_v2 \
-p src/order_v2 -l backend -d "新订单域模块"
python3 .agents/skills/modular-arch/scripts/mod_arch.py interface order_v2 order_service \
-s "createOrder(input) -> Order; getOrder(id) -> Order" \
-d "订单核心业务接口"
当你需要回答“旧系统原来是什么样”时，查看备份的 old db。
注意：
workspace-docs 和 modular-arch 现有脚本默认读写 docs/*.dbold db 的定位是“观察基线”，不是当前工具链的工作库新结构收口时，至少执行：
python3 .agents/skills/modular-arch/scripts/mod_arch.py check
python3 .agents/skills/workspace-docs/scripts/agent_docs.py scan
然后检查：
migration_plan.md 是否所有关键能力都具备明确状态done 项是否满足 Exit Criteriaold dbnew dbmigration_plan.md如果一个信息同时需要“结构事实”和“迁移状态”，优先以 migration_plan.md 为准，再回查 DB。
workspace-docs: 负责新文件和目录职责说明modular-arch: 负责新模块、依赖方向和接口契约这个技能不替代它们，而是规定在大规模重构场景下，三者如何协同：
workspace-docs 记录新结构职责modular-arch 记录新结构关系refactor-migration 记录旧到新的迁移方法和进度当你需要按用户 prompt 片段从本机 Codex CLI JSONL 会话里定位最近一次相关会话，并导出为可读的 user/assistant Markdown 对话稿时使用。
使用 draw.io CLI 绘制项目架构依赖图，支持中英文标签，导出 SVG/PNG/PDF 预览，并将图片插入 Markdown 文档。
管理和读取工作区目录文档。使用该技能可了解文件/目录用途、读取 agent 专用备注，或在创建/修改文件后更新文档。
自动工作工具箱入口。用于按需加载架构设计、重构迁移、质量门禁和会话留痕能力；默认只读取本入口，再根据任务打开对应 references 或下游 skill。
管理模块间语义层级依赖关系。注册模块、声明依赖方向、定义接口契约，支持环检测、跨层违规检查和并行开发分组。
记录 Agent 会话日志。捕获用户原始 prompt、LLM 理解摘要和执行上下文摘要，用于追溯和复盘。