writing-lean

簡潔に書く

コードとその仕様が最初に参照すべき情報です。このプロジェクトに初めて触れる人は、それらを読んで理解できるべきです。簡潔な文章とは、コードと仕様だけでは伝えられないことだけを伝えるものです。

• まずコードを見直します。 説明を長くする前に、より明確な名前、小さな関数、より的確な仕様を検討します。
• 1つの概念には1つの言葉を使います。 概念には、GLOSSARY.md またはコードにあるプロジェクトの用語を毎回使います。同義語は別の概念として受け取られます。
• 何をするかを伝えます。 禁止事項ではなく、目的（「1行コメント」など）を示します。禁止事項を記載するのは、強い制約として必要な場合に限り、代わりに何をすべきかも併記します。
• 必要な場所に1回だけ書きます。 各情報の唯一の参照元は以下のとおりです。それ以外の場所では、そこへのリンクを記載します。
• 経緯は議論の場に残します。 検討したことや却下した案は、議論や差分と並べて確認でき、git blame からたどれる issue、プルリクエスト、またはコミットに記載します。

削除テストを、書いたり変更したりするすべての文の基準にします。その文を削除したら、知識のある読者は何を失うかを考えます。何も失わないなら、コードがすでに伝えているため、その文は削除したままにします。

記載場所

チャネル	役割
コード	流暢さ：機能を伝える、簡潔でわかりやすい関数名と変数名
コードコメント	制約、落とし穴、出典、または自明でない理由を、該当する行に記載します
ドキュメントコメント	メンバーの用途を1文で説明します
README	一般的な利用方法：概要、使い方、次に進む場所
リポジトリのドキュメント	コードでは示せない決定事項や背景情報
issue	何を求めているか、その理由を issue フォームの各項目に記載します
エージェント向けブリーフ	契約：動作、受け入れ基準、範囲
プルリクエスト	変更内容と理由を、関連する issue にリンクして記載します
コミットメッセージ	変更内容を記載し、差分から理由がわからない場合はその理由も記載します
レビューコメント	指摘事項とその修正を1つずつ記載します
スレッドコメント	新たな事実や決定事項を、回答対象へのリンクとともに記載します
スキル、AGENTS.md	エージェントが作業する方法：手順と、その根拠となる参照情報

コードからのリンク

コード内で issue を引用するのは、その issue が後のコード変更方法に影響する場合に限ります。たとえば、clhbid/api#123 のリリース後に削除する回避策や、未決定事項によって維持されている制約などです。それ以外の場合は、git blame からプルリクエストとその issue をたどれます。