研究室のコーディングガイドライン (GitHubの運用・コードレビュー)

24.2K Views

March 17, 26

#python #matlab #github

スライド概要

東京農工大学の山田宏樹研究室におけるコーディングガイドラインの資料です．GitHubの運用，コードレビュー，ディレクトリ構成に関するルールを決めています．

profile-image
スライド一覧

東京農工大学工学部知能情報システム工学科・先進学際科学府 准教授

シェア

またはPlayer版

埋め込む »CMSなどでJSが使えない場合

ダウンロード

関連スライド

slide-thumbnail

uvを使ったPython環境構築-人工知能応用特論Ⅰ 第3回
python uv
user-img Koki Yamada 116K
slide-thumbnail

VS Codeを活用した開発 (Gitの各種操作・デバッグ) -人工知能応用特論Ⅰ 第5回
user-img Koki Yamada 39.9K
slide-thumbnail

Git・GitHubの実践 - 人工知能応用特論Ⅰ 第2回
user-img Koki Yamada 38.9K
slide-thumbnail

読みやすいPythonコードの書き方 (Ruff・命名規則・型ヒント) - 人工知能応用特論Ⅰ 第6回
user-img Koki Yamada 35.5K
slide-thumbnail

機械学習プロジェクトにおける実験管理
python pytorch-lightning
user-img Koki Yamada 35.4K
slide-thumbnail

pytestを活用したテスト駆動開発 - 人工知能応用特論Ⅰ 第7回
user-img Koki Yamada 17.3K
各ページのテキスト
1.

研究室のコーディングガイドライン (GitHubの運用・コードレビュー) (2026年3月作成) 東京農工大学大学院先進学際科学府 山田宏樹 1

2.

コーディングガイドライン作成の意図 研究コードを再現可能にし，引き継ぎ・共同開発・論文化を円滑にする 研究での手戻りを防ぐ コードの品質を保てる開発習慣 (lintやテスト，バージョン管理など) の定着 指導教員のフィードバックを受けやすくする 研究室メンバー全員がこのガイドラインを遵守すること 相当注意しないとコードの再現性は担保されなくなります．ルールを遵守するこ とで，研究を始めたての学生でも，コードの品質を高め，再現性を担保できるよ うになることを目指しています． 「守破離」という言葉があるように，まずはルールを遵守することで実装の「型」 を身につけ，応用できるようになることを目指しましょう．ルールを課している 意図がわからない・運用上問題が発生している場合は，適宜指導教員に伝えてく ださい．場合によっては，ガイドラインの変更を検討します． 2

3.

この資料のライセンス この資料は以下のGitHubリポジトリで，CC BY-NC 4.0 ライセンスの下で公開さ れています． https://github.com/koki-yamada-lab/lab-coding-guideline 研究室運営におけるGitHubの運用方法やコードレビューについて公開されている 資料があまりなかったので，他の研究室運営をされている方々にも使いやすくな るようCC BY-NC 4.0ライセンスで公開しました．この資料はMarpを使って書いて いるので，markdownで簡単に改変もできます．何か気づいた点があったり，改善 した方が良い点があれば上記のGitHubリポジトリにIssue/Pull Requestをあげる か，下記，山田の連絡先までご連絡いただけるとありがたいです． Twitter: @KokiYamada6 E-mail: [email protected] 3

4.

前提知識 以下の講義資料を学んでいることを前提としています． Git・GitHubの実践 - 人工知能応用特論Ⅰ 第2回 uvを使ったPython環境構築-人工知能応用特論Ⅰ 第3回 Dev Containerによる開発環境の構築-人工知能応用特論I 第4回 VS Codeを活用した開発 -人工知能応用特論Ⅰ 第5回 読みやすいPythonコードの書き方 (Ruff・命名規則・型ヒント) - 人工知能応 用特論Ⅰ 第6回 pytestを使ったテストコードの書き方 - 人工知能応用特論Ⅰ 第7回 機械学習プロジェクトにおける実験管理 4

5.

目次 GitHubの運用ルール リポジトリのルール GitHub flowに基づく開発 コードレビュー Copilotによるコードレビュー 教員によるコードレビュー ディレクトリ構成 Pythonの場合 Matlabの場合 5

6.

GitHubの運用 6

7.

