yomitoki: Cut the time to understand code

# yomitoki 目標は、他の人がコードの目的と動作を理解するまでの時間を減らすこと。行数の少なさや見た目の統一だけで良し悪しを決めない。 ## 既存コードの修正を始める 対象と修正依頼の範囲が明確で、小さな対象を修正するときは、最初に次の経路を使う。レビューだけの依頼、新規コード、独自の検査設定、大きな対象は後述の個別手順を使う。 1. このスキルを読んだら、基準・手順・ソースを個別に取りに行く前に `begin --context --state-root` を実行する。対象外の保存用親ディレクトリと、導入済みRuffを指定する。既存の親ディレクトリでも一意な子保存先が自動作成される。返された全ソース・14項目の基準・実行手順を読み、契約を押さえて方針を決める。 2. 関連する編集と直後の構文確認を、一つの呼び出し内で順番に行う。ファイル編集ツールがあれば使い、引用符を組み直すためのシェルや文字列置換スクリプトを増やさない。14項目ごとの根拠をJSONに記録する書き込みも同じ呼び出しにまとめられる。 3. 編集を終えたら整形・構文確認・プロジェクトの検証・`finish --include-diffs --review-notes` をまとめて実行し、それぞれの結果を保持する。返された全差分と14項目の根拠を読んで、契約と照合する。必要な修正が見つかった場合は再編集・再検証する。 ```bash python /path/to/yomitoki/scripts/review_session.py begin --context --state-root /path/outside/reviews --ruff /path/to/ruff /path/to/module.py /path/to/test_module.py # 全資料を読んで判断し、編集・構文確認・14項目の記録・必要な検証を行う # 結果の stateDir・reviewNotesPath を使い、finishCommand の引数で最終検査する ``` `context.sources` は退避した全ソースを含む。次の編集の判断にその内容を使い、同じ内容の `cat`・`Get-Content` を追加しない。追加で読むのは未取得・省略された部分、対象外の呼び出し元、または変更後の内容が必要な場合。記載された引数で実行できると分かっている場合、同じ確認のためだけの `--help` は不要。ツールの出力上限は全文を読める量に設定し、途中で切れた場合は未読部分を追加で読む。短くするために資料や確認項目を切り捨てない。 PowerShellでは最初の読込・実行と同じ呼び出しの冒頭で `[Console]::OutputEncoding = [System.Text.Encoding]::UTF8; $OutputEncoding = [System.Text.Encoding]::UTF8; $env:PYTHONIOENCODING = 'utf-8'` を設定する。ファイルを読むときは `Get-Content -Encoding UTF8` を使う。新しいシェルで実行する場合も同様に設定し、文字化けを直すためだけの再読込を防ぐ。 実行ツールを別のツールでラップしている場合、出力上限は内側と外側の両方へ指定する。Codexの `functions.exec` では外側の予算も必要になる。例えば、同じ呼び出しで次のように指定できる（数値は対象量に合わせる）。 ```javascript // @exec: {"max_output_tokens": 24000} const result = await tools.exec_command({cmd: "... begin --context ...", max_output_tokens: 20000}); text(result.output); ``` 「truncated」などの省略通知があれば、14件の確認記録が揃っていても全文確認済みと扱わない。未読部分を読み、該当する根拠を再確認する。ツールの成功やテストの成功は、資料・ソースの全文が届いた証拠にはならない。 ## 依頼の範囲を確かめる - レビュー・評価・改善案の依頼なら、コードを編集せず、読み手が困る箇所と具体的な改善案を報告する。 - 修正・リファクタリングの依頼なら、対象範囲を編集して検証する。コード作成中の利用なら、同じ基準を新しいコードに適用する。 - 対象が省略されている場合は会話中のファイルや差分から判断する。特定できなければ対象を確認する。全リポジトリの改修へ広げない。 ## コードの目的と契約を読む 対象ファイルだけでなく、理解に必要な呼び出し元・型・テスト・プロジェクトの規約を読む。Git 管理下なら差分を確認し、ユーザーの変更を保護する。 まず「何を受け取り、何を判断し、何を返すか」を短く説明する。理解を妨げる名前、条件、状態の追跡、責務の混在を特定する。 変更前に保つべき挙動を押さえる。特に以下は、見た目だけの変更でも壊れやすい。 - 公開 API、エクスポート名、JSON・DB のキー、設定名、外部で使われる名前 - 境界値、null や未定義値の扱い、例外の種類 - 短絡評価、評価回数、処理順序、副作用、非同期処理 - return・continue によって省略される後処理やリソース解放 バグ修正や仕様変更が必要になったら、可読性の変更と区別する。依頼で許可されていない仕様変更を混ぜない。 コメント・名前・資料とコードの動作が食い違うときは、どちらが正しいかを推測で決めない。コメントをコードに合わせると、コードの誤りを隠してしまうことがある。修正の依頼でも食い違いはそのまま残し、確認が必要な点として報告する。 対象に関係する契約と、その根拠になる呼び出し元・テストを短く控える。分からない仕様を推測して補わない。判断できない箇所は維持し、作業を進めるために必要な点だけ確認する。すでに読みやすい箇所はそのまま残す。 編集するファイルは、未コミットのユーザー変更も含む現在の内容を、対象の外に一意な名前で保存する。Git の HEAD を無条件に変更前としない。下の `review_session.py begin` で退避と変更前検査をまとめられる。手動で保存するときは [references/change-review.md](references/change-review.md) の保存手順を参照する。 ## 言語に応じて先に機械検査する Python・C・C++・Java・JavaScript・TypeScriptは、以下の付属検査で構文指標（関数の行数・引数数・ネスト・複雑さ・入れ子の三項演算子）を測る。PythonはRuffのlint・整形も付属検査に含む。Python以外のlint・整形・型チェックとHTML・CSSは、[言語別の機械検査](references/language-checks.md) の共通手順と対象言語の資料だけを読み、既存の設定と導入済みツールを確認して、対象範囲を変更前後に検査する。 資料のない言語もプロジェクト既存の検査を優先する。ツールがない、設定が不足する、対応構文を解析できない場合は、検査できなかった範囲と理由を報告し、手動確認と区別する。 ### 付属検査 [scripts/run_checks.py](scripts/run_checks.py) で構文指標と、PythonのRuff lint・整形を検査する。既存コードの修正では、[scripts/review_session.py](scripts/review_session.py) の `begin` と `finish` で退避・前後検査・比較・差分保存をまとめる。`begin --context` に [退避と前後検査](references/review-session.md) の全文が含まれるため、実行前の別読みは不要。個別手順の詳細が必要な場合だけ同資料を参照する。独自の閾値や許容リストが必要なら、[個別実行手順](references/workflow-checks.md) を使う。指標の定義を調べるときだけ [references/mechanical-checks.md](references/mechanical-checks.md) を参照する。 ```bash /path/to/yomitoki/.venv/bin/python /path/to/yomitoki/scripts/run_checks.py /path/to/project ``` Python以外の構文解析にはtree-sitterを使うため、`requirements.txt`を導入したスキル直下の`.venv`のPythonで実行する。導入されていなければ該当ファイルは検査エラーになる。Windowsでは、コマンドの`python3`を`python`に、`.venv/bin/`を`.venv\Scripts\`（Git Bashでは`.venv/Scripts/`）に読み替える。 これはスキルの付属検査であり、Ruff lintはPythonファイルだけに `F401,F841,SIM,RET` を独立した設定で調べる。プロジェクト既存のlint全体・型チェック・テスト・ビルドは実行しない。 測れる項目はスクリプトの結果を根拠にし、LLMの印象だけで行数や複雑さを断定しない。閾値はこのスキルの初期設定であり、普遍的な合格基準ではない。 検査指摘は確認候補として扱い、数値を下げるだけの分割・仕様変更・説明の削除をしない。命名の適切さ、責務、コメントの正確さ、挙動の同一性は別途コードとテストで確認する。 既存コードの修正では、修正前後のJSONを保存して [scripts/compare_reports.py](scripts/compare_reports.py) で比較する。`begin`・`finish` を使った場合は保存と比較が済むため、同じ検査を表示形式だけ変えて繰り返さない。合格のために閾値を緩めない。新しく書くコードは比較の相手がないため、`run_checks.py` で単独に検査し、テストで確かめる。 実行前にインタープリター・依存・書き込み可能な退避先を一度確認し、その実行パスを使い続ける。権限拒否や実行失敗は原因を確認してから対応し、同じ操作を引数の形だけ変えて繰り返さない。整形ツールが使えないとき、書式合わせだけの大量の手動編集に置き換えず、制約として報告する。 小さな対象では `begin --context` で、14項目の基準・実行手順・退避した全ソースを変更前の検査結果と一緒に読む。すでに同じ内容を読んだ場合は再読しない。対象が大きい場合は意味のまとまりごとに読み、量を減らすために必要なソースや基準を省略しない。 `begin` の後は14項目の確認から修正方針を決め、関連する編集と整形をまとめて終えてから `finish` を使う。整形だけを先に済ませた途中段階や、次に編集することが分かっている段階で `finish` を呼ばない。最終差分で必要な修正が見つかった場合は、修正して再検証する。PowerShellでの整形・構文確認には [そのまま実行できる例](references/review-session.md#powershellでの整形と構文確認) を使い、bashの標準入力構文を流用しない。 ## 理解の負担を減らす レビューでも修正でも、[references/principles.md](references/principles.md) の14項目をすべて読み、対象のコードを14項目それぞれについて確認する。具体的な判断と例はその資料に従う。 呼び出しをまとめても、14項目の判断は項目ごとに行う。各項目について確認したファイル・関数と判断の根拠を短く記録し、「確認済み」「対象外（理由あり）」「未確認」を区別する。まとめて「問題なし」とは記録しない。修正時は [レビュー記録](references/review-session.md#14項目の確認記録) を `finish --review-notes` に渡す。記録の項目数が揃っても、判断の正しさや見落としのなさを保証するものではない。 1. 名前・配置・コメントから始める（項目2〜6）。具体的な名前、意味のある順序、論理的な空行で、処理の意図を表す。 2. 条件式と制御フローを整える（項目7・8）。説明変数や早期 return が理解を助ける場合に使う。単純な式まで細分化しない。 3. 追跡する状態を減らす（項目9）。変数のスコープと再代入を減らし、不要な一時変数を除く。意味を伝える変数は残す。 4. 混在した責務を整理する（項目10・11）。まず処理をまとまりごとに並べ、意味のある名前と境界ができる場合に関数を抽出する。 5. コードを簡単な言葉で説明し、読み手が目的・入力・出力・例外を短く説明できるか、その説明と名前・処理順序が対応しているかを確認する（項目1・12）。 6. 必要なコードだけにする（項目13）。既存関数や標準ライブラリで明快に書けるなら使う。重複は同じ意味と変更理由を持つ場合だけ共通化する。コメントアウトされたコードやテストは、有効にも削除もしない。有効にすると挙動やテストの範囲が変わり、削除すると残された意図が分からなくなる。意図が読み取れなければ報告する。 7. テストも同じ基準で読む（項目14）。テスト名に状況と期待結果を示し、重要な入力と期待値をヘルパーに隠さない。テストを整理するときは、ケースやアサーションを減らさず、依頼がなければ新しいケースも加えない。足りないと思うケースは提案として報告する。名前を付けたら、実際の入力と期待値に合っているかを確かめる（境界の上・ちょうど・下を取り違えない）。 必要な改善だけを行う。既存の言語・フレームワーク・命名・フォーマッターの慣習を優先する。改善のためだけに依存関係、汎用基盤、階層、将来用の機能を追加しない。 関連する変更はファイル単位でまとめる。複数の処理を扱えるツールでは、編集と、その直後の構文確認を一つの呼び出し内で順番に行う。Pythonで関数抽出やインデント変更など構造を編集した直後は、次の編集へ進む前に変更したファイルをコンパイルして構文を確認する。失敗したらその編集を修正して再確認し、先へ進まない。対象コードは実行しない。例えば `python3 -m py_compile /path/to/changed.py` を使う。キャッシュを書きたくない場合の方法は [workflow-checks](references/workflow-checks.md#編集直後の構文確認) を参照する。 短いヘルパーの大量追加や、意味の異なる処理の共通化で、読み手が行き来する量を増やさない。削除候補は静的検索だけで断定せず、参照・動的利用・公開契約を確認する。 ## 検証して伝える 数値の前後比較に加え、保存した変更前と最終コードの差分を読み、最初に控えた契約と照合する。`finish` は全対象のテキスト差分と、変更したPythonの [scripts/diff_code.py](scripts/diff_code.py) の結果を保存する。その成果物を使い、同じ差分の再生成は不要。個別実行や照合観点の詳細が必要なら [変更内容の点検](references/change-review.md) を参照する。 編集完了後は、整形・構文確認・プロジェクトの検証・`finish --include-diffs --review-notes` を同じツール呼び出し内で順番に実行できる。各処理の終了コードと結果を保持し、途中の失敗を最後の成功で上書きしない。返された全差分と14項目の記録を照合してから完了する。未確認の項目や必要な修正が残る場合は再判断し、呼び出し回数の目標を理由に省略しない。 コードを変更した場合は、プロジェクトで求められる lint・型チェック・関連テスト・ビルドを実行する。対象に存在しないチェックは作ったことにせず、実行不能なら理由を報告する。 既存テストでは不安が残る分岐や副作用に、必要な検証を追加する。新しいヘルパーの内部構造や変数名だけを固定するテストは作らない。テストを弱めて成功させない。 好みや指摘数だけを理由に書き直しを繰り返さない。読みづらさが解消し、契約の差分確認と必要な検証が済んだら終える。その後に対象・設定が変わらず未解決の失敗もなければ、検証は繰り返さない。変更が原因の検証失敗や契約の破壊は修正し、影響する検査を再実行して最終差分を確かめる。修正回数の上限を理由に失敗を放置しない。 結果は簡潔に報告する。 - レビュー：箇所、該当する項目（principles.md の番号1〜14）、理解しづらい理由、具体的な改善案。主観的な好みと、仕様の確認が必要な点は、それぞれ分けて示す。 - 修正：以下の4つを短く報告する。指摘なし・未検証なしの場合も「なし」と記載する。 ```text 変更内容: 変更箇所、該当する項目（principles.md の番号1〜14）、理解しやすくなった理由。 通過した検査: 付属検査とプロジェクトの検査を分け、実行したコマンドと確認範囲を記載。 残っている指摘: 既存・今回追加を区別し、許容した指摘と維持する理由、失敗した検査、確認が必要な仕様の食い違いを記載。 未検証の範囲: 未実行・実行不能の検査と理由、挙動について確認できていない点を記載。 ``` コミット、push、デプロイは可読性改善に含めず、ユーザーの指示とプロジェクトの権限に従う。