dhis2-apps

DHIS2 アプリケーション開発

カスタム DHIS2 Web アプリケーションの開発を支援します。DHIS2 は、独自のアプリケーションフレームワーク、コンポーネントライブラリ、Web API を備えた保健情報管理プラットフォームです。AI アシスタントは、非推奨の API エンドポイントや誤ったパターンを使ったり、DHIS2 専用ツールの代わりに汎用ライブラリを使ったりするなど、DHIS2 の扱いを誤ることがよくあります。このスキルは、そうした問題を防ぐためにあります。

まず、現在の状況を確認します

何かを始める前に、既存の DHIS2 プロジェクトで作業しているのか、新規に始めるのかを確認してください。

確認項目	方法	結果
プロジェクトのルートに d2.config.js がある	d2.config.js を検索	既存プロジェクト — スキャフォールディングをスキップします
package.json に @dhis2/app-runtime がある	package.json を読み取る	既存プロジェクト — スキャフォールディングをスキップします
どちらも見つからない	—	新規プロジェクト — references/bootstrapping.md を読みます

既存プロジェクトの場合は、変更を加える前に d2.config.js と package.json を読み、すでに設定されている内容を確認してください。

ユーザーは何を必要としていますか？

ユーザーのタスクに合ったリファレンスを読んでください。実際のタスクの多くはデータと UI の両方を扱うため、該当するものをすべて読みます。両方が必要な場合は、UI の構築前に API の構造を把握できるよう、まず data-fetching.md を読んでください。

シナリオ	リファレンス（記載順に読む）
新しい DHIS2 アプリを作成またはスキャフォールディングする	references/bootstrapping.md
DHIS2 アプリを実行、起動、またはデプロイする	references/running-your-app.md
UI を構築せずにデータを取得または変更する（フック、スクリプト、一括処理）	references/data-fetching.md
データを表示するページを構築する（リスト、テーブル、詳細ビュー）	references/data-fetching.md → references/ui-patterns.md
リソースを作成または編集するフォームを構築する	references/data-fetching.md → references/ui-patterns.md
ナビゲーション、ページレイアウト、またはサイドバーを追加する	references/routing.md → references/ui-patterns/sidebar.md
ウィジェットを使ったダッシュボードまたは詳細ページを構築する	references/data-fetching.md → references/ui-patterns/widget.md → references/ui-patterns/dashboards.md
ユーザーインターフェースを作成する	references/ui-patterns.md
DHIS2 のバージョン間で異なる API に対応する	references/data-fetching.md（§ 機能フラグ）
DHIS2 の型を使って API レスポンスに型を付ける	references/types.md
フックまたはコンポーネントのテストを書く	references/testing.md

このコードベースでの作業方法

コードを書く前に、プロジェクトのルートに CLAUDE.md（または同等のエージェント用ファイル）がある場合は、必ず読んでください。アプリ固有の決定事項、規約、構成が記載されており、一般的なパターンより優先されます。

作業中は、次の点に従ってください。

• 新機能とヘルパー関数にはテストを書いてください。 パターンについては references/testing.md を読んでください。テストはソースファイルと同じ場所に置きます（例：useApps.ts の隣に useApps.test.ts）。
• 複雑なロジックや自明でないロジックにはコメントを付けてください。 コメントでは、隠れた制約、DHIS2 の特有の挙動、既知のバグへの回避策など、なぜそのように動作するのかを説明してください。コードを言い換えるだけのコメントは不要です。
• 読みやすいコードを優先してください。 !!value ではなく Boolean(value) を使い、複雑な条件には名前付き変数を使い、三項演算子の連鎖より明示的な return を使ってください。簡潔さより、次の開発者にとっての読みやすさを優先してください。
• CLAUDE.md を最新の状態に保ってください。 新機能、フック、アーキテクチャ上の決定を追加したら、何を構築したか、なぜ構築したかを CLAUDE.md に記載してください。CLAUDE.md がない場合は作成してください。これにより、今後のセッションやチームメイトがコードベースを理解できます。

ライブラリのバージョン：

@dhis2/ui、@dhis2/app-runtime、アプリプラットフォームのライブラリには、ソースコードが同梱されています。コンポーネントのプロパティ、フックのシグネチャ、エクスポートについて、最も正確な情報源である node_modules/@dhis2/<package>/ を直接読んでください。これらのパッケージについて、学習データや opensrc に頼らないでください。

ライブラリ	ソースの場所
@dhis2/ui	node_modules/@dhis2/ui/ — コンポーネントのプロパティ、エクスポート、デザイントークン
@dhis2/app-runtime	node_modules/@dhis2/app-runtime/ — フックのシグネチャとコンテキスト API
@dhis2/cli-app-scripts	ビルドツール — スキャフォールドコマンドではデフォルトで最新バージョンが使われます

opensrc は DHIS2 バックエンド（dhis2/dhis2-core）を調べる際の最終手段です。@dhis2/api-types の OpenAPI 仕様で必要な情報を確認できない場合、または何か誤っているように見える場合にのみ使ってください。まず仕様を確認し、それだけでは不十分な場合に限り Java のソースを参照してください。

ルール

参照した資料に関係なく、これらはすべての DHIS2 の作業に適用されます。

• React 18 のみを使用してください。 データ取得に Suspense を使わず、React 19 の API（use()、useFormStatus など）も使わないでください。isLoading と CircularLoader を使って、読み込み状態を明示的に処理してください。
• UI コンポーネントには必ず @dhis2/ui を使用してください。 MUI、Chakra、Ant Design は使用しないでください。必要なコンポーネントが UI ライブラリにない場合に限り、カスタムコンポーネントを使ってください。
• コードを書く前に必ずソースコードを読んでください。 DHIS2 フロントエンドライブラリ（@dhis2/ui、@dhis2/app-runtime）については、ソースが同梱されているため node_modules/@dhis2/<package>/ を直接読んでください。DHIS2 バックエンド API については、opensrc を使ってください（references/data-fetching.md を参照）。どちらについても、学習データは信頼できません。
• ユーザーに表示するすべての文字列に、@dhis2/d2-i18n の i18n.t() を使用してください。
• すべての DHIS2 リソース（組織単位、データ要素など）では、name ではなく displayName を使用してください。
• スタイルには CSS Modules と DHIS2 デザイントークン（var(--spacers-dp16)、var(--colors-grey900) など）を使用してください。
• 各ターンの後に検証してください。 変更を加えたら、問題を早期に検出するため pnpm exec eslint と pnpm exec tsc --noEmit を実行してください。問題があれば次に進む前に修正してください。出力がなければエラーはありません。

トラブルシューティング

DHIS2 アプリのビルド時によく発生するエラー：

症状	対処方法
実行時には問題なく動作し、IDE にもエラーが表示されない名前付きエクスポートで ESLint の import/named エラーが発生する	eslint-import-resolver-typescript をインストールし、ESLint の設定で構成します。