maintainable-typescript

保守しやすい TypeScript

局所的なコード変更だけでなく、プロジェクトに保守性の原則が必要な場合に、このスキルを使用します。

読み込み順序

デフォルトでは、スキルのディレクトリ全体を読まないでください。

1. 最初にこのファイルを読みます。
2. タスクに合致するファイルだけを読み込みます。
3. リポジトリが標準スタックに該当する場合は、stack/start-here.md を読みます。
4. doctrine/、stack/、prompts/、scripts/、assets/tooling-templates/ は参照資料として扱い、必須のコンテキストとは見なさないでください。

関連スキル

Fallow の設定、コマンド、JSON 出力、修正、CI ゲート、結果の解釈には fallow スキルを使用してください。見つからない場合：

npx skills add https://github.com/fallow-rs/fallow/tree/main/npm/fallow/skills/fallow --skill fallow

タスクルーター

• 基盤：maintainability-equals-correctness、resolve-uncertainty-into-contracts、ssot-or-die、integration-first-testing、external-boundary-mocks-only、assert-observable-outcomes
• クリーンアップ／リファクタリング：clean-up-what-you-touch、delete-obsolete-code、no-backwards-compat-shims、delete-fake-layers、edit-real-owners、build-deep-modules-not-shallow-abstractions、cleanup-module-rewrite、review-structural-slop
• パッケージ／境界：structure-typescript-apps-around-feature-owners、monorepo-package-boundaries、treat-critical-code-like-a-library、naming-is-navigation、no-re-exports、no-barrel-exports
• スタック／API／型：stack-overview、design-openapi-for-inference、errors-are-schema、document-fields-in-derived-zod-schemas、use-canonical-named-types、jsdoc-with-first-party-sources、no-magic-values、use-branded-scalar-types
• テスト／フロントエンド／ツール：contract-gate-synthetic-fixtures、test-ai-apps-by-artifacts-not-prose、no-type-casts、boundaries-validate-internals-trust、do-not-synchronize-state-with-useeffect、use-the-design-system-not-ad-hoc-tailwind、test-react-apps-in-real-browsers、maintainability-tooling
• このスキルの編集：変更するファイルを読み、その後、同梱の検証スクリプトを実行します。

監査ワークフロー

クリーンアップやレビューを行う場合：

skill_dir="<path-to-this-skill>"
bash "$skill_dir/scripts/audit-typescript-repo.sh" .

監査の出力は判断材料として扱い、絶対的な根拠とは見なさないでください。API の公開範囲を削除したり、パターンを一つにまとめたりする前に、実際の使用状況を確認してください。

対象のリポジトリが Vite+ の場合、通常のツールチェーンのエントリーポイントには vp を使用してください：vp lint、vp test、vp fmt、vp pack、vp add、vp dlx。

デフォルト

• 構造の変更にはコストがかかるため、契約、テスト、不変条件を維持してください。
• シムより削除を、偽のレイヤーより実際の所有者を、ヘルパーの乱立より安定したサブシステムファイルを優先してください。
• 不確実性は、アダプター、デフォルト値、オプショナル、スプレッド、catch で覆い隠さず、契約として解決してください。
• 派生型／スキーマ、永続性のある統合テスト、外部境界のみのモック、観測可能な結果に対するアサーションを優先してください。
• デッドコード、重複、依存関係の衛生状態、健全性、循環、依存関係の境界には Fallow を優先してください。
• コードベースの一貫性を今より高めてください。