Imported from sinotca529/zakki (
AGENTS.md). Install upstream withnpx skills add sinotca529/zakki. Copyright stays with the author.
AGENTS.md
zakki の開発にあたっての取り決めです。人間と AI エージェントの両方に適用します。
コードから読み取れること (ディレクトリ構成、依存ライブラリ、アーキテクチャの説明) は、 意図的に書いていません。コードが変わったときに古いまま残り、誤った案内をするためです。
言語
- 会話は日本語で行う
- コメント、ドキュメント、エラーメッセージも日本語で書く (ただしカッコなどの記号は半角を使う)
- 変数名・関数名は英語
文体
ドキュメント、コミットメッセージ、レビューコメント、会話のすべてに適用します。
表記
- ですます調で統一する。常体と混ぜない。
- 太字は使わない。ラベルも
[must]と書く。 - 会話では見出しを使わない。見出しは GitHub のコメントやドキュメントなど、 読み返される文章にだけ使う。
- 見出しは名詞句にする。文にしない。接続詞で始めない。
目次に並べて意味が通るかで判断する。
- 「ただし挙動が違います」→「挙動の違い」
- 「前言を訂正します」→「訂正」
- 会話の返答は、要点と判断を仰ぐ点に絞る。同じことを言い換えて繰り返さない。
- 表と箇条書きは、並列の項目が3つ以上あるときだけ使う。
言い回し
- 物理的な実体のないもの (指示、設定、規約、エラー) を主語にして、
比喩的な動詞を使わない。何が起きるかを具体的に書く。
- 「指示が効かない」→「指示が読み込まれない」「内容が反映されない」
- 「効くのは長さです」→「効果があるのは長さです」
- 「静かに壊れる」→「エラーが出ないまま読み込まれない」
- 「バグが生きている」→「まだ直っていない」「再現する」
- 「画面は無反応です」→「画面上はわかりません」
- 「穴を塞ぐ」→ 比喩をやめて、何が防げるのかを書く
- 英語表現の直訳を使わない。
- 「(読み手が) 止まる」→「引っかかる」「分かりにくい」
- 「情報にならない」→「区別がつかない」「意味がない」
- 一般に使われていない言い回しを持ち出さない。思いついた語は検索して、 実際に使われているか、別の意味を持っていないかを確かめる。
- 「唯一の」「まさに」「そのものです」のような強め方をしない。
- 自分がした行為は「〜しました」と書く。「〜してあります」と書かない。
- 「1文だけ」「わずか3行」のように、量を添えて控えめさを示そうとしない。
- 指示語と抽象名詞の組み合わせでぼかさず、関係を名指しする。
- 「まさにその形で古くなった」→「それが原因で古くなった」
- 事実をそのまま書き、評価や身振りを足さない。
- 「直し方が確定しています」→「修正方法は〜です」
- 「成功することまで示せます」→「成功することまで確認できます」
- 段落の最後を一文で決めようとしない。言い切りの型を繰り返さない。
- 同じ語尾を続けない。接続詞は必要な場所だけに置く。
不自然な言い回しを見つけたら、この節に例を足していきます。 足すのは、また使いそうな語のときだけにします。その場限りの言い換えは書きません。
この節のうち機械的に判定できるものは .claude/hooks/check-style.sh が検査します。
ファイルを編集したときと、GitHub にコメントを投稿する前に実行されます。
まとめて調べるときは引数にファイルを渡します。
git ls-files '*.md' '*.rs' | xargs .claude/hooks/check-style.sh検査は 2 段に分かれます。全角記号、太字、見出しの形は grep で判定し、
node がなくても動きます。語彙と日本語の一般的な規則は textlint に任せます。
禁止する語は .claude/hooks/prh.yml に、有効にする規則は
.claude/hooks/.textlintrc.json に書きます。導入は次の通りです。
cd .claude/hooks && npm cinode_modules がない環境では textlint の分を飛ばし、grep の分だけ実行します。 主語が誰か、比喩かどうかは判定できません。正しい用法まで検出されたときは 作業者に相談します。
検証
CI と同じ引数で実行します。引数が違うと、手元で通っても CI で落ちます。
cargo fmt --check
cargo clippy --locked --all-targets -- -D warnings
cargo test --locked出力の変化を伴う修正では、cargo test だけで済ませず、実際にサイトを生成して確認します。
リファクタリングの場合は、変更前後で生成物を全ファイル比較します。
暗号化ページの data-cypher は IV が毎回変わるため、ここだけは一致しません。
cargo build --release
cd <テスト用サイト> && <path>/zakki buildレビュー
進め方
- 1ラウンドあたり3〜5件、1〜2ファイルに絞る。
- 指摘は
[must]/[should]/[nit]のいずれかのラベルを付ける。 - 本文にまとめて書かず、該当行へのインラインコメントにする。 本文は読み返されにくい。
- 相手が返信したコメントには必ず返答する。返答がないと、閉じてよいか判断できない。
- 対応が確認できたスレッドは resolve する。
- GitHub に書いた内容を会話で繰り返さない。会話では要点と、判断を仰ぎたい点だけを書く。
指摘する前に
git blameで、そのコードを誰が書いたか確認する。 自分の過去の提案をコピーしたものを、他人の判断として指摘しない。- 推測で断定しない。zakki のコードの挙動についての主張は、実際に動かして確認してから書く。 確認できなかった場合は、確認していないと明記する。
- ブラウザやライブラリの仕様、既知の不具合は、手元で再現を試みる前に調べる。 再現できない環境を作り直そうとしない。
- 数値を伴う主張 (速くなる、軽くなる) は、測ってから書く。
指摘の書き方
- 何が起きるかを書く。直し方だけを書かない。
- 判断を相手に委ねる場合は、そう明記する。
- 既存コードへの指摘は、この変更で持ち込まれたものか、以前からあるものかを区別して書く。
git
- ユーザーの指示がない限り、エージェントはコードの変更や PR 作成を実施しない。
- main への直接 push は禁止 (ルールセットで制限済み)。