Imported from tanaka-note/t-room-site (AGENTS.md). Install upstream with npx skills add tanaka-note/t-room-site. Copyright stays with the author.

T-lain 開発ルール

このファイルはリポジトリ全体に適用する。ユーザーの明示的な指示がある場合は、その指示を優先する。

1. 自律的に完了まで進める

• 実装方針をユーザーと確認し、方向性が確定した後は細かな確認を繰り返さない。
• 原則として、調査 → 実装 → テスト → 回帰テスト → ビルド → Git commit → GitHub push → 本番反映 → 可能な範囲の本番確認まで一連の作業として完了させる。
• Cloudflareなどへの本番反映は、対象サービスの通常の公開手順に含まれ、ユーザーから公開まで承認されている場合に行う。
• ユーザーにしか行えない認証、二段階認証、決済情報入力などを除き、Codex側で実行できる作業は自律的に進め、結果を報告する。
• 次の場合のみ作業を止めて確認する。
  • 当初の方針を大きく変更する必要がある
  • 本番データを削除・破壊する可能性がある
  • 認証、暗号化、鍵管理などのセキュリティ設計を変更する必要がある
  • ユーザーの意図を複数通りに解釈でき、結果が大きく変わる

2. 変更範囲を必要最小限にする

• 依頼された目的を達成するために必要な箇所だけを変更する。
• 既存UI、既存仕様、既存の共通処理で判断できる場合は、その方式を踏襲する。
• 指定されていないUI、入力方法、機能を「便利そう」という理由だけで追加しない。
• 関連する同種機能、類似UI、同じ処理は調査する。ただし共通仕様として直す必要がないものまで勝手に変更しない。
• 同様の問題や改善候補を他で見つけた場合は、作業範囲を広げず完了報告で提案する。
• ユーザー体験が大きく異なる複数案がある場合のみ、実装前に確認する。

3. バグ修正と検証

• 症状だけを隠さず、原因を特定してから最小限の修正を行う。
• 修正前に、変更の影響を受ける可能性がある既存機能を洗い出し、回帰テスト対象に含める。
• 重要なバグ、再発したバグには、可能な限り再現テストまたは自動テストを追加する。
• 実際に実行して成功したテストだけを「確認済み」「回帰テスト完了」と報告する。未実施、代替確認、確認不能は明確に区別する。
• 本番確認では実データを破壊せず、安全なテストデータまたは読み取り操作を優先する。
• Container、Queue、R2転送等の従量課金を伴う実環境テストは、ローカル・単体・小容量fixtureで代替できない最小限の代表ケースに限定する。同じ高負荷E2EをCodexの判断だけで繰り返さず、可能な範囲で利用量・契約内枠を確認し、追加課金を避ける。未実施の高負荷確認はその旨を報告する。
• 変更対象外の既存差分を上書き、削除、コミットしない。
• 資産運用報告の「運用手数料・雑費」は短期的には維持し、変動がある場合のみユーザーの指示に従って更新する。

ブランド資産保護

• ユーザーの明示的な変更指示がない限り、Android・TWA・PWAのランチャーアイコン、ロゴ、favicon、splash、アプリ名、ブランドカラー、キャラクターデザイン等のサービス識別資産を変更しない。
• 機能追加、バグ修正、リファクタリング、SDK対応、依存関係更新では直前の正式版デザインを維持し、技術的な適合だけでは見た目を変えない。見た目の変更が必要な場合は実装前に確認する。
• ブランド資産が依頼範囲外でGit差分に現れた場合はコミット前に意図を確認し、不要な差分は正式版へ戻す。

4. Git・公開

• 通常は npm run verify:plan / npm run verify:changed またはサービス別verifyを使う。PRのCI・Preview、失敗Trace、ローカルD1/R2、対象限定releaseは開発フローに従う。本番bindingを持つWorkerをそのままPreview公開しない。

• コミットには今回の依頼に関係するファイルだけを含める。

• 調査・取得・比較・検証用の一時ファイルはリポジトリ直下に残さず、ignore済みのtmp/またはOSの一時ディレクトリへ生成する。

• Codex自身が作成した一時ファイルは不要であることを確認し、作業完了前に削除する。作業開始前からある未追跡ファイルやユーザー作成物は、正体を確認せず削除しない。

• 公開前に構文確認、対象テスト、影響範囲の回帰テスト、必要なビルドを実行する。

• GitHub pushと本番反映の両方が必要なサービスでは、片方だけで完了扱いにしない。