GitHubの運用の意図 1. "Working Out Loud"の思想 自身の作業プロセス，思考，困り事等をチームへオープンに共有する仕事術 作業が途中であってもチームメンバーの目に触れる場所にアウトプットする 研究室で esa を導入して進捗報告等を共有しているのも，これが理由です． GitHubでは，実装の作業プロセスやコードを共有します メリット 作業が可視化される → 早期にフィードバックを得やすくなる 作業の結果だけでなく過程における思考のプロセスも可視化される リモートワーク環境でも，チーム内での知識共有がしやすくなる 参考になるサイト Working Out Loud 大声作業（しなさい）、チームメンバー同士でのトレーニン グ文化の醸成 7 自分が大切にしている Working Out Loud という考え方

8.

2. コードの品質の担保 研究における成果物は主に「論文」と「コード」 しかし，卒業生のコードが失われていたり，再現性がないのはよく見る光景... → GitHubを普段から使っておけば，こういった問題を回避できる Git/GitHubでコードを管理する方法を学ぶ Git/GitHubはソフトウェア開発において必須のツール 昨今注目を集めている Claude Code や Codex を使った開発でも必須 学生のうちから，これらを活用した開発方法を身につけましょう． 研究でGit/GitHubを使っていけば，自然とスキルが身についてきます！ 8

9.

GitHubリポジトリのルール 研究室のリポジトリテンプレートを利用する 新しくリポジトリを作るときには，研究室のテンプレートを使うのを推奨しま す．テンプレートリポジトリを開き右上の緑色の Use this template を選ぶとこ のテンプレートを使ってリポジトリを作ることができます．(研究室メンバーは以 下のリンクからリポジトリに飛べます) lab-template-python python用のテンプレート．パッケージ管理は uv で行う．デフォルトで ruff , pytest が入っている． pyproject.toml ， vscode のデバッグや保存時に ruff が自動で走る設定等がなされている． lab-template-python-devcontainer の設定がなされたpython用のテンプレート．GPUを使うプロジェ クトだと cuda をdockerで指定できて何かと便利なので，このテンプレートを推 奨．このテンプレートを使う場合はdockerの設定をしておく必要がある． devcontainer 9

10.

lab-template-matlab MATLAB用のテンプレート．MATLABのProject機能を使うようにしており，Pathの 設定が楽になる． 外部の方へ 研究室で使っている上記のプライベートリポジトリのテンプレートとほぼ同じも のを，外部に向けて公開しています． lab-template-python-public lab-template-python-devcontainer-public lab-template-matlab-public 10

11.

リポジトリ名は小文字+ハイフン区切りで統一する 理由としては，リポジトリのURLが読みやすくなるためです． Google Search CentralはURL中の単語区切りとしてアンダースコアではなくハイフ ンを推奨しています． 参考：ハイフンなの!?アンダースコアなの!? ただし，pythonのパッケージ名は snake_case とするようにしましょう． 例を挙げると，以下のようにしましょう: GitHubリポジトリ名: lab-code-guide pyproject.toml のproject名: lab-code-guide package名（srcレイアウトで使うディレクトリ名）: lab_code_guide リポジトリはprivateにする 研究のコードは論文がオープンになってから公開しましょう． public にしてし まうと誰でもプロジェクトの中身が見られるようになってしまいます． 11

12.

Pull Requestの設定をする 研究室ではmerge方法を「Squash merge」 とし, 「merge後は作業ブランチを削除」 する運用にしています．この運用のために 以下の設定を行います． 設定手順 1. 自分のリポジトリをGitHubで開き， Settings → General を開く 2. Pull Requests の項目で， Allow merge commits と Allow rebase merging のチェックを外し， Allow squash merging にチェックを入れる 3. Automatically delete head branches にチェックを入れる 12

13.

main への直接pushを禁止する 研究室では GitHub flow に基づいた開発を行うので， main への直接pushを禁止 しています．これは， main を常にバグのない綺麗な状態に保つためです． (GitHub OrganizationのTeam planへの加入が必須．教育機関は申請すれば無料) 設定手順 1. 自分のリポジトリをGitHubで開き， Settings → Rules → Rulesets で右上 の緑のボタンの New ruleset をクリックし New branch ruleset を選ぶ 2. Ruleset Nameを protect_main とします 3. Enforcement status をActiveにします． 4. Target branchesで Add target で include default branch を追加する （これで main ブランチが対象となる）． 5. Branch rules で Restrict deletions と， Require a pull request before merging ， Block force pushes をチェックを入れる．ただし， Require a pull request before merging で Required approvals は0にす る（approvalの強制をするとそれがボトルネックになってしまうため）． 13

