diff --git a/.apm/instructions/nextjs-routing.instructions.md b/.apm/instructions/nextjs-routing.instructions.md new file mode 100644 index 0000000..df23bc6 --- /dev/null +++ b/.apm/instructions/nextjs-routing.instructions.md @@ -0,0 +1,15 @@ +--- +description: Next.js の routing / rendering 方針 +applyTo: "{app,src/app,pages,src/pages}/**/*.{ts,tsx,js,jsx}" +--- + +# Next.js Routing 方針 + +- App Router を使う repo では Server Component を優先し、`use client` は本当に必要な境界だけに限定してください。 +- client component にする理由は、フォーム操作、browser API、interactive UI など明確な要件がある場合に限ってください。 +- 取得可能なデータは server 側で解決し、client 側で同じ取得を重複させないでください。 +- `app/` や `src/app/` 配下では、route segment、`layout`、`page`、`loading`、`error`、`not-found` の役割を崩さないでください。 +- `pages/` や `src/pages/` 配下では、既存の data fetching 方式と routing convention を維持してください。 +- ルート追加時は URL 設計、認可要件、breadcrumb や navigation への影響も確認してください。 +- 画面単位で loading / error を置ける場合は、ユーザー体験として自然な粒度で配置してください。 +- API route や server action を追加する場合は、入力検証、認可、失敗時レスポンス、監査しやすさを意識してください。 diff --git a/.apm/instructions/team-workflow.instructions.md b/.apm/instructions/team-workflow.instructions.md new file mode 100644 index 0000000..a695025 --- /dev/null +++ b/.apm/instructions/team-workflow.instructions.md @@ -0,0 +1,19 @@ +--- +description: NUTFes の Web 系リポジトリで共通に守る開発フロー +applyTo: "**/*" +--- + +# NUTFes Web 開発フロー + +- まず repo の既存構成、README、`Makefile`、`mise.toml`、`docker-compose.yml` / `compose.yml`、package manager、lint、test、build スクリプトを確認し、その repo の流儀を優先してください。 +- 新しいツールや依存関係を追加する前に、既存のスクリプトや仕組みで解決できないかを確認してください。 +- NUTFes の各プロダクトは Docker ベースの開発環境を前提にしてください。ホストで直接コマンドを叩くより、repo が用意した Docker 経由の実行方法を優先してください。 +- コマンド実行は、まず `make `、次に `mise run `、その次に `docker compose exec` / `docker compose run`、最後に repo 既存 script を検討してください。 +- `npm test`、`pnpm lint`、`python manage.py`、`go test` などをホストで直接叩く前に、同等の `make` / `mise` / Docker ラッパーが無いか必ず確認してください。 +- package manager は repo が採用しているものを維持してください。不要な `npm` / `pnpm` / `yarn` の切り替えは禁止です。 +- 変更は最小限にとどめ、無関係なリファクタや命名変更を混ぜないでください。 +- 実装後は、影響範囲に応じて lint、typecheck、test、build など既存の検証コマンドを必ず実行してください。検証も Docker / `make` / `mise` の公式経路を使ってください。 +- 実行できなかった検証や、環境依存で未確認の点は明確に報告してください。 +- `.env`、シークレット、トークン、認証情報、個人情報を新規に出力・埋め込み・共有しないでください。 +- migration、seed、外部 API 更新、認証周りの変更は、破壊的変更の有無を必ず明示してください。 +- レビューや実装計画では、結論より先に前提、制約、リスク、未確認事項を整理してください。 diff --git a/.apm/instructions/typescript-react.instructions.md b/.apm/instructions/typescript-react.instructions.md new file mode 100644 index 0000000..4b11619 --- /dev/null +++ b/.apm/instructions/typescript-react.instructions.md @@ -0,0 +1,16 @@ +--- +description: TypeScript / React 実装時の共通方針 +applyTo: "**/*.{ts,tsx,js,jsx,mts,cts,mjs,cjs}" +--- + +# TypeScript / React 方針 + +- `any` は原則禁止です。やむを得ない場合は範囲を最小化し、代替型を検討した理由を残してください。 +- 型は利用箇所の近くで読みやすく保ち、既存 repo に schema や domain type があるなら再利用してください。 +- nullable / optional の扱いは曖昧にせず、UI とデータ境界で明示的に処理してください。 +- React の state は最小限に保ち、derived state を増やしすぎないでください。 +- 既存 repo が `react-hook-form`、server actions、query library、custom hooks などのパターンを持つ場合は、それに合わせてください。 +- props は責務ごとに整理し、巨大な component にロジックを詰め込みすぎないでください。 +- UI 実装では empty、loading、error、disabled の各状態を最初から考慮してください。 +- 非同期処理は例外経路を含めて扱い、ユーザー操作失敗時の表示や再試行導線を意識してください。 +- 不要な `useEffect`、過剰な client state、場当たり的な `console.log` を増やさないでください。 diff --git a/.apm/instructions/ui-accessibility.instructions.md b/.apm/instructions/ui-accessibility.instructions.md new file mode 100644 index 0000000..6731519 --- /dev/null +++ b/.apm/instructions/ui-accessibility.instructions.md @@ -0,0 +1,15 @@ +--- +description: Web UI のアクセシビリティと操作性の基準 +applyTo: "{app,src/app,pages,src/pages,components,src/components}/**/*.{ts,tsx,js,jsx}" +--- + +# UI / Accessibility 基準 + +- クリック可能要素は適切な semantic element を使い、見た目だけの `div` 操作を避けてください。 +- キーボードだけで操作できることを前提に、focus 移動、focus 可視化、dialog の閉じ方を確認してください。 +- フォームには label、説明文、エラーメッセージを結び付け、必須項目や失敗理由を見落とさせないでください。 +- hover 依存の UI にしすぎず、touch device と keyboard 操作でも成立させてください。 +- レスポンシブ時の崩れだけでなく、文量増加、long text、empty state でも破綻しない構成にしてください。 +- 色だけで状態を伝えず、テキストやアイコン、aria 属性など複数の手段で補ってください。 +- skeleton、spinner、disabled 表示は「待っている理由」が分かるように設計してください。 +- destructive action や irreversible action では確認導線と安全策を用意してください。 diff --git a/.apm/prompts/plan-feature.prompt.md b/.apm/prompts/plan-feature.prompt.md new file mode 100644 index 0000000..a72ca9f --- /dev/null +++ b/.apm/prompts/plan-feature.prompt.md @@ -0,0 +1,30 @@ +--- +description: repo 文脈を踏まえて Web 機能実装の計画を作る +author: NUTFes +input: + - feature + - constraints +--- + +# Plan Feature + +`${input:feature}` を実装するための計画を作成してください。追加制約は `${input:constraints}` です。 + +## 進め方 + +1. 先に repo 構成、既存パターン、利用中のライブラリ、関連画面や API、`Makefile` / `mise.toml` / Docker 設定を確認する +2. 実装や検証に使う正式なコマンド入口が `make`、`mise run`、`docker compose` のどれかを確認する +3. 現状に対して何を変えるべきかを、挙動単位で整理する +4. 実装担当者が迷わない粒度で、変更点、データフロー、例外系、検証方法を決める +5. 破壊的変更、migration、環境変数、認可影響があれば明示する + +## 出力要件 + +- 目的と成功条件 +- 主要な変更点 +- 影響を受ける UI / API / state / validation +- 実装と検証で使うべきコマンド経路 +- テスト方針 +- 未解決事項または要追加確認事項 + +実装者に判断を丸投げしない、decision-complete に近い計画にしてください。 diff --git a/.apm/prompts/release-check.prompt.md b/.apm/prompts/release-check.prompt.md new file mode 100644 index 0000000..86206ff --- /dev/null +++ b/.apm/prompts/release-check.prompt.md @@ -0,0 +1,27 @@ +--- +description: PR 前に lint / typecheck / test / build / env / migration を確認する +author: NUTFes +input: + - change_summary +--- + +# Release Check + +`${input:change_summary}` を踏まえて、PR 前の最終確認を行ってください。 + +## チェック項目 + +1. repo が採用している Docker / `make` / `mise` / script ベースの lint / format / typecheck / test / build コマンドが何か +2. ホスト直実行ではなく、どのラッパー経路を正式コマンドとして使うべきか +3. 今回の変更で最低限実行すべきコマンドは何か +4. 実行結果に失敗や未実施があるか +5. migration、seed、schema 変更、環境変数追加、権限変更があるか +6. release note や reviewer への申し送りが必要か + +## 出力形式 + +- 実行すべき確認項目のチェックリスト +- その repo で使うべきコマンド入口 (`make` / `mise` / Docker / script) +- 既に満たした項目 +- 未確認またはリスクが残る項目 +- PR 説明に含めるべき注意点 diff --git a/.apm/prompts/review-web.prompt.md b/.apm/prompts/review-web.prompt.md new file mode 100644 index 0000000..c3b6bea --- /dev/null +++ b/.apm/prompts/review-web.prompt.md @@ -0,0 +1,32 @@ +--- +description: NUTFes の Web 系リポジトリ向け findings-first レビュー +author: NUTFes +input: + - scope + - focus +--- + +# Web Review + +NUTFes の Web 系リポジトリをレビューしてください。対象範囲は `${input:scope}`、重点観点は `${input:focus}` です。 + +## レビュー方針 + +1. まず不具合、仕様逸脱、UX 破綻、セキュリティ、a11y、保守性の問題を列挙する +2. 指摘は重大度順に並べ、再現条件や影響範囲を明確にする +3. 問題がなければ「重大な findings はなし」と明言する +4. その後に residual risk、未確認事項、追加で見るべきテストを短くまとめる + +## 注目観点 + +- Next.js / React の実装が既存パターンと整合しているか +- TypeScript の型安全が保たれているか +- loading / error / empty state が考慮されているか +- フォーム、認可、API 呼び出しが安全に扱われているか +- responsive と keyboard accessibility が崩れていないか + +## 出力形式 + +- Findings を先に出す +- 各 finding には、場所、問題、影響、必要な修正方針を含める +- 最後に未確認事項と追加テスト候補を必要最小限でまとめる diff --git a/.apm/skills/web-feature/SKILL.md b/.apm/skills/web-feature/SKILL.md new file mode 100644 index 0000000..6ccccc6 --- /dev/null +++ b/.apm/skills/web-feature/SKILL.md @@ -0,0 +1,40 @@ +--- +name: NUTFes Web Feature +description: NUTFes の Web 系リポジトリで機能追加を進めるための実装フロー +--- + +# NUTFes Web Feature + +## 目的 + +NUTFes の Next.js / React / TypeScript ベースのリポジトリで、新機能や改修を進めるときの標準フローを共有します。 + +## いつ使うか + +- 新しい画面やフォームを追加するとき +- 既存 UI の改善や画面遷移の変更を行うとき +- API 接続や state 管理を伴う Web 実装を進めるとき + +## 手順 + +1. 先に repo の README、ディレクトリ構成、`Makefile`、`mise.toml`、Docker 関連設定、package manager、scripts、既存パターンを確認する +2. コマンドの入口は `make`、`mise run`、`docker compose exec` / `run` の順で探し、ホスト直実行より repo のラッパーを優先する +3. 変更対象に近い画面、component、hook、API client を探し、既存の流儀を把握する +4. 追加する state、validation、data flow、loading / error / empty state を先に整理する +5. `use client` が本当に必要かを確認し、server-first で実装できないかを検討する +6. UI は semantic HTML、keyboard 操作、responsive を前提に構成する +7. 実装後は repo 既存の lint / typecheck / test / build を Docker / `make` / `mise` の公式経路で実行し、未実施があれば明記する + +## 判断基準 + +- 型を曖昧にしない +- repo の既存パターンを壊さない +- コマンド実行経路も repo の既存ラッパーを壊さない +- 変更を最小限にする +- 例外系の UX を後回しにしない + +## あわせて使うもの + +- `review-web.prompt.md` +- `plan-feature.prompt.md` +- `release-check.prompt.md` diff --git a/.apm/skills/web-review/SKILL.md b/.apm/skills/web-review/SKILL.md new file mode 100644 index 0000000..489d6f7 --- /dev/null +++ b/.apm/skills/web-review/SKILL.md @@ -0,0 +1,39 @@ +--- +name: NUTFes Web Review +description: Next.js / React の変更を findings-first でレビューするための手順 +--- + +# NUTFes Web Review + +## 目的 + +NUTFes の Web 系変更をレビューするときに、問題発見を優先した一貫した観点を持たせます。 + +## いつ使うか + +- PR レビュー +- 実装後の自己レビュー +- リリース前の差分確認 + +## レビュー手順 + +1. まず変更範囲の entrypoint、routing、form、API 呼び出し、state 管理を把握する +2. 次に不具合、仕様逸脱、セキュリティ、a11y、性能、保守性の順で問題を探す +3. findings は重大度順にまとめ、場所と影響を明確にする +4. 問題がなければその旨を明示し、残る未確認事項だけを短く整理する + +## 観点 + +- `any` や unsafe cast で型安全が崩れていないか +- loading / error / empty / disabled state が抜けていないか +- `use client` の範囲が広すぎないか +- routing、認可、入力検証、失敗時表示が自然か +- keyboard accessibility と focus 管理が崩れていないか +- repo の既存 UI / data pattern から逸脱していないか + +## 出力の原則 + +- findings-first +- 重大度順 +- 修正に必要な情報を簡潔に含める +- 問題がない場合も「問題なし」を明示する diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..bcdf403 --- /dev/null +++ b/.gitignore @@ -0,0 +1,2 @@ +apm_modules/ +apm.lock.yaml diff --git a/README.md b/README.md index 2a335e1..d494561 100644 --- a/README.md +++ b/README.md @@ -1 +1,172 @@ # nutfes-apm-kit + +NUTFes の Web 系リポジトリで再利用するための APM パッケージです。共通の開発方針、Web レビュー用プロンプト、Next.js/React 実装フローのスキルをまとめて配布します。 + +このパッケージは、各プロダクトが Docker ベースの開発環境を持ち、日常の作業コマンドも `make` / `mise` / `docker compose` などの repo 既存ラッパー経由で実行される前提で設計しています。 + +## 何を提供するか + +- `.apm/instructions/` + - チーム共通の開発フロー + - TypeScript / React 実装時の基本方針 + - Next.js のルーティングと Server Component 優先方針 + - Web UI のアクセシビリティ基準 +- `.apm/prompts/` + - findings-first の Web レビュー + - repo 文脈を踏まえた実装計画 + - PR 前のリリースチェック +- `.apm/skills/` + - NUTFes 系 Web リポジトリ向け実装フロー + - Next.js / React 向けレビュー手順 + +v1 では agents / hooks / MCP / transitive dependencies は含めません。 + +## 標準の使い方 + +通常は `develop` を更新チャネルとして使います。 + +```bash +apm install NUTFes/nutfes-apm-kit#develop +``` + +利用側の `apm.yml` は次のようになります。 + +```yaml +name: your-project +version: 1.0.0 +dependencies: + apm: + - NUTFes/nutfes-apm-kit#develop +``` + +依存関係を追加済みの repo では、以後は通常の install で再展開できます。 + +```bash +apm install +``` + +## 開発フローの前提 + +このパッケージが想定する各プロダクトの作業方針は次の通りです。 + +- 開発環境は Docker ベースで扱う +- コマンド実行は、まず `make`、次に `mise run`、その次に `docker compose exec` / `docker compose run` を探す +- ホストでの `npm` / `pnpm` / `yarn` / `python` / `go` 直実行は、repo がそれを正式入口にしている場合を除いて避ける +- lint / typecheck / test / build も同じく repo の公式ラッパー経由で実行する + +つまり、このパッケージは「Docker 上で動くプロダクトに対して、repo が用意したコマンドツールを使って開発を進める」ための共通ルール集です。 + +## 固定版の使い方 + +安定版を固定したい場合はタグを使います。 + +```bash +apm install NUTFes/nutfes-apm-kit#v0.1.0 +``` + +利用側の `apm.yml` 例: + +```yaml +name: your-project +version: 1.0.0 +dependencies: + apm: + - NUTFes/nutfes-apm-kit#v0.1.0 +``` + +## 更新方法 + +### `#develop` を使っている repo + +最新の `develop` を取り込みたいときは次を実行します。 + +```bash +apm install --update +``` + +`apm.lock.yaml` が更新され、最新の commit に解決し直されます。 + +### タグ固定の repo + +`apm.yml` の ref を目的のタグへ更新してから install を実行します。 + +```yaml +dependencies: + apm: + - NUTFes/nutfes-apm-kit#v0.2.0 +``` + +```bash +apm install +``` + +## Codex / OpenCode / Gemini での利用 + +Copilot / Claude / Cursor は `apm install` のネイティブ配置だけで利用できます。 + +Codex / OpenCode / Gemini では instruction を `AGENTS.md` にコンパイルするため、install 後に次を実行してください。 + +```bash +apm compile +``` + +必要に応じて Codex 向けを明示する場合: + +```bash +apm compile --target codex +``` + +`apm compile` が成功表示でも `AGENTS.md` が生成されない場合は、利用側の APM を最新版に更新して再試行してください。 + +## このパッケージを更新する運用 + +標準運用は `develop` ブランチです。利用例でも常に `#develop` を明示し、既定ブランチに依存しないようにします。 + +リリースを切るときは次の順で運用します。 + +1. `apm.yml` の `version` を更新する +2. README のタグ例を必要なら更新する +3. `develop` を安定化させる +4. `vX.Y.Z` タグを切る + +タグは「固定配布用」、`develop` は「継続更新用」です。 + +## authoring / 検証 + +この repo 自体を APM パッケージとして検証するときの基本コマンド: + +```bash +apm install --dry-run +``` + +consumer 側の確認例: + +```bash +apm init +apm install /path/to/nutfes-apm-kit +apm audit +apm compile --target codex +``` + +確認対象: + +- `apm.yml` +- `apm.lock.yaml` +- `.github/` +- `.claude/` +- `.cursor/` +- `.opencode/` +- `.agents/skills/` +- `.codex/agents/` +- `AGENTS.md` + +## 構成 + +```text +. +├── apm.yml +└── .apm + ├── instructions + ├── prompts + └── skills +``` diff --git a/apm.yml b/apm.yml new file mode 100644 index 0000000..adf6861 --- /dev/null +++ b/apm.yml @@ -0,0 +1,6 @@ +name: nutfes-apm-kit +version: 0.1.0 +description: NUTFes の Web 系リポジトリ向けに共有する APM パッケージです。 +author: NUTFes +dependencies: + apm: []