• 完了報告には、変更内容、原因、実行したテストと結果、公開先、commitを簡潔に記載する。

5. T-Cloudのセキュリティ原則

共通

• R2へ保存するデータは、原則として暗号化する。
• 復号鍵、パスワード、秘密鍵、署名鍵をCloudflare、GitHub、ログ、ソースコードへ保存しない。
• 認証、暗号方式、鍵管理を変更する場合は、実装前にユーザーへ影響と移行方法を説明し、承認を得る。
• 「基本は暗号化。表示高速化に必要な軽量データは例外。動画だけはCloudflare側に平文を見せない」ことを基本方針とする。

動画

• R2には暗号化済み動画だけを保存する。
• 動画の平文データをR2、D1などのCloudflare側へ保存せず、Cloudflare側で処理させない。
• 動画の復号は原則としてユーザー端末側で行い、Cloudflare側へ平文動画を渡さない。
• 「動画の内容をCloudflare側に見せない」ことをT-Cloudの重要なセキュリティ原則とする。
• 明示的な方針変更と承認なしに、Cloudflare StreamなどCloudflare側で動画の復号・解析を必要とする仕組みを導入しない。

表示高速化用データ

• サムネイル、写真表示用データ、テキストファイル、表示情報、メタデータなどの軽量データは、表示速度や操作性を優先するため、必要に応じてR2・D1への平文保存またはユーザー端末へのキャッシュを認める。
• 平文保存は目的達成に必要な最小限のデータと範囲に限定し、機密性と利便性を個別に評価する。
• ただし、動画データにはこの例外を適用しない。
• 日記の正式写真も昇格後にdiary/staging/配下のR2 objectを参照するため、このprefixへR2 Lifecycleの自動削除を設定しない。

6. 文書の維持

• このファイルには開発判断に必要な最重要ルールだけを残し、同じ趣旨の記述を重複させない。
• 詳細が増えて判断しづらくなる場合のみ、T-Cloudアーキテクチャ、セキュリティ仕様、テスト方針、デプロイ方針を別文書へ分離し、このファイルから参照する。
• 文書を増やすこと自体を目的にしない。Codexが迷わず安全に自律開発できる状態を優先する。

7. Web自動反映・公開先

• T-lainのユーザー向けWebサイト／Webアプリは、通常ブラウザ・PWA・TWAで安全に最新版へ自動更新される構成を標準とし、新規サイトにも初期実装から適用する。
• 未保存入力、アップロード、ダウンロード等がある間は更新を延期し、安全になってから自動再試行する。
• 対象アプリ、公開URL、build marker、Service Worker、deploy targetはweb-apps.jsonを正とし、追加・変更時はcontract testを通す。
• GitHub pushだけで公開完了とせず、変更した全サービスをregistry記載の正しいtargetへdeployし、本番build一致まで確認する。
• 技術的理由で自動更新を適用できないユーザー向けサイトは、勝手に例外化せずユーザーへ説明して確認する。

8. 共通Identity・パスキー

• 既存PW認証と各サービス固有のアカウント・role・セッションを正本として維持し、共通Identityと権限を混同しない。第一管理者PWは恒久的な復旧手段として残す。
• パスキーの新規・追加・再登録は第一管理者の招待と承認を必須とし、端末標準のロック解除、discoverable credential、user verificationを使用する。
• T-Cloudはパスキーでも端末側だけで既存鍵を解除し、PRF出力、復号鍵、folder key、file keyをCloudflare、GitHub、ログへ渡さない。
• Security CenterをIdentity・招待・連携・監査の正本とし、失敗だけでなく成功ログインと重要な管理者アクセスも監査する。詳細はdocs/security/passkeys.mdに従う。

9. 画面遷移・戻る操作

• 詳細・検索結果・フォルダ・子画面等から戻る場合は、原則として遷移元の表示位置と表示状態を復元する。ページ全体だけでなく、意味のある内部スクロール領域も対象とする。
• 動的リストは安定したitem ID等をアンカーにし、検索・フィルター・ソート・表示モード・読み込み済み範囲を再現して必要なデータを描画した後に位置を復元する。
• ブラウザ標準のHistory・BFCache・scroll restorationで十分な画面はそれを利用し、明示的な新規遷移と「戻る」操作を区別する。Web・PWA・TWAで同じ基本UXを維持する。
• パスワード、復号鍵、秘密情報、危険操作の承認状態、意図しない再送信につながるフォーム状態は保存しない。