Skip to content

chore(repo): 個人標準の監査で見つかった不足を埋める (CI ゲート / permissions / CHANGELOG / ADR) - #254

Merged
shinyaoguri merged 6 commits into
mainfrom
chore/repo-standards
Aug 5, 2026
Merged

chore(repo): 個人標準の監査で見つかった不足を埋める (CI ゲート / permissions / CHANGELOG / ADR)#254
shinyaoguri merged 6 commits into
mainfrom
chore/repo-standards

Conversation

@shinyaoguri

@shinyaoguri shinyaoguri commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown
Owner

目的

個人標準 (repo-standards) との突き合わせ監査で、必須 NG 2 件・推奨 WARN 12 件が出た。GitHub 側の設定は別途適用済みで、本 PR はリポ内ファイルで直せる分をまとめる。

監査で分かった根本は 2 つ:

  1. CI で強制できていない規約があった — PR タイトルの Conventional Commits、参照ドリフトの定期検知。文書ルールだけでは崩れが履歴に残り続ける
  2. 設定と履歴の正本がリポ外にあった — Claude の permissions は未追跡の local 設定のみ、変更履歴は GitHub Release の自動生成ノートのみ、設計判断の一部は ADR ではなく運用記述にしか無かった

変更点

コミット 対応する監査項目
ci(repo): PR タイトル検査と週次鮮度チェックの workflow を追加する pr-title-lint / scheduled-freshness
chore(claude): 共有 .claude/settings.json で permissions を整備する claude-permissions-curated
docs: CHANGELOG.md を追加する changelog-exists
docs(adr): Biome 導入と E2E deploy ゲートの判断を ADR-0032 / 0033 に残す adr-covers-decisions (必須)
docs: CLAUDE.md の重複を削り 100 行に収める claude-md-quality

各コミットメッセージに目的・変更点・確認方法を書いている。特に注意して見てほしい点:

  • pr-title.yml は pull_request_target を使う (fork PR でも走らせるため)。checkout せずタイトル文字列しか読まず、タイトルは env: 経由で受け取るので run: へのコマンドインジェクション経路は無い。permissions は pull-requests: read のみ
  • .claude/settings.json の deny で npm run deploy:* / gen-checkpoint-key / wrangler deploy / force push / rm -rf / .env の Read を明示的に塞いだ。従来の広い Bash(npm run *) が本番デプロイと署名鍵生成を無確認で通していたため
  • ADR-0032 / 0033 は事後の ADR 化。Date に決定時期 (2026-07) と ADR 化時期 (2026-08-05) の両方を書いている

併せて適用済みの GitHub 設定 (本 PR の範囲外)

設定 before → after
merge 方式 squash / merge commit / rebase → squash のみ (ruleset の allowed_merge_methods も squash に)
squash コミットの要約 / 本文 COMMIT_OR_PR_TITLE / COMMIT_MESSAGES → PR_TITLE / PR_BODY
wiki 有効 → 無効 (中身は自動生成の Home.md 1 行のみ)
auto-merge 無効 → 有効
main の ruleset required_signatures + required_linear_history を追加
refs/tags/v* の ruleset deletion + update → non_fast_forward を追加

確認方法

  • npm run lint green (60 warnings / 9 infos はいずれも scripts/ 由来の既存分)
  • pr-title の判定式を workflow の YAML から抜き出して 22 ケース実行し、全件期待どおりであることを確認 (OK: feat(editor): 追加 fix: 修正 feat!: 破壊的 / NG: Add feature feat: wip Feat(editor): ... feat(): 空 scope など)
  • freshness の各 step をローカルで実行し、リンク検査 1 件・依存 21 件を検知、両方 0 件のとき Issue 作成へ進まないことを確認
  • CHANGELOG の記載はすべて git 履歴と gh pr list --state merged で裏取り済み
  • pr-title は pull_request_target トリガのため、workflow ファイルが base ブランチ (main) に存在してからでないと発火しない。本 PR では走らず、初回実行はマージ後の次の PR になる

残課題

  • freshness の初回実行で docs/adr/0004-verifier-checkpoint-stance.md の packages/verify/src/core/VerificationEngine.ts へのリンク切れが上がる見込み (検証エンジンは shared へ移動済み)。本題と別関心なので本 PR では直していない
  • scripts/ 配下の Biome warning 60 件をどうするかは未決 (ADR-0032 の Follow-ups に記載)

🤖 Generated with Claude Code

shinyaoguri and others added 5 commits August 5, 2026 20:53
@shinyaoguri @claude
ci(repo): PR タイトル検査と週次鮮度チェックの workflow を追加する
a3a382e 
## 目的
個人標準 (repo-standards) の監査で、CI で強制できていない品質ゲートが 2 つ
残っていたため塞ぐ。

- pr-title: squash merge では PR タイトルがそのままマージコミットの要約になる
  ため、Conventional Commits の崩れが main の履歴に永続する
- freshness: 参照先・依存のドリフトは PR CI では捉えられず、定期実行でしか
  拾えない

