Imported from BoxPistols/dev-album (
AGENTS.md). Install upstream withnpx skills add BoxPistols/dev-album. Copyright stays with the author.
AGENTS.md
AI コーディングツール（Claude Code / Cursor / Copilot 等）共通の規約の正本（SSOT）。 ツール固有の指示は CLAUDE.md、アーキテクチャと設計判断は ARCHITECTURE.md、 機能仕様は specs/ を参照。ここに書いた規約は全ツール・人間の共通基準とする。
プロジェクト概要
- Web 開発の実践リファレンス教材（React 19 + TypeScript + Vite + Tailwind CSS 4 + wouter）。
- パッケージマネージャは pnpm 固定（
packageManagerフィールド）。npm/yarn を混在させない。
ビルド・テスト・開発
pnpm install --frozen-lockfile # 依存インストール（lockfile 厳守）
pnpm dev # 開発サーバ（Vite）
pnpm check # 型チェック（tsc --noEmit）
pnpm test # 単体テスト（Vitest）
pnpm test:e2e # E2E 全スペック（Playwright, a11y 含む）
pnpm test:a11y # a11y のみ（axe-core, 3テーマ）
pnpm test:storybook # story ごとの a11y 検査（chromium で実描画）
pnpm check:prose # 文章の検査（差分で足した行だけ。textlint）
pnpm build # 本番ビルド- CI は
verify（型チェック → 単体テスト → ビルド）とe2e（Playwright 全スペック）の 2 ジョブ。push 前にビルド + テスト通過を確認する。 - 外部に出る検査は PR ゲートに入れず、定期実行で回す。頻度は変化の速さと所要時間で分ける。
- 週次:
.github/workflows/link-maintenance.yml。check:links（727 URL・約 5 分）を回し、リダイレクトをfix:linksで恒久 URL に書き換え、書き換え後にもう一度check:linksを回してから PR を出す。再検査で切れが増えたら PR を出さず issue に回す。自動マージはしない（再検査は「届くか」しか見ず「同じ内容か」は見ないため）。 - 月次:
.github/workflows/source-checks.yml。引用の逐語照合（medium だけで 22 分・全部で 40 分）とcheck:freshness。引用のズレは出典側の改稿でまとめて出るので、週次で回しても同じものを何度も見るだけになる。
- 週次:
- 定期実行の報告は固定タイトルの issue 1 本に集約する（
.github/scripts/append-or-create-issue.sh）。実行ごとに issue を立てると件数が膨らんで運用が破綻する。機械で直せるものは自動修正に回し、issue には判断が要るものだけを残す。 - ローカルで E2E を回すときは 空きポートを明示する（
PORT=3400 pnpm test:e2e）。既定の 3000 が他プロジェクトに使われていると、そのサーバを再利用して誤った結果になる。
コーディング規約
- TypeScript の
any/@ts-ignoreを使わない。 - コンポーネントは PascalCase、hooks は
useプレフィックス、定数は UPPER_SNAKE_CASE。 - 単一責任（1 コンポーネント 1 責務）。副作用は hooks に分離。Props は必ず型定義。
- 色は CSS 変数トークンのみ（
text-foreground/bg-muted等）。text-black/text-white/bg-white/bg-gray-*の直接使用は禁止。 --primary系はマニュアルごとに差し替わる（[data-manual]）。text-primaryを載せる自己色ティントはbg-primary/10を上限とし、トークンを変えたらclient/src/lib/theme-contrast.test.tsを通す。- ハードコードされた文字列（i18n 対象）・API キー/シークレットをコードに書かない。
console.logを commit しない。
テスト方針
- 単体テストは Vitest、E2E / a11y は Playwright。
- ロジック（純関数）は単体テスト、アクセシビリティは axe-core で 3 テーマ検査。
- 色トークンのコントラストは二段構え。
theme-contrast.test.ts（単体）がソースに実在するクラスの組を全マニュアル × 全テーマで網羅し、axe（E2E）が実描画で裏を取る。 - UI/レイアウト・色を伴う変更は「ビルド緑」だけで判断しない。実描画（スクリーンショット or a11y 検査）で確認する。
- コントラスト等の数値は手計算せず、検算ツールで実測して ground truth を確定してから採用する。
- 教材やフロント側がこのリポジトリ自身の実装（
api/lib/quota.tsの層や.github/workflowsの permissions など）を写している場合は、ファイル先頭に// implementation-mirror: <写している実装のパス>を書く。client/src/lib/implementation-drift.test.tsがこの印を走査し、印の付いたファイルは同 test の REGISTRY で実装の現在値と突き合わせる。印だけ付けて検査を足さないと落ちるので、新しく写す箇所を作るときは検査も一緒に足す。環境変数で決まる値（匿名の 1 日上限など）は具体値を書かず「デプロイ時の設定値」と書く。
PR / コミット規約
- コミットメッセージは日本語・簡潔。
Co-Authored-By/ 絵文字 / 自動生成署名を含めない。 - 1 PR = 1 関心事。
git add .より対象ファイルの明示を優先。 - PR は CI（verify + e2e）緑を確認してからマージ。Vercel プレビュー配信の pending / CodeRabbit の rate-limit は非ブロッキング。
- main へは直接コミットせず、feature ブランチ → PR → マージコミット方式。
レビュー基準
- 正確性: 事実主張（実測値・仕様）をツール出力で裏取りする。
- アクセシビリティ: WCAG AA、キーボード操作、色だけで情報を伝えない（アイコン + テキスト併用）。
- 保守性: 過剰な抽象化・未依頼のリファクタをしない。共通化は 3 例目で抽出する。
- セキュリティ: 秘匿値をコード/記憶に残さない。GitHub Actions で untrusted な context 式を run に直挿ししない。
教材コンテンツ規約
- トーンはフラットで実用的（Progate / オライリー）。エモーショナルなコピー・ネガティブ訴求・クリシェを禁止。
- 教材ページの追加/更新時は
client/src/data/announcements.tsの先頭にエントリを追加する。 - 「仕様値 vs 実測値」がズレる箇所は先に明示する（学習者が折れないため）。
- 新しく書く文章では、日本語と英数字の間に半角スペースを入れない。コード内のコメントと文字列も対象にする。既存の行は一括で直さず、
pnpm check:proseが差分で足した行だけを検査する（CIのverifyでもPRごとに回る）。検出された行は手で直し、textlint --fixや整形をファイル全体に掛けない。
スペック駆動（新機能の進め方）
複数ページにまたがる機能・セクション追加は、まず specs/ に仕様を書いてから実装する。
適用/非適用の判断基準と 6 フェーズのワークフローは specs/README.md を参照。