14.

GitHub flowで開発を進める 研究室ではGitHub flowに基づいて実装を行います． 1. Issueを作成する 実装をするときにはまずissueを作成します．これは作業を明確化したり，作業内 容を整理するのに役立ちます．また作業を追跡しやすくもなります． Issueの作成手順: 作業するリポジトリの Issues から New issue をクリック 14

15.

表示されるissueのテンプレートから作業内容に沿ったものを選んで記入する 実装 [IMPL]：機能の追加や修正，リファクタリングするときはこれを選ぶ 実験 [EXP]：性能評価や可視化をする時にはこれを選ぶ スパイク [SPIKE]：実装に必要な文献の調査や試作を行う バグ報告 [BUG]：直さないといけないバグを見つけたときに選ぶ ドキュメント [DOCS]：まとまったドキュメンテーションを行う時に選ぶ Issueのタイトル Issueのタイトルは[上記のテンプレートのラベル] 作業内容としてください． 例えば [IMPL] 計測データの読み込みの実装 [EXP] CNNベースの手法の計測データに対する性能評価 Issueの規模 Issueは最大でも1週間で終わる作業内容にしましょう．それ以上かかるタスクで あれば，issueを分割しましょう． 15

16.

補足: Issueテンプレートについて Issueのテンプレートは .github リポジトリの .github/ISSUE_TEMPLATE で設 定することで，Organization全体のリポジトリでIssueのテンプレートが使え るようになっています． （ .github リポジトリはpublicにしないと設定は反映されないはず） 個別のリポジトリに .github/ISSUE_TEMPLATE を置くと，Organizationの設定 よりもリポジトリ内の設定が優先される仕様です． 16

17.

2. ブランチを作成する 先ほど作ったIssueを開くと右側に Create a branch for this issue or link a pull request をクリックするとブランチを作成できます． ブランチの命名規則 作業ブランチは次の形式に統一します <type>/<issue-number>-<short-title> : issueでつけたラベル impl , exp , spike , bug , docs <issue-number> : デフォルトのブランチ名に入っている数字がIssue number <short-title> : 作業内容を英語で短く書く 例： <type> impl/1-add-ptycho-loader exp/12-ablation-cnn-classification 17

18.

からブランチを作 成すると，GitHub上でブランチが作成される．その際，以下のようなコマンドが 表示されるので，ローカルリポジトリのターミナルで実行し，ローカルリポジト リにブランチを同期させる． Create a branch for this issue or link a pull request git fetch origin git checkout <branch-name> 18

19.

3. 作成したブランチで作業を進める Issueで記述した内容について実装を進めていきます．ここで大事なのが， Issueに記述した実装のみを行い，スコープ外の項目に関して実装はしない ことです．これが守られないと以下の不都合が生じます Issue (やるべき作業の定義)，ブランチ（そのIssueを実装する場所），Pull Request (そのIssueがどう解決されたか)の対応が崩れる やるべき作業のテスト等がおろそかになる レビュー負荷が上がる．どこが本来の目的の実装が不明瞭になる バグ発生時の切り戻しが難しくなる なので， 1つのブランチ / PR では，原則として対応する Issue に明記されたスコープだけを 扱う．追加作業が必要になった場合は，Issue を更新するか，別 Issue・別ブラン チに分ける ことを徹底してください． 19

20.

コミットについて 研究室でのGitHub flowでは，Squash mergeをすることをルールとしています． ( main の履歴をsquash merge 後の PR 単位で管理したいため) なので，コミットは厳密に美しく保つ必要はないですが，少なくとも作業内容が 分かるメッセージを付けるようにしましょう． 以下のようなコミットメッセージをつけることを推奨します． feat: add load function ( feat は機能追加を表す) chore: fix typos ( chore は軽微な修正を表す) wip: implement baseline ( wip は作業途中 (work in progress)を表す) fix: shape bug ( fix はバグ修正を表す) docs: add readme for experiments ( docs はドキュメントの変更を表す) test: test_load_data ( test はテストコードの追加を表す) 参考: semantic commit messages 参考: Commit Message Format 20

21.

