aim-common-rules

UNNC AIM Team — リポジトリとコードの標準

このスキルは、チームの標準を参照する単一のエントリーポイントです。組織リポジトリ unnc-aim/.github の profile/ にある文書化されたルールを集約し、実際に適用できる形にしています。

• リポジトリの命名／ブランチ／コミットのルール ← profile/README.md
• C++ 標準 ← profile/standard.cpp.md
• Python 標準 ← profile/standard.py.md
• TypeScript／Go／CMake 標準 ← profile/standard.ts.md ／ standard.go.md ／ standard.cmake.md
• ドキュメントのスタイル（Markdown／YAML／JSON）← profile/standard.docs.md

これらの文書が引き続き唯一の信頼できる情報源です。このスキル（unnc-aim/aim-common-agentic-skills にあります）は、文書を実行可能なチェックリストと、そのままコピーして使えるルールファイル（assets/）にまとめています。

**生成物の言語ルール：**ドキュメントの文章は言語を問いませんが、すべてのコード、コードコメント、コミットメッセージはアメリカ英語で記述する必要があります（例：colour、behaviour、optimise ではなく color、behavior、optimize）。

参照先

作業	参照先	コピーするファイル
リポジトリの作成／命名、ROS2 パッケージ名の検証	references/repo-naming.md	—
競技用 ワークスペース（git サブモジュール）のクローンと整理	references/workspace-organization.md	—
ブランチの作成、コミットメッセージの作成、エージェントの git 安全ルールの遵守、推奨する git config の設定	references/git-workflow.md	assets/.gitattributes
Python のフォーマット／設定	references/python-formatting.md	assets/setup.cfg
C++ のフォーマット／設定	references/cpp-formatting.md	assets/.clang-format + assets/.clang-tidy
TypeScript のフォーマット／設定（Prettier、ESLint、pnpm）	references/ts-formatting.md	assets/.prettierrc + assets/eslint.config.js
Go のフォーマット	references/go-formatting.md	—
CMakeLists.txt のスタイル	references/cmake-style.md	—
Markdown／YAML／JSON のスタイル（.editorconfig）	references/docs-style.md	assets/.editorconfig
VS Code のセットアップ（拡張機能、Pylance、保存時のフォーマット、スペルチェック）	references/python-formatting.md §3、§5、§6 + profile/README.md §1.6	assets/.vscode/extensions.json + assets/.vscode/settings.json

命名クイックリファレンス（最もよく使う形式 — まずはこちらをお読みください）

リポジトリの種類	パターン	区切り文字	例
競技会（1年／1試合／1台のロボット）	[2-digit year][match abbr]_[robot (optional)]_[package]	アンダースコア _	26RC_R2_controller、26RC_interfaces、26UL_Sentry_ws
内部／学年度（競技会以外）	aim-[4-digit year]-[package]（長期利用のライブラリでは年を省略する場合があります）	ハイフン -	aim-2526-py-coursework、aim-rookie-courses
外部／再利用可能／ライブラリ	BrandingRepo または package_name	任意	RoboMark、ros2_hik_camera

• 年／試合のトークン：26RC = 2026年のRobocon、25RM = 2025年のRoboMaster、2526 = 2025〜2026年度（aim-* 内のみ）。
• セグメントの大文字・小文字の使い分け： 2桁の年（26）；試合の略称はすべて大文字（RC／UC／UL）；ロボット名がある場合は、間に区切りを入れないPascalCase（Sentry、NormalHero、R1）；パッケージのセグメントは小文字の snake_case。
• ROS2パッケージ名との一貫性： リポジトリが単一のROSパッケージの場合、package.xml の <name> はリポジトリ名の「package」セグメントと一致させる必要があります。ros2_ のような接頭辞は通常、<name> では省略します（例：ros2_hik_camera → <name>hik_camera</name>）。
• デフォルトブランチは常に main です（master は使用しません）。競技会用／安定版のリポジトリでは main に直接プッシュせず、Pull Requestを使用してください。

詳細なルール、判断フロー、既知の不整合については、references/repo-naming.md を参照してください。

コミットメッセージのクイックリファレンス（Conventional Commits）

<type>(<scope>): <subject>
<blank line>
<body>           # optional, wrap at <=72 chars
<blank line>
<footer>         # optional: BREAKING CHANGE: ... / Closes #123

type ∈ feat | fix | docs | style | refactor | test | chore | perf | ci | build；subject は50文字以内で、命令形とし、最初の文字は小文字、末尾に句読点を付けません。詳細：references/git-workflow.md。

エージェントのルール： 現在のタスクでユーザーから明示的に依頼されない限り、git commit／git push を実行しないでください。明示的な許可なしに書き込みを伴う gh コマンドを実行しないでください（gh pr view／gh run list などの読み取り専用サブコマンドは制限なく実行できます）。コミットにAIの Co-Authored-By: トレーラーを追加しないでください。また、コードを変更するタスクの後にはコミットせず、コミットメッセージを提案してください。メッセージは1行で、typeの接頭辞を含めて50文字以内のアメリカ英語にしてください。詳細は references/git-workflow.md §5 を参照してください。

コミッターはあなたです。AIを使うかどうかは関係ありません： AIが正しく行ったことへの評価も、誤ったことへの責任も、どちらもユーザーであるあなたに帰属します。そのため、差分を確認して、AIの共同作成者トレーラーを付けずに自分でコミットしてください。ポリシー：references/git-workflow.md §0。