## 変更点
- `.github/workflows/pr-title.yml`
  - `pull_request_target` で fork PR でも走る。checkout せずタイトル文字列
    しか読まないので fork のコードを実行する経路はない。permissions は
    `pull-requests: read` のみ
  - サードパーティ action に依存せず bash の正規表現 1 本で判定
    (`feat|fix|docs|refactor|test|chore|ci`、scope 省略可、`!` 許可)
  - タイトルは `env:` 経由で受け取り、`run:` へ直接展開しない
    (コマンドインジェクション対策)
  - job id = `pr-title` (= status check の context)
- `.github/workflows/freshness.yml`
  - 週次 (月曜 00:00 UTC) + `workflow_dispatch`
  - 検査 1: Markdown の相対リンク切れ (外部 URL・アンカー・サイト絶対パス・
    gitignore 対象は除外)
  - 検査 2: `npm outdated` の要約 (major 更新を先出し、全件は details に格納)
  - 検知 0 件なら Issue を作らない。1 件以上なら同タイトルの open Issue が
    あればコメント追記、無ければ新規作成 (週次で増殖させない)

## 確認方法
- 両ファイルが YAML として妥当であることを確認
- pr-title の判定式を YAML から抜き出し 22 ケース実行、全件期待どおり
  (OK: `feat(editor): 追加` `fix: 修正` `feat!: 破壊的` / NG: `Add feature`
  `feat: ` `wip` `Feat(editor): ...` `feat(): 空 scope` など)
- freshness の各 step をローカルで実行し、リンク検査 1 件・依存 21 件を検知、
  `LINKS_COUNT=0 DEPS_COUNT=0` で Issue 作成へ進まないことを確認
- `npm run lint` green

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@shinyaoguri @claude
chore(claude): 共有 .claude/settings.json で permissions を整備する
4409eee 
## 目的
これまで Claude Code の permissions は未追跡の `.claude/settings.local.json`
(5 件) にしかなく、clone / worktree を作るたびに引き継がれなかった。加えて
`Bash(npm run *)` が広すぎ、`packages/workers` の `deploy:production` や
`gen-checkpoint-key` (署名鍵生成) まで確認プロンプトなしで通る状態だった。

## 変更点
- `.claude/settings.json` を新規追加 (追跡対象)
- allow: 本リポで頻繁に使う読み取り系・非破壊コマンドを列挙
  - ビルド / 型検査 / lint / テスト / dev サーバ / doctor
  - git の参照系 (status, diff, log, show, branch, worktree list, fetch など)
  - gh の参照系 (pr / issue / run / release の view・list、本リポの api GET)
- deny: 外部影響・不可逆な操作を明示的に塞ぐ (deny は allow に優先する)
  - `npm run deploy:*` / `gen-checkpoint-key` / `gen-exam-authority-key`
  - `wrangler deploy` / `wrangler secret`
  - `git push --force` / `-f` / `--delete`、`git reset --hard`、`git tag -d`
  - `rm -rf`、`gh repo delete`、`gh release delete`
  - `.env` / `.dev.vars` の Read (秘密情報をコンテキストへ持ち込まない)

個人固有の設定は従来どおり `.claude/settings.local.json` (gitignore 済み) に
残す。

## 確認方法
- `jq . .claude/settings.json` でパースできることを確認
- allow の対象コマンドがルート `package.json` の scripts・CLAUDE.md・
  `.github/workflows/deploy.yml` に実在することを確認
- deny の対象が `packages/workers/package.json` の scripts に実在することを確認

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@shinyaoguri @claude
docs: CHANGELOG.md を追加する
28b19a5 
## 目的
本リポはタグ式 GitHub Flow (ADR-0028) で `v*` タグから production へ出す。
リリースするリポでは変更履歴が利用者への契約になるが、これまで正本が無く
GitHub Release の自動生成ノート (PR 全列挙) しか無かった。

## 変更点
- ルートに `CHANGELOG.md` を追加 (Keep a Changelog 形式 / 日本語)
- `[Unreleased]` に v1.1.0..main の 24 コミットから利用者に見える変化のみを
  10 件 (変更 4 / 修正 4 / セキュリティ 2)。内部リファクタ・CI 高速化・
  リポ運用整備は列挙しない
- `[1.1.0] - 2026-07-07` に主要変更 40 件。プロジェクト開始以降の全 PR は
  網羅せず、その旨と GitHub Release へのリンクを冒頭に注記
- 末尾にバージョン比較リンク

記載内容はすべて git 履歴で裏を取っている。コミット要約末尾の `(#NN)` は
Issue 番号のことがあるため、`gh pr list --state merged` と merge commit で
実 PR 番号を突き合わせて確定させた。

## 確認方法
- 本文中の `docs/adr/*.md` 相対リンク 20 本すべての実在を確認
- ルート `package.json` の version (1.1.0) とタグ v1.1.0 が一致することを
  `git log -L` で確認 (食い違いは無い)