補足：実装・検証していらないとわかった機能をどうするか？ 例えば，「性能向上すると思って実装した前処理手法が全然意味がなかった」とい うことが研究ではよく起こります．このような場合，その機能は main にマージ しない方が良いです．今後使わない機能が main に紛れこむと，他の人がコード を読むときに混乱してしまいます．ですが，PRやIssueに知見は残しましょう． その機能を採用しないと判断をしたら， 1. Pull Request (PR) とIssueに結果を記録する 2. 必要ならtagを打つ 3. PRをmergeせずにcloseする 4. branchを削除する 手順が多いので，詳細はこちらを参照してください． 21

22.

4. Pull requestを作成する 実装とテストが完了したら，Pull Request (PR) を作成しましょう． リポジトリの Pull requests → New pull request から作成できます． PRのテンプレートを設定しているので，書かれている項目を記載しましょう． 研究室のPRテンプレート PRのタイトルの命名規則 PRのタイトルは以下の形式で統一します: <type>(<scope>): <summary> : issueでつけたラベル impl , exp , spike , bug , docs と同じものを選ぶ <scope> : 作業の中心となるスコープを書く <summary> : merge後に何が追加されるのかを書く 例： <type> impl(data): add data loader of measured data exp(synthetic_data): experiments sparse regularization 22

23.

PRの記載に関する注意事項 作業内容の種別を「実装」か「実験」を選んで，それに紐づく入力項目を記 載しましょう． PR内で Fixes #<issue-number> を記載しておくと，mergeされたタイミング で自動で対象のissueがcloseされます．なので，「関連Issue」の項目で <issue-number> を忘れずに記載しましょう． セルフチェックをして，記載事項が守れているかを確認しましょう． 23

24.

(補足) Draft pull requestについて ブランチで作業しているときに，まだ作業は完了してい ないけどPRを出して，他のメンバーや教員に意見を聞き たい場合があると思います．その時はdraft pull request を出しましょう． Draft Pull Request Draft PRは通常のPRと違って，作業途中に出すPRです． Draft PRの場合，mergeができないようになっており， CODEOWNERS による自動レビュー依頼もでません． 参考: ドラフトプルリクエスト 作成方法 通常のPRと作成方法は同じで，緑のボタンをプルダウン して Create draft pull request を選べば，Draft PRが 作られます． 24

25.

5. コードレビューを受ける コードレビューに関しては，あとでまとめて説明をします． 25

26.

6. main へmergeする コードレビューも完了したら， main へmergeしましょう．Pull Requestの設定で したように，merge方法は squash merge になっています．また，merge後は自動 で作業ブランチが削除されます． mergeの手順 1. 対象のpull requestを開く 2. コードレビューに対応したことを確認する 3. 下の方にある緑色のボタン Squash and merge をクリックする 4. Commit message はPRタイトルと同じにし， Extended description は原則 空白のままで良いです．必要であれば1-3行の短い補足を書きます． 5. merge 後は自動で作業ブランチが削除されます． マージ後にブランチを自動で消す設定にしているのは，ブランチが残っていると どれがアクティブなブランチなのかわかりにくくなるためです． 26

27.

ここまでで研究室のGitHub flowの1サイクルが完了です．この 1-6の手順を繰り返していくことで，実装を進めていきます． 実装の流れのおさらい 1. Issueを作成する 2. ブランチを作成する 3. 作成したブランチで作業を進める 4. Pull requestを作成する 5. コードレビューを受ける 6. main へmergeする 27

28.

コードレビューについて 28

29.

コードレビューの意図 研究室に入ったばかりの学生は，研究においてどうプログラムを書いていけば良 いかわからず，よく知られたアンチパターンを踏んでしまいがちです（山田もそ うでした）．コードレビューが受けられる環境だと，研究の手戻りが発生しにくく なったり，コードの再現性も保たれやすくなります． コードレビューを阻む壁 レビュー可能なメンバーの不足: 企業だとシニアエンジニア等がレビューを担当し てくれますが，うちの研究室だと人手が足りません（ビッグラボなら可能?） レビューがボトルネック化: コードレビューを待っている時間がボトルネックにな ってしまいます．1人のPIが全メンバーのコードレビューを担うのは非現実的です し，コードレビューが遅れると形骸化しそうです → AIによるレビュー + 教員によるレビューのハイブリッドで運用します 29

