arch-upkeep

arch-upkeep

arch-upkeep は、既存のプロジェクトを標準スタータースタックに沿った状態に保つためのメタアーキテクチャスキルです。

• arch-tsdown-monorepo — パッケージごとに tsdown を使用する、TS ライブラリ向け pnpm モノレポ
• arch-tsdown — tsdown を使用する、単一パッケージの TS ライブラリ
• arch-tsdown-cli — tsdown で構築する CLI アプリ
• arch-unplugin — unplugin として構築するライブラリ（Vite/Rollup/Webpack/ESBuild）
• arch-webext-vue — Vue を使用するブラウザー拡張機能
• arch-vscode — VS Code 拡張機能

プロジェクトがすでに存在し、次のことを行いたい場合にこのスキルを使用します。

• 現在どのアーキテクチャに該当するかを特定する（lib / CLI / monorepo / webext / vscode / unplugin / mixed）
• 標準の arch-* スターターへの移行を計画する
• アプリのロジックを書き換えることなく、ツール、スクリプト、CI を段階的にアップグレードする

このスキルでは、各アーキテクチャの詳細を再定義するのではなく、適用する arch-skill とその順序を選ぶのに役立ちます。

クイックスタート

1. 1. Detect current architecture のチェック項目を使って、リポジトリを分類します。
2. 2. Choose the target architecture skill(s) を使って、対象となるスキルを選びます。
3. 2.1 Check & install required skills に従って、必要な arch-* スキルがインストールされていることを確認します。
4. 3. Migration strategy (incremental) と 4. Architecture-specific notes を使って、段階的な移行を計画します。
5. 5. Checklist: running an “arch upkeep” on a repo のチェックリストを使って、メンテナンス作業を行います。

1. 現在のアーキテクチャを検出する

まず、リポジトリを分類します。次の簡単なヒューリスティックを使ってください（複数を適用できます。プロジェクトは「モノレポ + CLI」などの場合もあります）。