メンバーがこのスキルを導入する方法

このスキルは unnc-aim/aim-common-agentic-skills にあります。オープンな skills CLI（npx skills）を使ってインストールします。この CLI はすべてのローカルエージェント（Claude Code / Cursor / Codex / …）を自動検出し、すべてのエージェント向けにスキルディレクトリ全体をインストールします。

npx skills add unnc-aim/aim-common-agentic-skills --skill aim-common-rules -g

• -g を付けるとグローバルにインストールされます（開くすべてのプロジェクトで利用できます。個人利用におすすめです）。-g を省略すると、現在のプロジェクトの .agents/skills/ にインストールされます（コンペティション／共同作業のリポジトリにおすすめです。チーム全員がクローン時に取得できるよう、コミットしてください）。
• 後から npx skills update で更新できます。

手動でコピーする場合は、スキルディレクトリ全体を ~/.claude/skills/（グローバル）または <your-repo>/.claude/skills/（リポジトリごと）に cp -R でコピーしてください。ディレクトリ（SKILL.md + references/ + assets/）は、まとめて移動する必要があります。

AI を使うかどうかにかかわらず、書式設定の標準ルールファイルをリポジトリのルートにコピーしてコミットし、全員のエディターと CI で設定を統一してください。

言語	コピー先	コピー元
C++	.clang-format と .clang-tidy	assets/.clang-format, assets/.clang-tidy
Python	setup.cfg の [flake8] / [autopep8] / [isort] セクション（既存の ROS [develop] / [install] を上書きせず、マージしてください）	assets/setup.cfg

AI を使わないメンバーは、references/*.md を読み、assets/ をコピーするだけで構いません。Claude Code は不要です。

リポジトリのセットアップ — エディター設定を先回りして提案する

リポジトリの作成やセットアップを支援するとき（新規プロジェクト、または既存プロジェクトのオンボーディング）、リポジトリを開く全員が同じ拡張機能、書式設定、スペルチェックの基準を使えるよう、チームの VS Code 設定を .vscode/ に追加することを先回りして提案してください。テンプレート：assets/.vscode/extensions.json + assets/.vscode/settings.json。

• 必ず最初に確認してください。 たとえば 「チームのエディター設定を含む .vscode/extensions.json + .vscode/settings.json を追加しましょうか？」 と提案し、確認を得てからファイルを書き込んでください。ユーザーのリポジトリに黙ってファイルを作成してはいけません。
• 上書きせずにマージしてください。 .vscode/extensions.json または .vscode/settings.json がすでに存在する場合は、置き換えずに手動でマージしてください（不足している拡張機能 ID を recommendations に追加し、不足している設定／cSpell.words を追記します）。
• ローカルにだけインストールする方法もあります。 ユーザーがファイルのコミットを望まない場合は、確認を得たうえで拡張機能ごとに code --install-extension <id> を実行するか、profile/README.md §1.6 のリストを案内してください。
• スペルチェック（Code Spell Checker）。 cSpell が単語を指摘した場合は、まず実際の誤字かどうかを確認してください。アメリカ英語で正しく綴られた用語（チーム／分野の専門用語、頭字語、固有名詞）であれば、.vscode/settings.json の cSpell.words 配列に追加してください。スペルチェッカーを無効にしたり、実際の誤字をそのままにしたりしないでください。

settings.json には、保存時の自動書式設定、isort、Pylance の設定も含まれています（references/python-formatting.md §3 / §5 / §6）。

主な注意点

• clang-format はレイアウトのみを整え、命名規則は適用しません。 C++ の命名規則（関数は snake_case ／変数は camelBack ／クラスは PascalCase ／マクロと定数は UPPER_CASE ／構造体は _t）は、コードレビューまたは提供されている .clang-tidy によって適用されます。references/cpp-formatting.md を参照してください。
• ベンダーとして取り込まれている ros2_hik_camera/.clang-tidy は変数に lower_case を使っており、記載されている standard.cpp.md（camelBack）と競合しています。新しいリポジトリでは記載されている標準に従います。チームで整合性を取る必要があります。詳細は cpp-formatting.md を参照してください。
• Python の行の長さは 79 です（aim-py-2526-courseworks の CI で使われている autopep8 のデフォルトと一致します）。99/100 に変更すると、そのリポジトリの CI が失敗します。
• autopep8 はインポートを並べ替えません。 isort（line_length = 79。 references/python-formatting.md §5 を参照してください）で並べ替え、autopep8 より先に実行してください。aim-py-2526-courseworks の CI では autopep8 のみを実行するため、isort の追加は推奨されていますが、現時点では必須ではありません。
• standard.cpp.md の例ではインデントに 4 スペースを使っていますが、チームで実際に使われている .clang-format（Google ベース）では 2 スペースです。.clang-format の設定が優先されます。
• 競技用ワークスペース内（*_ws、例：26RC_R2_ws）では、競技名のプレフィックスが付いたリポジトリを、プレフィックスを除いて src/ の下に git サブモジュールとして追加してください（26RC_R2_arm_controller → src/arm_controller）。プレフィックスは冗長です。ワークスペース名に年度・試合・ロボットがすでに含まれているためです。references/workspace-organization.md を参照してください。