🕵️‍♀️

たった数行でコード品質がグッと上がる、CLAUDE.md / AGENTS.md にいつも追記してるやつ

に公開
Next.js
TanStack
Claude Code
Codex
AGENTS.md
tech

Tanstack startかNext.jsで実装する前提で書いてますが、何にでも応用出来るかと思われまス

create appしてリポジトリ立ち上げたときは、最初のルールと、最初のコードがどういう感じで書かれたかで、成果物の点数の99%が決まりますネ

なぜならClaude codeもCodexも空気を読んで既存スタイルに合わせるからですネ

ボクは、最初は１画面・１機能だけ作らせて、コードが気に入らなかったら全消ししてcreate app直後からやり直してますヨ

なので、最初の立ち上げ時、バイブコーディングのスタイルでも、いつも1時間くらいかかりまス

そして以下で書いたルール、このルールだけでとりあえず誰でも60点くらいのコードは目指せるのではと思います

特に軽視されてるのがJSDoc(TSDoc)だと思っていて、必ず書かせるとガチめに品質あがります

Effect TSなどを入れる手もありますが

まずは人間も読みやすく導入もclaude codeにやらせれば一気に書いてくれるJSDoc / TSDocでいいのではと思います

claude opus 4.7 でも特段能力が落ちてるように感じないのはこれが理由だとおもってます

ただしベンチを取っているわけでもないし、なんとなく雰囲気でなので、ボクを信じてください以上のデータはありません

AGENTS.md / CLAUDE.md に必ず入れてるやつ

  • KISS, DRY, YAGNI を守る
  • TSDoc を書くこと（ts, tsxともに必須。@param, @returnsなど）
  • すべての .ts / .tsx ファイルの冒頭に、そのファイルの役割・責務を2行程度で記述
  • コロケーションを重視すること
  • docs/以下にドキュメントがあるので必要なときに参照すること。ファイル名で判断すること。追加するときはファイル名をわかりやすくつけること。
  • ADRを書くこと（docs/adr以下に）。設計上の重要な判断をしたときは必ず書くこと。書くべきか迷う場合はユーザーに確認すること。append-onlyで、過去の内容は変更しないこと
  • アイコンは lucide-react を使用（絵文字は使わない）
  • デザイントークンを定義すること、Tailwind デフォルトカラーは使わない、既存トークンとのトンマナを考えて自前で色を作る、oklchを使うこと
  • UIは視線の流れを意識すること

DB使うとき

  • DBに影響ある実装をする場合は、フルスキャン/ USE TEMP B-TREE にならないことをインデックス、クエリから確認し、想定クエリをEXPLAINするなど万全の注意を払ってから実装すること

Next.js 16.2 以上を使ってる時限定で、AGENTS.md / CLAUDE.md に入れてるやつ

  • <Suspense> はページ全体を包まない
  • コロケーション: いきなり広いスコープに置かない。まず最小スコープ（_components/ / _lib/）で定義し、複数箇所から使うようになってから共有（components/ / lib/）へ昇格する

Next.js 16 の知識を与える

ここに書いてることやると一気に性能があがる

https://nextjs.org/blog/next-16-2-ai

具体的には以下をAGENTS.md / CLAUDE.md にいれるだけ
中身は、自分の学習をあてにせずdoc読みなさいよーってこと
Next.jsは16から大きく変わったので、知識与えないと間違いまくります

<!-- BEGIN:nextjs-agent-rules -->
 
# Next.js: ALWAYS read docs before coding
 
Before any Next.js work, find and read the relevant doc in `node_modules/next/dist/docs/`. Your training data is outdated — the docs are the source of truth.
 
<!-- END:nextjs-agent-rules -->

さいごに

役に立ったら高評価、チャンネル登録、よろしくお願いします✨️

Discussion