Skip to contents

jarticr

Source: AGENTS.md

日本道路交通情報センター（JARTIC）オープンデータ「断面交通量情報（type B）」を R で読み込む R パッケージ。

本ファイルは全エージェント共通の正典で、Codex は直接、Claude Code は CLAUDE.md 1 行目の @AGENTS.md 経由で読む（CLAUDE.md は Claude Code 専用で Codex に届かない）。本ファイルは 32 KiB（32,768 バイト）を超えてはならない（Codex が警告なく打ち切る。検査は sh tools/check-instructions-size.sh と git / Claude Code の hook）。@ 記法で分割しない。R パッケージとしての規約を定める（targets パイプラインの研究プロジェクトではない）。

プロジェクト概要

  • GitHub リポジトリ: uribo/jarticr
  • pkgdown: https://uribo.github.io/jarticr/
  • 関連リポジトリ: uribo/jartic_storage（ダウンロード・parquet 変換のワークフロー。本パッケージを利用する側）
  • 公開状況: 未 CRAN。GitHub からのインストールのみ

ディレクトリ構成

jarticr/
├── DESCRIPTION        # 依存マニフェスト（renv は使わない。理由は下記）
├── NAMESPACE          # roxygen2 生成物。手で編集しない
├── R/                 # 関数定義・データドキュメント
├── man/               # roxygen2 生成物。手で編集しない
├── data/              # エクスポートするデータ（.rda）
├── data-raw/          # data/ と inst/dummy/ の生成スクリプト（.Rbuildignore 済み）
├── inst/dummy/        # テスト用の小さな固定データ（CP932）
├── tests/testthat/    # testthat（3rd edition）
├── .github/workflows/ # R-CMD-check, pkgdown
├── memory/            # プロジェクト固有知識（会話間引き継ぎ）
├── AGENTS.md          # 本ファイル（全エージェント共通の正典）
├── CLAUDE.md          # @AGENTS.md + Claude Code 固有の設定
└── .codex/config.toml # Codex の sandbox・環境変数ポリシー

.vscode/ の追跡方針: 作者のグローバル gitignore は .vscode を無視するが、本リポジトリでは .gitignore の !.vscode/ で再包含し意図的に追跡する。内容はワークフロー設定（air の formatOnSave・推奨拡張）に限り、テーマ・フォント等の個人的好みは置かない。

依存管理は renv ではなく DESCRIPTION

本リポジトリは renv を使わない。R パッケージは DESCRIPTION の Imports / Suggests が依存の正典であり、CI（r-lib/actions/setup-r-dependencies）もそこから解決する。依存を足したら DESCRIPTION に書く。renv.lock / .Rprofile を持ち込まない（research-project-template の renv 一式は、あちらが DESCRIPTION を持たない解析プロジェクトだから必要なものであって、ここでは二重管理になる）。

R コード記述

スタイル

  • tidyverse スタイルを air でフォーマット（air.toml、編集時に hook で自動実行）
  • 関数にはパッケージ名前空間プレフィックスを付ける: data.table::fread()、stringr::str_squish()
  • roxygen2 の @importFrom で宣言した関数のみ、プレフィックスなしで使ってよい
  • 変数名は英語のみ。コメント・ドキュメント・コミットメッセージは英語
  • モダン tidyverse パターンを優先し superseded パターンを避ける。ただし本パッケージの戻り値は data.table であることが公開 API の一部なので、置き換えの際は戻り値のクラスが変わらないことを必ず確認する（tidyr の関数は data.table を plain data.frame に落とす）。クラスが変わるなら破壊的変更として別途扱う

生成物を手で編集しない

