AGENTS.md git:20261018.cb61b8aA

Immutable. This exact content never changes and is served at /api/v1/blob/bb887aff2076c76d.

# AGENTS.md

Crane は RoboCup SSL 向けの ROS 2 Jazzy / C++20 フレームワークです。

## 作業の入口

- [環境構築・起動](docs/setup.md)、[開発・テスト手順](docs/tools.md)、[開発規約](CONTRIBUTING.md)を参照する。
- 設計・運用上の注意は[文書索引](docs/index.md)から確認する。実装・設定の正本はソースコード。
- ロボット全体の仕様（パケット・ポート・停止判定・cm4-sim）の正本は `specs/`（[ibis-ssl/specs](https://github.com/ibis-ssl/specs) のサブモジュール）。Crane の文書に仕様を書き写さずリンクする。
- プロジェクトコンテキストは `docs/agent-context/`、なければ明示的な context-link を参照する。private context の内容を公開文書へ無断転載しない。

## 必須制約

- colcon は `src/` のある **ROS ワークスペースのルート**で実行する。リポジトリ内に `build/`・`install/`・`log/` を作らない。
- ビルド後はワークスペースの `install/local_setup.bash` を読み込む。
- 既存の ament_cmake_auto / make ベースのビルドを維持する。
- 制御周期、座標・単位、通信タイミングを変更するときは、呼び出し側と実機への影響を確認する。
- `robot_packet.h` の変更は Crane / Orion_CM4 / G474 の互換性確認と同期、各ビルド、統合通信テストが必要。[通信の変更手順](docs/network.md#通信仕様を変更するとき)と [specs の一致検査](https://github.com/ibis-ssl/specs/blob/main/common/control_packet.md#正本と一致検査)を参照する。
- シミュレーションと実機のネットワーク設定を混同しない。[ネットワーク設定](docs/network.md)を確認する。
- バージョン番号を手動変更しない。リリースは GitHub Actions が管理する。
- 既存の未コミット変更を保護し、生成物・IDE設定・秘密情報をコミットしない。コミット前にステージ対象と必要な検証結果を確認する。

## 文書を変更するとき

- 手順、設計理由、守るべき制約を簡潔に残す。API・設定値・依存関係の一覧はソースへリンクする。
- 同じ説明は一か所に置く。実装の転載、進捗や成熟度の記述、裏付けのない性能表現を増やさない。
- `docs/` は別リポジトリへ同期される。文書間は相対リンク、コードへの参照は GitHub の `develop` 上の具体的なファイル・ディレクトリへのリンクを使う。