30.

コードレビューの運用方法 GitHub Copilotによるレビュー Pull requestでreviewerとしてCopilotを割り当てることができま す．最近のAIレビューの進歩はすごいので，十分良い精度でレ ビューを行ってくれます．Mergeを行う前にPull requestで copilotに必ずレビューしてもらいましょう． Pull requestでCopilotをReviewerに割り当てる Pull requestの画面右あたりに Reviewers というセクションが あるので，そこでCopilotを割り当てるとコードレビューが利 用できるようになります． 参考：GitHub Copilot を使ったコードレビュー 30

31.

(補足) Copilotによる自動コードレビューをする設定 ブランチに直接pushを禁止する設定 protect_main の中に， Automatically request Copilot code review という項目があるので，これを チェックするとそのリポジトリではpull requestが作られると自動でcopilotによる レビューが実行されます． 参考: Configuring automatic code review for a single repository main GitHub Copilotの仕様 GitHubのProプランでGitHub Copilotのレビューを利用できます．1回のレビューご とにPremium rquestを1つ消費します．これは，GitHub Organizationではなく，個 人のアカウントに対してPremium rquestが消費されます．Premium rquestは月あた り300あるので，レビューを利用しすぎなければ十分足ります．GitHubのProプラ ンはGitHub Educationで申請すれば学生・教員は無料で使えます． (2026年3月の情報です) 参考: About GitHub Copilot code review 31

32.

(補足) GitHubのBudgetについて GitHub Copilotにお願いしすぎてPremium rquestを使い切っても，Budgetが正しく 設定されていれば追加請求されることはありません．自分のGithubアカウントの settings → Billing and licensing → Budgets and alerts のところで，以下 のように全ての項目のbudgetが0になっていたら追加請求されることは無いです． デフォルトではbudgetが0円になっているはずですが，確認しておきましょう． 32

33.

Copilotのレビューをカスタマイズする を設定することで，コードレビューに関してコンテキ ストを与えることができます． custom instruction file リポジトリ単位で custom instruction を設定する リポジトリ内に .github/copilot-instructions.md 作り，その中で指示を記載 することで，copilotにコンテキストを与えることができます．さら に .github/instructions ディレクトリを作り，その中に path-specific custom instructions を設定可能です．この機能を使うと， python に対する指 示や MATLAB に対する指示を個別に設定可能です．また， excludeAgent を活用す ることで，コードレビューのみで適用されるコンテキストも与えることが可能． 注意: Copilot code reviewでは， custom instruction file の最初の4000文字ま でしか読んでくれないので，4000字以内で記載しましょう． 参考: Customizing Copilot's reviews with custom instructions 33

34.

研究室で現在使っている custom instructions 以下を参照してください（リンクから飛べます）．使っていくうちにコードレビュ ーをカスタマイズしたくなったら，各自のリポジトリで自分用にカスタマイズし ていってください．( lab-template のリポジトリでは以下の設定がデフォルトで 入ってます) .github/copilot-instructions.md .github/instructions/code-review.instructions.md .github/instructions/python.instructions.md .github/instructions/matlab.instructions.md 34

35.

教員によるレビュー 教員が全メンバーの全PRにコードレビューするのは不可能なので，教員によるレ ビューを以下のタイミングで依頼してください． 1. GitHub flowを初めて実践するメンバーの最初の3回のPR 正しくGitHub flowが実行できてるか？，PRの粒度は適切か？ などをチェックし，フィードバックするためです． 2. 研究対象とする課題のベースライン手法の実装を完了したとき 研究では，まず対象とするタスクに対して，ベースラインとなる手法の実装に取 り組むことが多いです．例えば，X線ナノイメージングにおける位相回復では， 「計測データの読み込み」，「変数・アルゴリズムの初期化」，「ベースラインとな る位相回復手法」，「可視化」，「性能評価」を実装する必要があり，これら一連の パイプラインを実装してようやく提案手法の検証等を行えるようになります．こ の一連のパイプラインが完成したタイミングでコードレビューを行うことで，致 命的な勘違いや実装ミスがないかをチェックし，どうモジュール化していけば良 いかをフィードバックします． 35

36.