- `npm run lint` green

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@shinyaoguri @claude
docs(adr): Biome 導入と E2E deploy ゲートの判断を ADR-0032 / 0033 に残す
5d33a10 
## 目的
個人標準の監査 (adr-covers-decisions) で、設計判断を伴う変更のうち 2 件に
ADR が残っていないことが分かった。どちらも「なぜその範囲か」が CLAUDE.md と
CONTRIBUTING の運用記述にしか無く、却下した選択肢が失われていた。

## 変更点
- `docs/adr/0032-biome-as-single-lint-format-toolchain.md` (Accepted)
  - lint / format を Biome 1 つに集約した判断 (Issue #157 / PR #185)
  - 却下: ESLint + Prettier (依存 3 系統・型情報 lint が monorepo で遅い)、
    現状維持 + `.editorconfig` (CI で強制できない)
  - `.editorconfig` を置かない理由 (format の正本を Biome に一本化) と、
    型情報つきルールの不足を `tsconfig.base.json` の厳格化で補う分担を明記
- `docs/adr/0033-e2e-round-trip-harness-as-deploy-gate.md` (Accepted)
  - E2E を暗号成果物 (verify-cli の exit code) をオラクルにした round-trip に
    限定し、全 deploy の必須ゲートに置いた判断 (PR #116〜#118 / #192)
  - 却下: ユニットのみ、UI アサーション中心の E2E、全シナリオ full 検証
  - full は happy-path 1 本・他は `--mode fast`、負のオラクルを必ず対で持つ、
    合成打鍵は `dispatchEvent` で注入 (ADR-0018) の線引きを決定として記録
- `docs/adr/README.md` の一覧に 2 行追加

いずれも事後の ADR 化のため、Date に決定時期と ADR 化時期の両方を書いている。

## 確認方法
- 両 ADR が template.md の 4 節 (Context / Considered Options / Decision /
  Consequences) と Status・Date・PR の front block を満たすことを確認
- 参照している相対リンク (ADR-0018 / 0028 / 0032、deploy.yml、
  packages/e2e/CLAUDE.md、biome.json、tsconfig.base.json) の実在を確認
- 記載した PR 番号を `gh pr list --state merged` と merge commit で突き合わせ
- `npm run lint` green

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@shinyaoguri @claude
docs: CLAUDE.md の重複を削り 100 行に収める
45125f9 
## 目的
個人標準の監査 (claude-md-quality) で 128 行と目安 (100 行) を超過し、
グローバル CLAUDE.md や他ドキュメントとの重複が指摘された。玄関口としての
役割に絞り、正本が別にある内容はリンクに置き換える。

## 変更点
- Version の記述を 1.0.0 → 1.1.0 に修正 (`package.json` の実態に合わせる。
  タグ v1.1.0 のコミットで bump 済みだった)
- 「コミットと PR タイトルは Conventional Commits」の行を削除
  (グローバル CLAUDE.md と重複)。代わりに CI の `pr-title` job が検査する
  ことと許可 type を 1 行で書く
- ブランチ名の規約をグローバル側に委ね、worktree で作業する点だけ残す
- 委譲プロンプトを自己完結で書く旨の一般論を削除し、委譲の目安 2 行に圧縮
- 「ドキュメント階層」の箇条書き 6 行を 1 段落に圧縮 (CHANGELOG.md を追加)
- 「環境設定」の変数一覧 (17 行) を削除し docs/setup.md と
  packages/workers/CLAUDE.md へのリンクに置換。三重の重複だった。あわせて
  秘密情報を docs へ書き写さない旨を明記
- dev / build / test コマンドの列挙を圧縮 (個別コマンドは 1 行にまとめる)

## 確認方法
- `wc -l CLAUDE.md` = 100 行
- 記載した相対リンク (docs/setup.md, docs/system-spec.md, docs/adr/,
  CONTRIBUTING.md, CHANGELOG.md, packages/*/CLAUDE.md) の実在を確認
- 削除した内容の正本が docs/setup.md と packages/workers/CLAUDE.md に
  存在することを確認

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
@github-actions github-actions Bot added documentation Improvements or additions to documentation pkg:repo リポジトリ横断 (docs/CI/依存) labels Aug 5, 2026
@github-actions

github-actions Bot commented Aug 5, 2026 •
edited
Loading

Copy link
Copy Markdown

🚀 Preview Deployment

Name URL
Preview https://d8477cfc.typedcode.pages.dev

Deployed from commit adfd695
API: staging Workers

@shinyaoguri shinyaoguri mentioned this pull request Aug 5, 2026
Closed
4 tasks
This was referenced Aug 5, 2026
Open
Open
@shinyaoguri
shinyaoguri merged commit 0332927 into main Aug 5, 2026
7 checks passed
@shinyaoguri
shinyaoguri deleted the chore/repo-standards branch August 5, 2026 16:30
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

documentation Improvements or additions to documentation pkg:repo リポジトリ横断 (docs/CI/依存)

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

1 participant

@shinyaoguri