NAMESPACE と man/*.Rd は roxygen2 の生成物。roxygen コメントを直したら再生成する。

Rscript -e 'roxygen2::roxygenise()'

roxygen2 8.x はバージョンを DESCRIPTION の Config/roxygen2/version に記録する（7.x までの RoxygenNote は書かれない）。再生成なしにこのフィールドだけ書き換えない（man/ の内容と食い違う）。roxygen コメントは markdown 記法で書く（Roxygen: list(markdown = TRUE)）。

データとフィクスチャ

  • data/*.rda は data-raw/DATASET.R から usethis::use_data() で生成する
  • inst/dummy/type_b.csv（10 列・現行）と inst/dummy/type_b_9col.csv（9 列・2018-02 より前）は data-raw/dummy_typeB.R から生成する。CP932 バイト列なので手で編集しない。UTF-8 で書き直すと read_jartic_traffic() の iconv(from = "cp932") が地点名を文字化けさせ、テストが無意味な値を検証する状態になる。実データに合わせてヘッダ行と CRLF を持たせてある
  • 生の JARTIC データ（都道府県別 CSV / ZIP）はコミットしない。.gitignore で除外済み

type B の配布形式（実データで確認済み）

前提を推測で書かない。以下は 2017-08 の全 51 提供元と 2026-06（徳島）の実ファイルを走査して確認した事実。

項目 2018-02 より前 2018-02 以降
ヘッダ行 あり（時刻,…,リンク終端からの距離(10m)） あり（時刻,…,リンク終端からの距離（×10m）,リンクバージョン）
列数 9（link_ver なし） 10
日時 2017/8/1 0:00:00 と 2017/08/01 00:05 が提供元ごとに混在（2017-08 は 40 : 11） 2026/06/01 00:00
改行 CRLF CRLF

ヘッダ行は全期間で存在する。fread(header = FALSE) を無条件に渡すとヘッダが観測値として混入し、現行月のファイルすら読めない（#3）。read_jartic_traffic() は先頭行の 1 行目だけを読んで「ヘッダの有無」と「列数」を判定し、skip と colClasses / col.names を切り替える。9 列期は link_ver を NA_integer_ で補い、戻り値は常に 10 列に保つ。

テスト

  • testthat 3rd edition（Config/testthat/edition: 3）
  • フィクスチャのパスは tests/testthat/helper-fixture.R の type_b_fixture() / type_b_9col_fixture() 経由で取る（system.file() を各テストに散らさない）
  • 検証は「読み込みの契約」に集中する: 列名・列の型・タイムゾーン・キー・欠測の扱い・CP932 と NFKC の正規化結果
  • to_link_end_10m が character のままであることを必ず検証する。integer に落とすと元の表記（ゼロ埋め等）が失われ、静かにデータが壊れる。なお 2017-08 / 2026-06 の実データを走査した範囲ではゼロ埋めは観測されていない。それでも character を保つのは、公開 API の型であると同時に、表記の揺れを読み込み側で潰さないため
Rscript -e 'testthat::test_local()'

共通コマンド

# ビルド・チェック（devtools 非依存）
R CMD build .
R CMD check jarticr_*.tar.gz

# ドキュメント再生成（roxygen2 が必要）
Rscript -e 'roxygen2::roxygenise()'

# フォーマット（通常は編集時 hook で自動実行される）
air format .

# フィクスチャ再生成
Rscript data-raw/dummy_typeB.R

作業時の注意

Issue・PR

  • Issue 作成前に必ず既存 Issue を確認する（gh issue list --state all）
  • GitHub 上の操作（issue 作成・クローズ、PR 作成、push 等）は取り消しが困難。実行前にユーザーへ確認する

Git ブランチ操作

  • ブランチの作成・切り替えは必ずユーザーに確認を求めてから実行する

コミット規約

Conventional Commits v1.0.0 に準拠する。コミットメッセージは英語。Co-Authored-By: フッターは付けない。

scope 対象
read read_jartic_traffic()（読み込み）
xroad 国土交通省 xROAD 交通量 API（R/xroad_traffic.R）
location 観測地点テーブル（R/location.R）
data 同梱データ・data-raw/ の生成スクリプト
deps DESCRIPTION の依存
ci .github/workflows/
docs README・roxygen・pkgdown
test tests/

例:

feat(read): support type A traffic files
feat(xroad): reject specification-style quoted CQL filters
fix(location): keep unsplit location names when the arrow is absent
test(read): pin the CP932 decoding contract
chore(deps): move tibble to Suggests

セキュリティ・データ取り扱い

  • 認証情報（API key、サービスアカウント JSON、.env）をコミットしない
  • 資格情報ファイル・.env・認証用 JSON・秘密鍵など、秘密を保存するためのファイルを読まない・編集しない・出力しない・検索しない・要約しない
  • 認証付きのアクセスが要るときは、必要な認証情報・環境変数を説明して許可を得てから有効にする。値をプロンプト・ログ・コマンド出力・コミットに含めない
  • Claude Code / Codex の通常セッションでは R_ENVIRON_USER=/dev/null とし、R に資格情報ファイルを自動ロードさせない（.claude/settings.json / .codex/config.toml）。同ファイルで LC_COLLATE=C を設定し、sort() / factor() の水準順がマシン依存にならないようにしている。この 2 つのキーを消さない
  • コミット前に git status で意図しないファイル（生データ・生成物）が含まれていないか確認する

既知の課題

コードの挙動を変える変更なので、着手前にユーザーへ確認する。

  • type A（旅行時間情報）には未対応。read_jartic_traffic() は type B 専用
  • arrow スキーマ対応は一度入れて revert された（dfdd6e9 → 8e7f3a6）。再導入するなら arrow は Suggests に置き、無い環境でスキップできる形にする