ソースコード中のコメントを書く時の心得。コメントに何を書き、何を書かないかの判断基準と、置く位置、日本語の文体を定める。ソースコードのコメントを書く時、直す時、レビューする時に読み込む。
The English summary is being prepared. Showing the original description.
See how to installReview the instructions the agent will receive before you install.
ソースコードのコメントを書く時、直す時、レビューする時は、以下の基準に従う。
コメントに書いてよいのは、コードを読んでも分からない事だけである。非自明な制約、invariant、隠れ仕様、gotcha、特定のbugへのworkaroundがこれに当たる。なぜそうするかという意図も書いてよい。
コードや配置から読み取れる事を、言葉でなぞらない。配置とは、ファイルの位置、関数名、周辺のコードの事である。自明な説明は実装との二重管理になり、コードを変更した時の更新漏れの原因になる。読み手には、コードと違う事を言っているかもしれないと疑う負担をかける。
text.replaceAll('\0', '') の直上に // NULを弾く と書かない(test ...) を付けるコードは、その式だけで、test送信を区別する意図が読める書いてよいコメントの例を挙げる。
// TextDecoderが既定でBOMを除去する// 上流APIの制約で、書き込みはPAT認証のみ// .trim()ではなく末尾改行のみ除去する。先頭空白は保持したいコード内のコメントの読者は、pull requestのレビュアーだけでなく、merge後の未来のコントリビューターも含まれる。「従来は」「今までは」のように相対的な時点を参照すると、mergeされた後に基準の時点が失われ、意味を持たなくなる。「matchする文字列は変わらない」のように、比べる相手がmerge後のコードに存在しなくなる文も同じで、何を指すのか後から意味不明になる。「〜のまま」「〜なくなった」「〜ようになった」にも、変更前との比較が隠れている事がある。コメントは現在のコードの意図だけを述べる。pull requestのレビュアーだけに向けた説明には、GitHubのコメント機能を使う。
// 先読みはReDoS対策。後ろのpatternを変える時は先読みも合わせる のように書く公開されるrepositoryやpackageのコメントに、非公開のコードの実装の機構を書かない。file path、関数名、middleware名がこれに当たる。
外から観測できる仕様を根拠にした理由は、書いてよい。「URLのタイトル部分に生の / が来ると、サーバーが拒否するので、ここで正規化する」は観測できる仕様で、サーバーのどの関数が何をしているかは実装の機構である。
読み手が実装を読む時に要る情報は書く。既存のコメントを点検した結果、大半が正当な意図の説明で、現状維持になる事もある。
// 2026/09/12 05:03:21 UTCという形式を返す のように書く。整形のオプションの羅列から、出力の形は読み取れない// 使用例: rateLimit({ cost: 1 }).or(fallbackHandler) のように書く。関数の冒頭にvalidationやsetupがあり、返り値が更にchainできる事が定義から分かりにくい時に役立つ文体はkuden:writing skillの基準に従う。コメントでは、さらに次の2点を守る。
。 を付けない。複数の文を区切る途中の 。 は残すNo reviews yet. Tell others what you thought.
No login needed. Share how it worked for you, ask a question, or note where it did not run.
No comments yet. Be the first to write one.
Agent Skillを書く時の心得。SKILL.mdに何を書き、何を書かないかの判断基準を定める。AIが読んで従う文書に共通の心得は、kuden:common-rules-for-agent-instructionsにある。 Agent Skillを作成する時、編集する時、レビュー指摘の採否を決める時に読み込む。
The English summary is being prepared. Showing the original description.
リポジトリのセキュリティ調査を領域ごとに進める。同じサービスを構成する複数のリポジトリを束ねて調査できる。 このsessionは調査を指揮し、領域ごとに起動したsubagentが調査してレポートを出力する。 レポートの問題のトリアージと、問題の自動修正、問題を直すpull requestの状態の同期も指揮する。 複数sessionにまたがる長期作業を想定し、実行するたびに現状を確認して続きの作業を行う。 ユーザーが手動で起動する。
The English summary is being prepared. Showing the original description.
セキュリティ調査で検出された問題を1つ修正し、pull requestをready for reviewまで仕上げる。 codepatrol skillが起動したsubagentが実行する。ユーザーが直接呼び出す事は想定していない。
The English summary is being prepared. Showing the original description.
本番に出る前の修正が積まれたrelease pull requestに、デプロイの前後に人間がやる事をまとめたコメントを投稿・更新する。 codepatrol skillが起動したsubagentが実行する。ユーザーが直接呼び出す事は想定していない。
The English summary is being prepared. Showing the original description.
リポジトリの1つの領域をセキュリティ観点で調査し、Codexの批判的レビューを経てレポートを出力する。 codepatrol skillが起動したsubagentが実行する。ユーザーが直接呼び出す事は想定していない。
The English summary is being prepared. Showing the original description.
セキュリティ調査に使う調査対象リストと観点リストを、リポジトリのコードを読んで生成・更新する。 codepatrol skillが起動したsubagentが実行する。ユーザーが直接呼び出す事は想定していない。
The English summary is being prepared. Showing the original description.