Why it is hard
簡単な題材ではありません。
そこが面白いところです。
対象はメンバー管理を中心に、経歴・スキル、現場・案件、面談、人事考課、権限管理まで広がる基幹寄りの業務システムです。一括で書き直すのではなく、機能単位の縦切りで移行しています。理由は、この3つが同時に効いてくるからです。
認可モデルの移行
「管理者／一般」のような単純なロールではなく、グループとユーザー単位の例外を組み合わせた、機能・操作単位のモデルです。安易にロールへ縮約すると権限漏れが起きます。認可モデルを、データベースの制約とクエリレベルの絞り込みにまで反映して再現します。
データ移行の検証
旧システムには自動テストがほとんどありません。行数・チェックサム・キー関係の突合など、値そのものを見ずに移行の正しさを示す方法を設計する必要があります。
保証基準がないテスト設計
「今まで動いていたから正しい」という前提が使えません。機能ごとに期待される挙動を明文化してからテストを書きます。何を正とするかを決めるところが仕事です。
How we work
人の役割が「書くこと」から
「検証すること」へ移ります。
実装は AI コーディングエージェントが行い、人が差分を検証します。それを成立させているのは、設計を先に固め、レビューを通してから実装するという順序です。この5つは、その順序をエージェントが実装する環境で保つための具体策です。
AI-first 開発
共通指示を1か所へ集約し、繰り返す手順を skill へ切り出す。実装者が変わっても手順が変わらない。
ADR 駆動
元に戻しにくい判断は必ず記録する。設計書レビューの後継にあたる仕組み。
契約優先
OpenAPI を HTTP API 契約の正とし、型を自動生成し、CI で乖離を検出する。
要求トレーサビリティ
受け入れ条件に機械可読なIDを割り当て、マーカーで実装とテストに結び付け、食い違いを終了コードで検出する。
検証文化
生成されただけでは完了ではない。確認できなかったことも書き残す。
ズレを検出したら、エージェントは整合を取らずに停止して人へ報告します。検出スクリプトに --fix にあたる機能はありません。
生成 AI が仕様とコードの両方を書く体制では、「仕様のほうを書き換えて辻褄を合わせる」が最も起こりやすい失敗モードだからです。整合させる判断は人に残します。
Proof
壊してみてください。
1つの要求IDは、5箇所に現れていなければなりません。仕様、台帳、コミット、実装、テスト。どれか1つだけを動かすと検出され、そこで止まります。実際の要求で試せます。
-
01仕様
- [x] `REQ-MEMBER-INTRO-001` 一覧responseは許可されたsummaryだけを含み、自己紹介全文を含まないrequirements-md.md の実例（逐語） -
02台帳
status: implemented kind: requirementregistry.yaml は非公開。規則が読む2項目のみ -
03コミット
Requirement: REQ-MEMBER-INTRO-001trailer（任意） -
04実装
// @req REQ-MEMBER-INTRO-001implemented なら必須 -
05テスト
// @req REQ-MEMBER-INTRO-001implemented なら必須
req:checkpassexit 05箇所すべてでIDが一致している。
2つめの操作が、この仕組みの核心です。「仕様のほうを書き換えて辻褄を合わせる」「状態を下げて警告が出ないようにする」は、生成AIが仕様とコードの両方を書く体制で最も起こりやすい失敗です。その回避行動自体を D-REGRESS で検出します。
そして、検出したらエージェントは整合を取らずに停止し、人へ報告します。検出スクリプトに --fix にあたる機能はありません。
この仕組みが検出できないこと
限界は規約本文に書いてあります。以下はすべてその引用です。
- 仕様とコードを同一 Pull Request で同時に書き換えれば通過します。検出できるのは共変更規約の違反であって、意味の一致ではありません。
D-CODEは意味を変えないリファクタでも発火します。機械的に除外する信頼できる方法が無いため、恒久的に warning に留め、ブロックへ昇格させません。- 参照先 ADR の実在は確認しますが、ADR 本文が要求を実際に満たしているかは機械検証しません。その判断は人のレビューに残ります。
Diagrams
設計判断を反映した、動かせる図。
ADR から機械的に生成した図です。生成のたびに同じ結果になることと、配置や線の重なりを自動で検証しています。ブラウザの中でそのまま動きます — 図と ADR が食い違う場合は、ADR が正です。
- テーマ切替
- 検索
- 関係のたどり
- 拡大縮小
- 画像の書き出し
認証・認可の trust boundary
ブラウザから PostgreSQL までのあいだで、どこに境界があり、各所で何を検証し、何をブラウザへ渡さないか。
ADR 0001 / 0004 / 0005 / 0007 / 0011 / 0012 / 0017 / 0018Issue から merge までの運用フロー
起票から実装、検証、Pull Request、マージまでの順序と、各段階で満たすべき条件。どこで止まるかも示します。
開発の進め方 / 要求トレーサビリティの規約要求 ID のトレーサビリティ
受け入れ条件が、ID・台帳・コード中のマーカーを通ってズレの検出までどうつながるか。
要求トレーサビリティの規約 / ADR 0023認証・認可の検証順序
リクエストがPostgreSQLに届くまでに何がどこで検証され、どの失敗がどの分類に当てはまるか。
ADR 0006 / 0007 / 0009 / 0011 / 0012写真の write lifecycle
登録・置き換え・削除が通る状態と、途中で失敗したときにどう再開するか。
ADR 0017 / 0018設計図の一覧 →
5枚すべての読み方と、投影元の ADR をまとめています。
docs/diagrams/Built this way
このページ自体が、その過程です。
ここまでのヒーロー、さきほど壊していただいたデモ、上の図の埋め込み。いずれも AI エージェントが実装し、人が差分を検証し、公開の Pull Request を経てマージされました。差分も検証結果もそのまま読めます。
先に、検証できなかったことを書きます。ヒーローの 3D について、GPU のフレーム時間は信頼できる値を測れませんでした。検証に使ったブラウザでは gl.finish() を挟んでも実際の GPU 時間を反映しなかったためです。この事実は PR 本文にそのまま書かれています。
「確認できなかったことも書く」はこのプロジェクトの完了条件のひとつです。ここで伏せると、その主張自体が嘘になります。
| PR | 作ったもの | 差分 | 検証 |
|---|---|---|---|
| #42 | このページと 3D ヒーロー | +4,036 / −260 | 劣化経路4条件を実機確認。GPU のフレーム時間は測れず、その旨を明記 |
| #43 | 上のトレーサビリティのデモ | +461 | 検証項目 9 件。引用が原本と逐語一致することを機械的に検査 |
| #44 | 上の設計図の埋め込み | +117 | 検証項目 7 件。埋め込む幅の閾値は実測で決定 |
規模は誇張しません。これは公開サイトであって、作り直している業務システムそのものではありません。示せるのは、同じ進め方が実際に回り、検証の記録が公開されているという事実だけです。開発そのものは別のリポジトリで行っています。
What you touch
参加して何に触れられるか
到達点は人によって違って構いません。環境構築まででも、その日の学びとしては十分です。
- Rust — 業務ロジック・認可・トランザクション
- TypeScript / Next.js — サーバーサイド統合を含む UI
- PostgreSQL — スキーマ、Row Level Security、権限モデル
- OpenAPI — 契約優先の型生成と drift 検査
- 要求トレーサビリティ
- データ移行・検証設計
- CI/CD・デプロイ構成
- AI エージェント運用
Join
社内メンバー、有志、自己学習目的。
いずれも歓迎します。
参加は Discussions の Apply カテゴリへの投稿から始まります。アクセスは段階的にお渡しします。
- 申込Discussions の Apply カテゴリへ、動機・使える時間・関心領域を書いて投稿します。
- ワークショップ参加該当する場合。当日限定の一時アクセスをお渡しします。
- 実績の確認Issue への着手・PR 提出、または Discussions でのやり取り。
- 招待開発リポジトリの collaborator 権限をご案内します。
開発で使うのは合成データだけです。メンバー名や写真も、この用途のために作った架空のデータです。実在する人物の情報をローカル環境やCIへ持ち込まないことを、プロジェクトの譲れない原則としています。
AI コーディングエージェントのアカウントが必要です（Claude Code か Codex のどちらか一方）。費用は自己負担になります。
Documents
読むところ
このリポジトリにコードはありません。開発は別のリポジトリで行っています。ここは、参加を検討している方とワークショップ参加者のための入口です。