3. 提案手法がおおよそ固まり，本格的に論文に載せる実験を開始するとき 論文に載せる実験は特に再現性を担保することが重要なので，本格的に実験を開 始するときにコードレビューを行います．以下の項目について確認し，フィード バックします． 実験設定がconfig化されているか？ 実験の再現に必要な情報が保存されているか？ 必要な中間ファイル等が保存されているか？ trainなどのメインの処理と図の作成のプログラムが分離されているか？ もちろん上記以外のタイミングでもレビューして欲しい内容があれば，PR やdraft PRを出して，slackの #実装関連 に連絡してくれれば対応します！ 36

37.

レビューのお作法 Reviewer (レビューする人) 人ではなくコード/設計/再現性にコメントしましょう．攻撃的なコメントは 絶対NGです (当然，教員もこのルールを守ります)． 指摘は「理由＋提案」をセットで書きましょう． コメントに対してラベルをつけましょう．(後述します) Reviewee (レビューを受ける人) Pull requestを出す前にちゃんとセルフレビューをしましょう． レビューコメントを受け入れる場合には，忘れずちゃんと対応しましょう． 対応が完了したら，レビューコメントに対して「修正しました」等のメッセ ージを入れることで忘れづらくはなると思います． レビューコメントを受け入れない場合には，レビューコメントに対して自分 の考えをコメントしましょう．このときも攻撃的なコメントは絶対NGです． 37

38.

レビューコメントのラベル化 レビューコメントにラベルをつけることで，重要度・優先順位が伝わりやすくな ります．(参考：CyberAgent AI Lab研修 / Code Review in a Team) must : 必須．修正のアクションが必要です． ask : 質問．回答のアクションが必要です． imo : 提案．個人的な見解や提案です． nits : 軽微な指摘．typoなどの軽微な指摘です． fyi : 参考情報．参考までに情報を共有します． ラベルを Saved replies に設定する これらのラベルをGitHubの Saved replies に登録すると，レビューコメントをす るときに便利です．設定方法はこちらにまとめています．Reviewerを担当する人 は登録しておきましょう！ 38

39.

レビューの観点 Google's Engineering Practices documentation 日本語訳より引用 設計: コードはうまく設計され、そのシステムにとって適切か？ 機能性: コードは作成者の意図通りに動作するか？ユーザーにとってコードの 挙動は適切か？ 複雑さ: コードはもっとシンプルにできるか？コードを作成した開発者があと になってもう一度そのコードに触れたとき、理解しやすく使いやすいか？ テスト: そのコードには、正確で、うまく設計され、自動化されたテストがあ るか？ 命名: 変数名、クラス名、メソッド名などに明解な名前を選んだか？ コメント: コメントは明解で有益か？ スタイル: コードはスタイルガイドに準拠しているか？ ドキュメント: 関連するドキュメントも更新してあるか？ 39

40.

コードレビューのまとめ 毎回のPull requestでGitHub Copilotによるレビューを受ける へmergeする前に必ずCopilotによるレビューを受ける custom instractions を設定し，コンテキストを与える main 教員によるレビューは以下のタイミングで必ず受ける GitHub flowを初めて実践するメンバーの最初の3回のPR 研究対象とする課題のベースライン手法の実装を完了したとき 提案手法がおおよそ固まり，本格的に論文に載せる実験を開始するとき 40

41.

ディレクトリ構造を整理する 41

42.

ディレクトリ構造を整理しよう 研究を始めたての学生が踏むアンチパターンの一つが，ディレクトリ構造を整理 せずに，全てのコードを一つのディレクトリにまとめてしまうことです．ディレ クトリをきちんと整理することは可読性や再現性にも直結します． ここでは，pythonとMATLABを使う研究プロジェクトのディレクトリ構造を説明 します． 42

43.

Pythonプロジェクトのディレクトリ構造 Pythonのプロジェクトでは以下のディレクトリ構造を使います． lab-templatepython のテンプレートリポジトリではこのディレクトリ構造を採用しています． project/ ├── .gitignore ├── .python-version ├── README.md ├── pyproject.toml ├── uv.lock ├── configs/ ├── data/ ├── docs/ ├── models/ ├── outputs/ ├── scripts/ ├── src/ └── tests/ # Gitの管理から外すファイル・ディレクトリを設定 # uvが生成するPythonバージョン情報 # プロジェクト概要 # Pythonパッケージ設定 # uvが生成する依存関係ロックファイル # configファイルを保存 # データセットを保存 # ドキュメントや実験ノートを保存 # 保存した学習済みモデルを保存 # 実験結果を保存 # 実行スクリプトを保存 # 自作の関数やクラスを保存 # テストコードを保存 43

