# Module Augmentation Guardrails

> Use when TypeScript subpath exports lose types or have declaration conflicts. Follow module augmentation conventions to avoid replacing upstream exports.

- Skill: `ai-shifu/module-augmentation-guardrails` (Agent Skill)
- Install (CLI): `npx get-skill add ai-shifu/module-augmentation-guardrails`
- Raw SKILL.md: https://api.skillmd.com/api/skills/ai-shifu/module-augmentation-guardrails/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Coding & Dev Tools
- Author: ai-shifu (https://skillmd.com/u/ai-shifu)
- Updated: 2026-11-16
- Page: https://skillmd.com/skills/ai-shifu/module-augmentation-guardrails

---


# TypeScript 模块增强防护

## 核心规则

- 改类型前先核对 `node_modules` 中发布版声明文件。
- augmentation 文件必须包含顶层 `import "package/subpath";` 与 `export {};`。
- 仅增强已导出的 interface；非 interface 结构优先用本地 wrapper 类型。
- 为子路径组件补扩展 props 时，要 augment 到真实导出子路径（如 `markdown-flow-ui/slide`），不要误写到相邻模块导致类型表面可用、运行接入点却不生效。

## 工作流

1. 先确认是上游类型问题还是本地声明覆盖导致。
2. 在 augmentation 中显式引入依赖类型（如 `InteractionDefaultValueOptions`）。
3. 避免在 `.d.ts` 里重写整个模块结构。
4. 变更后执行定向类型检查，确认导出成员未丢失。
5. 若扩展字段依赖 React 类型（如 `ReactNode`），在声明文件顶层显式 `import type`，避免 TS 在模块增强中退化成 `any`。