• モノレポ（arch-tsdown-monorepo の候補）

  • pnpm-workspace.yaml、packages/*、apps/*、または類似の構成がある
  • packages/ または apps/ の下に複数の package.json ファイルがある
  • ルートに共有ツール設定がある（eslint.config.*、vitest.config.*、tsconfig.base.json など）

• 単一の TS ライブラリ（arch-tsdown の候補）

  • ルートに package.json が1つだけある
  • ライブラリ形式のエクスポート（main、module、types、場合によっては exports）がある
  • bin エントリーポイント、ブラウザーマニフェスト、VS Code 拡張機能マニフェストがない

• CLI（arch-tsdown-cli の候補）

  • ルートの package.json に "bin" がある、または "package.json#exports" が CLI エントリーを指している
  • エントリーファイルで #!/usr/bin/env node を使用している
  • cac、commander、yargs などに依存していることが多い

• unplugin ベースのライブラリ（arch-unplugin の候補）

  • unplugin に依存している
  • createUnplugin をエクスポートしている、または src/core/、src/vite.ts、src/webpack.ts などのファイルがある
  • バンドラー（Vite/Rollup/Webpack/ESBuild）を対象としている

• ブラウザー拡張機能 + Vue（arch-webext-vue の候補）

  • manifest.json / manifest.v3.json（Chrome/Firefox 拡張機能）がある
  • ポップアップやオプション画面、またはコンテンツスクリプト用の Vue SPA がある
  • ブラウザー拡張機能の開発向けツール（web-ext、wxt、またはカスタムスクリプト）を使用している

• VS Code 拡張機能（arch-vscode の候補）

  • "contributes"、"activationEvents"、"engines.vscode" を含む package.json がある
  • src/extension.ts または類似のアクティベーションエントリーがある

プロジェクトの主な構成がわかったら、アップグレード先となる主要アーキテクチャを1つ選びます。モノレポに CLI パッケージが含まれるなど、複数の構成が混在している場合は、arch-tsdown-monorepo と、該当するパッケージごとのスキル（arch-tsdown、arch-tsdown-cli など）を組み合わせます。

2. 対象となるアーキテクチャスキルを選択する

分類結果を、次の正式なスキルに対応付けます。

• pnpm マルチパッケージリポジトリ → arch-tsdown-monorepo から始めます
• 単一の TS ライブラリ → arch-tsdown
• CLI（単独、またはモノレポ内のパッケージ）→ arch-tsdown-cli
• unplugin ライブラリ → arch-unplugin（多くの場合、arch-tsdown またはモノレポの構成内で使用します）
• ブラウザー拡張機能 + Vue → arch-webext-vue（アプリ層）と、共有ライブラリがある場合は arch-tsdown
• VS Code 拡張機能 → arch-vscode（拡張機能アプリ）と、共有ライブラリには arch-tsdown

続いて、次の手順を行います。

1. 対応する arch-* スキルを開きます。
2. 「overview」／「core」のリファレンスを、既存のリポジトリが目指すべき設計として使用します。
3. 段階的な移行を計画します。まず設定とスクリプト、次に CI、最後にリリースの自動化を行います。

2.1 必要なスキルを確認してインストールする

arch-upkeep はオーケストレーターにすぎないため、エージェント環境に具体的な arch-* スキルがインストールされ、使用可能な状態であることを前提としています。

推奨される手順は次のとおりです。

1. エージェントのランタイムにインストールされているスキルを一覧表示します

   • プラットフォームの「スキルを一覧表示」コマンド／UI を使用します（例：arch-tsdown-monorepo、arch-tsdown、arch-tsdown-cli、arch-unplugin、arch-webext-vue、arch-vscode を探します）。
   • 対象のアーキテクチャスキルがすでに存在する場合は、そのまま呼び出せます。

2. 必要なスキルがない場合は、名前を指定してインストールします

   • Agent Skills カタログ（またはプラットフォームのマーケットプレイス）で、arch-tsdown-monorepo などの正確な名前を検索します。
   • 現在のエージェントプロファイル／ワークスペースにインストールします。

3. 作業を進める前に、インストールを確認します

   • もう一度「スキルを一覧表示」画面を開き、スキルが表示され、有効になっていることを確認します。
   • 必要に応じて、その SKILL.md（または UI のスキル詳細）を開き、バージョンと対象範囲を確認します。

4. 1 回の保守セッションで複数のスキルを組み合わせます

   • モノレポ + CLI：arch-tsdown-monorepo と arch-tsdown-cli を CLI パッケージに使用し、共有ライブラリには arch-tsdown を使用します。
   • 共有ライブラリを含む VS Code 拡張機能：拡張機能ホストには arch-vscode を使用し、共有モジュールには arch-tsdown を使用します。
   • 共有 TS ライブラリを含む Web 拡張機能：拡張機能アプリには arch-webext-vue を使用し、再利用可能なパッケージには arch-tsdown を使用します。

関連するスキルをインストールして確認してから、以下の移行手順を適用してください。

3. 移行戦略（段階的）

一般原則：

• アプリのロジックを書き換えないでください。 置き換えるのはインフラストラクチャ（ビルド、テスト、リント、CI、リリース）のみです。
• 一度に1つのレイヤーを移行してください。 可能であれば、バンドラー、テストランナー、tsconfig をすべて1つの PR で変更するのは避けてください。
• Git の履歴を読みやすく保ってください。 「ツールの移行」と「コードの修正」は別々のコミットにしてください。

推奨する順序：

1. パッケージのレイアウトを標準化する

   • モノレポの場合：arch-tsdown-monorepo に従って、packages/* のレイアウト、ルートの package.json、ワークスペースのバージョン範囲、pnpm カタログを揃えます。
   • 単一パッケージの場合：フォルダー構成（src/、dist/、tests/）、tsconfig の名前などを arch-tsdown に合わせます。

2. ビルドを tsdown に移行する（該当する場合）

   • 既存のビルドスクリプト（tsc、rollup、tsup など）を、移行先のスキルにある tsdown の設定に置き換えます。
   • package.json#exports、main/module/types、files の各フィールドが移行先のパターンと一致していることを確認します。

3. テストとリントを揃える

   • 関連する arch スキルで推奨されているテストランナー（Vitest）と ESLint の設定に移行します。
   • モノレポの場合は、必要に応じてパッケージごとのオーバーライドを設定し、設定をルートに集約します。

4. スクリプトを統一する

   • 移行先のアーキテクチャで使われているスクリプト名（build、dev、test、lint、typecheck、release など）に統一します。
   • モノレポでは、pnpm -r または pnpm --filter を使うルートスクリプトを優先します。

5. CI とリリースをアップグレードする

   • 関連する arch スキルの GitHub Actions／リリースワークフローを採用します。
   • 該当する場合は、npm Trusted Publisher、タグベースのリリース、bumpp または類似のツールに移行します。

6. クリーンアップする

   • 新しいパイプラインが正常に動作したら、不要になった設定、スクリプト、未使用の devDependencies を削除します。

4. アーキテクチャ別の注意事項

• arch-tsdown-monorepo を対象にする場合：

  • ツール（ESLint、Vitest、TS のベース設定）をルートに集約します。
  • パッケージ間の依存関係を workspace:* のバージョン範囲に変更します。
  • 各パッケージを tsdown で個別にビルドできるようにします。

• arch-tsdown または arch-tsdown-cli を対象にする場合：

  • パッケージを標準的な TS ライブラリ／CLI として扱い、可能な限り src/ を整理して副作用のない状態に保ちます。
  • バイナリーのエントリーポイントは、内部モジュールをインポートする小さなブートストラップファイルにします。

• arch-unplugin を対象にする場合：

  • unplugin のコアを小さく、組み合わせやすい状態に保ちます。
  • 統一された unplugin API を通じて、各バンドラー（Vite、Rollup、Webpack、ESBuild）向けの明確なエクスポートを提供します。

• arch-webext-vue を対象にする場合：

  • アプリの UI（Vue）をバックグラウンド／サービスワーカーのロジックおよび共有ユーティリティから分離します。
  • 拡張機能の外でも再利用できるロジックには、共有 TS ライブラリ（arch-tsdown を使用）を優先します。

• arch-vscode を対象にする場合：

  • 拡張機能ホストのコード（アクティベーション、コマンド）を薄く保ちます。
  • 可能であれば、複雑なロジックを共有 TS ライブラリに移します。

5. チェックリスト：リポジトリで「arch の保守作業」を行う

繰り返し使えるワークフローとして、以下を使用します。

1. アーキテクチャを分類する（モノレポ／ライブラリ／CLI／unplugin／webext／vscode）。
2. 目指す最終状態に合う主要な arch-* スキルを選ぶ。
3. 各スキルの概要とコアリファレンスを読み、目標とする構成とスクリプトを書き出す。
4. 段階的な手順を計画する（レイアウト → ビルド → テスト／リント → CI → リリース）。
5. アプリのロジックを維持しながら変更を適用する。
6. 新しいパイプラインが通ったら、古いツールを削除する。

これにより、プロジェクトは選択したスターターから最初にスキャフォールドされたかのような構成と動作になり、今後の保守やオンボーディングが大幅に容易になります。