44.

configs ディレクトリ 実験を行うときにはスクリプト内にハイパーパラメータをハードコードするのは NGです．configファイルからハイパーパラメータを読み込むのを基本としましょ う． configs/ はこのconfigファイルを保存するためのディレクトリです． configファイルをどう使うのが良いのかについては機械学習プロジェクトにおけ る実験管理を読みましょう． 山田はconfigファイルを読み込むのに omegaconf を使っていますが，各々好きな ものを使って構いません． 44

45.

data ディレクトリ このフォルダには実データを配置します．ここには容量の大きいデータを置くこ とが想定されているので .gitignore でGitの管理からはずしておきましょう．ま た，以下のようにサブディレクトリに分けておくのも良いでしょう． data/ ├── raw/ ├── processed/ ├── simulation/ # データセット # 生データ (未処理) # 前処理済みデータ # シミュレーションデータ 45

46.

docs ディレクトリ このプロジェクトに関するドキュメント，実験ノートを配置します．実験ノート のテンプレートは以下を使うのが良いでしょう． # 実験：<実験タイトル> - GitHub Issue Number: `#<Issue No.>` - Config: `configs/xxxx.yaml` - Command: `uv run python <実行ファイル名>` - Outputs: `<実験結果の出力先のpath>` - Notes: GPU=..., dataset version=... 問い・仮説 ## 実験内容 ## わかったこと ## 次に検証すべきこと (あれば書く) ## また，gitで管理できないのでドキュメントを作るのにwordを使うのはやめましょ う．基本markdownで良いです． 46

47.

models ディレクトリ 学習済みのモデルはこのディレクトリに置きます．機械学習のモデルは基本容量 が大きいので， .gitignore でGitの管理から外しておきましょう．機械学習モデ ルを扱わないプロジェクトなら，このディレクトリは削除してしまっても良いで す． outputs ディレクトリ プログラムを実行して得られるログ・実験結果を保存するディレクトリです．こ れも .gitignore でGitの管理から外しておきましょう．また，以下のように研究 段階に応じて出力の保存先を分けておくと後々参照しやすくなります． ├── outputs/ │ ├── explore/ │ ├── paper/ │ └── tuning/ # 実験結果（git管理しない） # 試行錯誤・デバッグといった探索段階の実験の出力先 # 論文に載せる実験の出力先 # チューニング用 また，上記以外のディレクトリ以外にも，卒論に載せる実験用のディレクトリ (例: bachelor_thesis ) などを作ったり，学会原稿に載せる実験用のディレクト 47 リ(例: sips2026 ) などを作ると良いです．

48.

scripts ディレクトリ エントリポイント (プログラムが実行される際に最初に処理が開始されるコードの こと) となるスクリプトをここに置きます．つまり， uv run python scripts/<実 行するスクリプト>.py のように呼ぶためのファイル群を scripts/ に置きます． 注意すること 再利用したい処理やロジックは関数化・クラス化して src/ に置き， scripts/ からそれらを呼ぶ形にしましょう scriptsで利用するハイパーパラメータや設定等はハードコーディングせず， configs/ にあるconfigファイルを読み込み実行するようにしましょう 48

49.

の第1階層は処理の種類で分けておくのがおすすめです．以下はあくま で一例です． scripts/ scripts/ ├── data/ │ ├── build_dataset.py │ └── simulate_gmrl.py ├── training/ │ ├── train_gnn.py │ └── resume_training.py ├── evaluation/ │ ├── eval_checkpoint.py │ └── benchmark_baselines.py ├── plots/ │ ├── plot_main_results.py │ └── make_ablation_table.py ├── experiments/ │ ├── exp01_baseline/ │ │ ├── run.py │ │ ├── sweep.py │ │ └── README.md │ └── exp02_robustness/ │ ├── run.py │ └── README.md └── tools/ ├── inspect_dataset.py ├── migrate_config.py └── clean_outputs.py # データ生成・前処理用のスクリプト # 学習用のスクリプト # 評価用のスクリプト # 可視化用のスクリプト # 実験用のスクリプト # ユーティリティ用のスクリプト 49

50.

