J-paku.github.io

Imported from J-paku/J-paku.github.io (AGENTS.md). Install upstream with npx skills add J-paku/J-paku.github.io. Copyright stays with the author.

AGENTS.md

このリポジトリで作業するコードエージェント(Claude Code / Codex / Cursor / Gemini CLI など)の入口。 この文書は知識を持たない。「今の作業でどれを読むか」を決めるためのルーターである。

サイト本体は https://j-paku.github.io/ に配信しているポートフォリオハブ。 Next.js 16(App Router)の静的エクスポートで、サーバもデータベースも無い。人間向けの紹介は README.md。

人はコードを読んでレビューしない。 代わりに制約(テスト・検査)を極端に多く置き、すべて通ったものを信頼する。「完了」はレビューではなく、すべての門を通ったことで言う。

不変ルール(破ったら即中断して報告)

1. locale は location.pathname からのみ決まる。 ?lang=・自動リダイレクトを作らない
2. 表示文字列を content/ の外にハードコードしない。 コンポーネントに日本語・韓国語リテラル禁止
3. localStorage / sessionStorage へのアクセスは src/lib/preferences.ts 一箇所だけ。 例外は src/app/html-shell.tsx のインラインスクリプト1本だけで、初回ペイント前にテーマを当てるためにある
4. フックを呼んでよいのは、src/components/ の中の index.tsx(hooks・__tests__ の中の index.tsx を除く)と、hooks フォルダの中の use- 始まりのファイルだけ。 コンポーネントのフォルダの入口はいつも index.tsx で、外からはフォルダ(@/components/<フォルダの道>)を指す。container.tsx という名前のファイルは置かない。 フックを1つでも呼ぶ index.tsx と、I/O コンテナの6つ(一覧の正本は scripts/container-dirs.mjs)の index.tsx がコンテナで、ほかの index.tsx は表示部品。 hooks フォルダはコンテナのフォルダ(と src/hooks/)にだけ置き、use- 始まりのフック以外を置かない。フックはフォルダ化しても index.ts を作らない。 画面の状態・データのフックと、外の世界に触れる import(保存・天気・計測・SVG の取得・村の時計のストアなど)は、I/O コンテナの6つの index.tsx とその隣の hooks フォルダにだけ置く。 content の読み出しは画面の3つのサーバのローダー(src/app/directory-screen.tsx・src/app/story-screen.tsx・src/app/village-screen.tsx)が行う。 フックを呼ぶ所は ESLint の layer/hook-only-in-container が守らせる
5. wip 作品は詳細ページを作らない。 カードにリンクを付けず、slug 直接アクセスは NotFound
6. 1段階 = 1セッション(大きな改修を1回のセッションに詰め込まない)
7. 新しいロジックは純粋関数(src/lib/・src/utils/・コンポーネント専用のutils)に置き、新しく作ったファイルごとにカバレッジ100%・ミューテーション100%を守る。hooksフォルダに単体テストを置かず、どのテストでもrenderHookを使わない。コンポーネントを描くテストは、コンテナのフォルダに置く統合テスト(コンテナごとに1本以上。1本なら隣の index.integration.test.tsx、2本以上ならそのフォルダの __tests__/<動作>.integration.test.tsx)だけに書き、表示部品は自分のテストを持たない。hooks フォルダの中のファイルと src/components/ の中の全部の .tsx(コンテナと表示部品。テストを除く)は、統合テストのカバレッジでファイル別100%

決めた理由は 1 が docs/decisions/0002-locale-from-url-only.md、2 が docs/decisions/0003-content-outside-src.md、冒頭の方針と 7 が docs/decisions/0011-extreme-constraints.md、 4 のコンテナと 7 のコンポーネントを描くテストが docs/decisions/0019-hooks-make-containers.md(I/O コンテナの6つと画面のローダーは docs/decisions/0017-screen-containers.md、統合テストをコンテナのフォルダに置くことと表示部品のファイル別100%は docs/decisions/0022-colocate-integration-tests.md、コンテナも index.tsx にすることとローダーを src/app/ に置くことは docs/decisions/0024-containers-as-index.md)にある。 3〜5 の詳しい決まりは docs/architecture/data-flow.md・docs/architecture/frontend.md・docs/product/business-rules.md にある。 レイヤー境界(import の向き)と、そのうち機械が守らせている範囲は docs/architecture/boundaries.md。

作業の種類 → 読む文書

左の行にひとつ当てはまったら、そこに挙がっている文書だけを読む。複数当てはまるときだけ足す。

どれにも当てはまらないときだけ docs/README.md(文書全体の地図)を開く。

読まなくてよいもの(重要)

• docs/ を再帰的に読まない。 上の表が指した文書と、その文書が明示的にリンクした先だけを開く
• docs/decisions/ は通常作業で読まない。 読むのは「既存の設計を置き換える」「なぜこうなっているかを問われた」ときだけ
• docs/operations/ は機能追加では読まない。 CI・配信の設定を触るときだけ
• 作業範囲外のディレクトリを探索しない。 村を触るなら src/components/Story/ と src/components/Directory/ は開かない(逆も同じ)。 例外は2つ — 同種の既存実装を1つだけ開いて書き方を合わせるとき、部品を src/components/ui/ へ引き上げてよいか使用箇所を数えるとき
• .claude/ はリポジトリ管理外(.gitignore 済み)。過去セッションの作業メモなので参照しない
• ../portfolio-hub-spec/ はこのリポジトリの外にある参考資料で、大半は過去の段階記録。無くても作業できる。現在の姿の正本はこのリポジトリ内の文書である

作業の進め方

1. この文書の不変ルールと routing 表を読む
2. 作業を分類し、routed された文書だけを読む
3. 触る範囲に AGENTS.md があれば先に読む(content/ src/lib/pixel/ src/components/VillagePage/)
4. 着手から報告までの手順は docs/agents/workflow.md に従う
5. 何をどこまで走らせるかは docs/agents/verification.md

このリポジトリで実際に起きた間違いの一覧は docs/agents/common-mistakes.md。

コミット

• 形式: <type>: <日本語の要約> + 本文は日本語の箇条書き。type は feat / fix / hotfix / refactor / docs / test / chore / ci / perf
• AI 署名を入れない(Co-Authored-By も Claude-Session も書かない)
• エージェントは自分でコミットしない。 利用者が明示的に指示したときだけ実行する