菜单
Apply when extracting code from a large monolith file into submodules. Covers barrel re-exports, _internals DI seam proxy patterns, CI invariant allowlist updates, and cross-file test verification. Prevents CI failures, broken imports, and test regressions from code extraction.
默认使用会先检查来源的 Prompt；你也可以切换为直接命令，或下载本地副本。
决定是否安装前，请先阅读 SKILL.md，以及 SkillsMP 当前展示的配套文件。
用 Codex 或 Claude 帮你安装 复制这段 Prompt，粘贴到 Codex、Claude 或其他助手里，让它检查 Skill 页面并帮你完成安装。
直接命令不会经过审查 Prompt；运行前请先检查来源。
npx skills add https://github.com/ZaxbyHub/opencode-swarm --skill safe-extraction命令会保持在同一行。复制前请横向滚动并检查完整内容。
想先保存到本地？可下载 SkillsMP 当前能够提供的文件。
正在显示 SKILL.md
基于 SOC 职业分类
| name | safe-extraction |
| description | Apply when extracting code from a large monolith file into submodules. Covers barrel re-exports, _internals DI seam proxy patterns, CI invariant allowlist updates, and cross-file test verification. Prevents CI failures, broken imports, and test regressions from code extraction. |
| effort | medium |
| generated_from_knowledge | [] |
| source_knowledge_ids | ["b02ac9d7-9f2b-4ac0-9afe-5ee5f35f54c3","cc366a49-f097-41a5-847b-ccce077e6c80"] |
| generated_at | 2026-06-14T16:50:00.000Z |
| confidence | 0.8 |
| status | active |
| version | 4 |
| skill_origin | generated |
| provenance_note | Re-linked to current knowledge entries (version 4). The original source ID c276dc6e... is no longer present in the active knowledge store. The skill body and behavior are unchanged; only source_knowledge_ids metadata was updated to point to current lessons about refactoring guards to separate functions and upgrade-safety test helpers, both directly relevant to the safe extraction protocol. |
Follow every step in order. Do not skip steps.
Benefit: Prevents the three most common extraction failure modes:
Before moving ANY code, inventory every path-scoped artifact that references the source file:
grep -rn "<source-file-path>" scripts/ .github/workflows/
Check:
LEGACY_EXEMPTS arrays (e.g., check-invariants.sh)grep -rn "<source-file-path>" scripts/mock-allowlist.txt
grep -rln "from.*<source-module>" src/ tests/ --include="*.test.ts"
grep -rln "vi.spyOn.*<source-module>" src/ tests/ --include="*.test.ts"
grep -rln "_internals.*<source-module>" src/ tests/ --include="*.test.ts"
Record EVERY test file that imports or spies on the source module. These must all pass after extraction.
Prefer the imports tool or repo_map action for comprehensive consumer discovery. Grep catches direct string matches but misses require() imports, dynamic import(), and re-exports through intermediate modules. Use grep as a secondary cross-check.
Use the imports tool or repo_map to find all consumers of exports from the source file.
If consumers import from the original path, keep the original file as a barrel:
// src/hooks/guardrails.ts (barrel — preserves import path)
// Use EXPLICIT named exports, not `export *`, to avoid naming conflicts
// when multiple submodules export symbols with the same name.
export {
_internals,
createGuardrailsHooks,
enforceSpecDriftGate,
} from './guardrails/index';
export {
buildEffectiveRules,
checkFileAuthority,
getGlobMatcher,
} from './guardrails/file-authority';
export {
createToolBeforeHandler,
normalizeToolInput,
} from './guardrails/tool-before';
// etc.
Verify: bun run build succeeds. All existing imports still resolve.
If the source module exports _internals for test injection:
Functions that remain in the source file stay as direct entries:
export const _internals = {
resolveEvidenceTaskId, // still in this file
loadPlanJsonOnly, // still in this file
// ...
};
Functions moved to the extracted module need proxy entries so test mocks propagate:
import { _internals as _extractedInternals } from './extracted-module';
export const _internals = {
resolveEvidenceTaskId, // direct
get extractedFn() {
return _extractedInternals.extractedFn; // proxy to extracted module
},
set extractedFn(v) {
_extractedInternals.extractedFn = v; // allow test injection
},
};
The extracted module must ALSO export its own _internals:
// extracted-module.ts
export const _internals = {
extractedFn,
otherExtractedFn,
};
Type annotation: Always include an explicit type annotation on _internals objects to override as const readonly inference. Without it, as const makes properties readonly and test injection (_internals.fn = mockFn) fails at compile time:
// GOOD — explicit type annotation allows mutation
export const _internals: {
extractedFn: typeof extractedFn;
otherFn: typeof otherFn;
} = {
extractedFn,
otherFn,
};
CRITICAL: The extracted module's own production code must call mockable functions through _internals.fn(...), NOT through the direct function reference. If extractedFn internally calls otherExtractedFn, it must use _internals.otherExtractedFn() — otherwise test mocks set on _internals won't intercept the internal call. This is the same pattern the parent module follows.
Verify: Run ALL test files from Step 0c — not just the one explicitly in scope.
When splitting a factory function into handler files (NOT extracting a subsystem with its own _internals), the getter/setter proxy is unnecessary. Instead:
// guardrails/tool-before.ts — handler file
export function createToolBeforeHandler(cfg: Config, deps: Deps) {
// Receives all dependencies as parameters — no _internals needed
return function toolBefore(input: ToolInput) {
/* handler logic using cfg and deps */
};
}
// guardrails/index.ts — orchestrator
export function createGuardrailsHooks(config: PluginConfig) {
const cfg = resolveConfig(config);
return {
toolBefore: createToolBeforeHandler(cfg, deps),
// ...
};
}
Use this pattern when:
Use the _internals proxy pattern (3b) when:
_internals for test injectionFor EVERY path-scoped artifact found in Step 0a, add the new file paths:
# Example: check-invariants.sh
LEGACY_EXEMPTS=(
"src/hooks/guardrails.ts" # original (still exists as barrel)
"src/hooks/guardrails/file-authority.ts" # NEW
"src/hooks/guardrails/helpers.ts" # NEW
"src/hooks/guardrails/index.ts" # NEW
)
Verify: Run the invariant check script locally if possible (bash on Windows may require WSL).
File-path moves alter SAST finding fingerprints, making pre-existing findings appear new. After extraction:
sast_scan with capture_baseline: true and the current phase numberVerify: SAST scan on the new file paths shows only genuinely new findings, not relocated pre-existing ones.
Update any doc references that point to the old monolith for functions that moved:
grep -rn "<source-file-path>" docs/ *.md
Fix references to point to the new submodule location.
bun run build succeedsbun run typecheck succeeds (zero new type errors)biome ci . passes| Mistake | Why it fails |
|---|---|
| Forgetting to update LEGACY_EXEMPTS | CI quality job fails on process.cwd() check for new file paths |
| Only testing the explicit test file | Cross-file regressions in OTHER consuming test files go undetected |
| Not creating getter/setter proxies for _internals | Test mocks on the parent module don't propagate to extracted functions |
| Moving helper functions without updating/re-exporting all consumers | Import errors in unrelated files that depended on the helper |
| Updating docs to reference new paths but missing some | Stale doc references confuse future readers |