src ディレクトリ 自作のライブラリ（関数やクラス等）を置くためのディレクトリです．以下のよ うな src レイアウトを採用することが多いです．（参考：src レイアウト対フラッ トレイアウト） 以下の my_project の構造はあくまで一例です． ├── src/ │ └── my_project/ │ ├── data/ │ ├── models/ │ ├── training/ │ ├── evaluation/ │ └── utils/ # データ処理用スクリプト # モデルの定義 # 学習関連スクリプト # 評価関連スクリプト # 汎用関数 で --lib オプションをつけると， src レイアウトでプロジェクトを初 期化してくれます (uv公式: Creating projects)．ここで， my_project の部分がライ ブラリ名に対応します．詳しくは過去の uv の講義資料を参考にしましょう． uv init 50

51.

tests ディレクトリ テストコードを置くディレクトリです． pytest については過去の講義資料を参考 にしましょう． その他のディレクトリ : pythonの仮想環境で作られるディレクトリ．Gitで管理しないように 気を付ける． .github/ : copilot のcustom instructionsを置いたり，issue templateを置 く．研究室のgithub organizationではすでにissue，PRのテンプレートが設定 されているので，それを上書きする必要があれば設定する． .vscode/ : vscode のデバッグ設定等を置く .devcontainer/ : devcontainer を使う場合はここに設定ファイルを置く． .venv/ 51

52.

MATLABプロジェクトのディレクトリ構造 MATLABのプロジェクトでは以下のディレクトリ構造を使います． labtemplate-matlab のテンプレートリポジトリではこのディレクトリ構造を採用し ています． project/ ├── .gitignore ├── README.md ├── configs/ ├── data/ ├── docs/ ├── models/ ├── outputs/ ├── resources/ ├── scripts/ ├── src/ └── tests/ # Gitの管理から外すファイル・ディレクトリを設定 # プロジェクト概要 # configファイルを保存 # データセットを保存 # ドキュメントや実験ノートを保存 # 保存した学習済みモデルを保存 # 実験結果を保存 # MATLABのプロジェクト定義ファイルが保存される # 実行スクリプトを保存 # 自作の関数やクラスを保存 # テストコードを保存 Pythonとほぼ同じなので，注意が必要な部分だけ説明します． 52

53.

configs/ ディレクトリ MATLABでは，pythonのようにconfigファイルから設定を読み込んで実験を行うと いう機能がそこまで充実していません．基本的には，設定ファイルを json で書 いて，MATLABの jsoncode で読み込むという運用になるかと思います．もしく は，configを構造体で記述し，それを返す関数をconfigとして扱うという運用でも 良いかもしれません． MATLABでhydra.utils.instantiateを使ったconfig管理をある程度再現する方法につ いては，リポジトリexample-config-matlabを参考にしてください． 53

54.

resources/ ディレクトリ MATLABの project 機能を使うと勝手に作られるディレクトリです．この中に は，プロジェクト定義ファイルが格納されます．このディレクトリはちゃんとgit で管理しましょう． MATLABの project を使う検索パスと依存関係を管理することができます． addpath とかを 書かなくてよくなるので，結構便利です．また，どのMATLABのtoolboxに依存し ているかもすぐにわかるようになったり，自作の関数名を変えたくなった時に一 括で変えることができたりします． 参考: プロジェクトの作成 参考: プロジェクトファイルの管理 project 54

55.

tests ディレクトリ このディレクトリにはテストコードを置きます．MATLABのテストコードの書き方 は以下を参考にしましょう． pytest でできることは大抵MATLABでもできると思 います．色々と書き方はありますが，クラスベースのユニットテストがおすすめで す． pytest の使い方がわかっていれば，なんとなくでも使えると思います． MATLAB公式のテストコードに関するドキュメント とりあえず，ユニットテストの記述のドキュメントを読めば使い方はわかると思 います．特に役に立つドキュメントを以下にまとめて置きます． クラスベースのユニットテスト 検証、アサーション、その他の検定の表 クラスを使用するセットアップ コードと破棄コードの記述 クラスベースのテストでのパラメーターの使用 55

56.

まとめ このコーディングガイドラインを守って実装を進めていけば，ある程度品質が保 たれたコードを書けると思います．結構たくさんルールを書いたので，見落とし てしまうかもしれませんが，特に研究を始めたてのときはルールを厳守しつつ実 装を進めることを意識してみてください． 56