mai
/
posimai-root
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
posimai-root/CLAUDE.md

20 KiB
Raw Blame History

Posimai Project — AI Instructions

新しい AI への引き継ぎチェックリスト（必読）

別の AI エージェント（Antigravity 等）やセッションを新たに始めるときは、必ず最初にこのセクションを読ませること。

作業前に AI が確認すべき事項

  1. CLAUDE.md を全文読む（このファイル）— デザインルール・デプロイ方法・禁止事項がすべてここにある
  2. memory/ ディレクトリを確認する — C:\Users\maita\.claude\projects\c--Users-maita-posimai-project\memory\MEMORY.md にプロジェクト固有の記憶がある
  3. posimai-dashboard/src/data/projects.json を確認する — 全アプリの一覧・ステータス・技術スタックがここにある

ディザスタリカバリ（PC 完全消失時の復元手順）

バックアップリポジトリ

リポジトリ Gitea（ローカル） GitHub（クラウド） 内容
posimai-root http://100.76.7.3:3000/mai/posimai-root https://github.com/posimai/posimai-root (private) CLAUDE.md / _template / server.js / scripts / deploy-server.sh / claude-settings.json
claude-memory http://100.76.7.3:3000/mai/claude-memory https://github.com/posimai/claude-memory (private) ~/.claude/memory 以下の全記憶ファイル

新マシンでの復元手順

# 1. GitHub CLI 認証
gh auth login

# 2. posimai-root を clone（CLAUDE.md・設定類を復元）
git clone https://github.com/posimai/posimai-root.git "C:/Users/maita/posimai-project"
cd "C:/Users/maita/posimai-project"
git remote add gitea http://100.76.7.3:3000/mai/posimai-root.git

# 3. Claude Code settings を復元
cp "C:/Users/maita/posimai-project/claude-settings.json" "C:/Users/maita/.claude/settings.json"

# 4. claude-memory を clone（AI 記憶を復元）
git clone https://github.com/posimai/claude-memory.git "C:/Users/maita/.claude/projects/c--Users-maita-posimai-project/memory"
cd "C:/Users/maita/.claude/projects/c--Users-maita-posimai-project/memory"
git remote add gitea http://100.76.7.3:3000/mai/claude-memory.git

# 5. 各アプリを必要に応じて clone
# git clone https://github.com/posimai/[app-name].git "C:/Users/maita/posimai-project/[app-name]"
# cd [app-name] && git remote add gitea http://100.76.7.3:3000/mai/[app-name].git

posimai-root の更新方法（CLAUDE.md・server.js 等を変更した後）

cd C:/Users/maita/posimai-project
git add CLAUDE.md claude-settings.json _template/ deploy-server.sh scripts/ server.js
git commit -m "chore: update ..."
git push gitea main && git push github main

claude-memory の更新方法（AI が記憶を更新した後）

cd "C:/Users/maita/.claude/projects/c--Users-maita-posimai-project/memory"
git add .
git commit -m "chore: update memory"
git push gitea main && git push github main

AI の調査・回答ルール

バージョン・最新情報は必ず WebSearch で確認する

以下のトピックについては、訓練データの知識だけで答えてはいけない。回答前に必ず WebSearch ツールで現在の情報を確認すること：

トピック 理由
AI モデルのバージョン・モデル名（Claude, Gemini, GPT 等） リリースサイクルが速く訓練データがすぐ古くなる
npm パッケージの最新バージョン セキュリティパッチ・breaking changes が頻繁
Vercel / Next.js の設定・API 仕様 バージョンアップで仕様変更が多い
Tailscale / Docker の設定・コマンド 手順がバージョンで変わることがある
ブラウザ API のサポート状況（PWA, Web Share 等） Can I Use で現在のサポート率を確認

検索してから答える手順：

  1. WebSearch で「[技術名] [バージョン or latest] site:公式ドキュメント」で検索
  2. 取得した情報をもとに回答
  3. 回答に「検索日: [今日の日付]」を添えて情報の鮮度を明示する

WebSearch が使えない状況の場合：

  • 「訓練データをもとに回答しています。最新情報は公式ドキュメントで確認してください（知識カットオフ: [自分のカットオフ日]）」と明示してから回答する

ファイル同期ルール（違反時は即修正）

操作 必ず同時にやること
CLAUDE.md を変更 AGENTS.md も同等の内容に更新する（ツール名は AI 固有のため完全同一でなくてよい）
AGENTS.md を変更 CLAUDE.md も同等の内容に更新する（ツール名は AI 固有のため完全同一でなくてよい）
~/.claude/settings.json を変更 posimai-root/claude-settings.json を上書きコピーして push
memory ファイルを変更 claude-memory リポジトリに push する

AI が絶対に守るべきルール（違反時は即修正）

禁止事項 理由
絵文字の使用（コード・コメント・HTML 問わず） デザインルール違反
lucide@latest の使用 バージョン固定済み（@0.344.0）
CDN ライブラリのバージョン未固定（@latest 等） SW キャッシュ破壊・予期せぬ破壊的変更のリスク
vercel --prod の直接実行 GitHub push で自動デプロイされるため二重になる
git push origin の使用 gitea と github の2リモートを使う
デザインシステム外の色の使用 アクセントは --accent 1色のみ
manifest.json / sw.js のないアプリを作る 全アプリ PWA 必須
theme-color メタタグをメディアクエリなしで書く ライトモード時に黒い問題が発生する
新アプリ作成後に Dashboard 更新を省略する アプリがエコシステムから孤立する。ユーザーに言われなくても必ずやる
SW でクロスオリジン GET リクエストをキャッシュする Brain API 等の外部 API が古いデータを返す・データ消失に見える（Habit バグ事例あり）
lucide.createIcons() を早期 return の後にしか呼ばない 早期 return のコードパスでアイコンが空になる（Habit バグ事例あり）
CSS でアクセントカラーをハードコード（#6EE7B7 直書き等） ダーク/ライトテーマ切り替えが壊れる。必ず var(--accent) を使う
底面固定要素に env(safe-area-inset-bottom) を付けない iPhone のホームインジケーター領域にコンテンツが被る
外部リンクに rel="noopener" を付けない Tabnabbing 攻撃の温床。target="_blank" には必ずセットで付ける
新アプリ作成前にアクセントカラーを宣言しない 実装後に変更コストが大きい。カテゴリ確認→CLAUDE.md テーブル追記→実装の順を守る

作業完了時の必須チェック

  • emoji が増えていないか (grep -r "emoji\|✅\|📱\|⚙️\|🎉" --include="*.html")
  • @latest が増えていないか (grep -r "@latest" --include="*.html")
  • npm run deploy でデプロイしたか（git push gitea main && git push github main）
  • Dashboard Timeline に追記してデプロイしたか（変更規模を問わず、コードを変更した全セッションで必須。「大きな変更のみ」は誤り）
  • 新アプリなら Dashboard カード・Ecosystem・Timeline・Access Guide を更新してデプロイしたか（ユーザーに言われる前に完了させる）

対応不要と判断済みの改善案（再提案禁止）

以下は検討したうえで「対応不要」と確定した事項。再度提案・実装しないこと。

項目 却下理由
Lucide CDN に defer 属性を付ける 効果が体感できない（Lucide は約 70KB、unpkg CDN でキャッシュ済み）。リスク低でも実装コストに見合わない。<head> 内配置は意図的
モノレポ化 個人利用規模では不要。リポジトリ分離で Vercel 自動デプロイが成立している
Firebase / Supabase SSO 現行の Magic Link + Posimai API Key 方式で十分。複雑性を増やす理由がない
?init_key= URL の廃止 Magic Link の意図的設計。セキュリティ上許容済み（ユーザーが承知）

Deploy ルール（必須）

コードを変更してデプロイするときは 必ずこの手順 を使うこと：

git add .
git commit -m "feat/fix/chore: 変更内容"
npm run deploy

npm run deploy = git push gitea main && git push github main

  • Gitea（http://100.76.7.3:3000/mai/）: ローカルバックアップ
  • GitHub（https://github.com/posimai/）: Vercel 自動デプロイのトリガー

やってはいけないこと

  • vercel --prod を直接実行しない（GitHub push で自動デプロイされるため不要）
    • 例外: 新アプリの初回本番デプロイのみ、空コミット push で代替する（_template/README.md 参照）
  • git push origin を使わない（gitea と github の2つのリモートを使う）
  • git push github main だけ実行して Gitea を忘れない

プロジェクト構成

アプリ ディレクトリ 説明
posimai-dashboard posimai-dashboard/ Next.js メインダッシュボード
posimai-analytics posimai-analytics/ Next.js アナリティクス
posimai-brain posimai-brain/ 記事管理（静的）
posimai-feed posimai-feed/ RSS フィード（静的）
posimai-events posimai-events/ イベント情報（静的）
posimai-hotels posimai-hotels/ ホテル価格ウォッチ（静的）
posimai-daily posimai-daily/ オーディオファースト・ブリーフィング（静的/API融合）
posimai-maps posimai-maps/ マップ（静的）
posimai-reader posimai-reader/ 記事リーダー（静的）
posimai-together posimai-together/ 共有スペース（静的）
posimai-journal posimai-journal/ CMS エディタ（Synology API バック）
posimai-site posimai-site/ 公開ホームページ（journal/site_config と連携）
posimai-digest posimai-digest/ テキスト要約（静的）
posimai-ambient posimai-ambient/ 常時表示アンビエント PWA（静的）
posimai-widget posimai_widget/ Android ホーム画面ウィジェット（Flutter）
posimai-timer posimai-timer/ ストップウォッチ＋カウントダウン（静的）
posimai-habit posimai-habit/ 習慣チェックリスト・ヒートマップ（静的）
posimai-pulse posimai-pulse/ 気分・エネルギー記録（静的）
posimai-lens posimai-lens/ 写真 EXIF メタデータ表示（静的）
posimai-diff posimai-diff/ テキスト差分ビューア（静的）
posimai-clean posimai-clean/ テキストクリーナー（静的）
posimai-tech-events posimai-tech-events/ IT イベント情報（Doorkeeper/connpass RSS）
posimai-think posimai-think/ AI 思考整理アシスタント（Gemini 直接呼び出し）
posimai-ui posimai-ui/ 共有デザインシステム（CSS/JS）— 全静的アプリが参照するインフラ
posimai-veil posimai-veil/ アプリランチャー — ホーム画面を1アイコンに集約（静的 PWA）

共有デザインシステム（posimai-ui）

  • URL: https://posimai-ui.vercel.app/v1/base.css / https://posimai-ui.vercel.app/v1/base.js
  • リポジトリ: posimai-ui/（GitHub: posimai/posimai-ui private）
  • 全静的アプリが <link> と <script defer> で参照する。インラインに CSS/JS を書かない
  • バージョン方針: /v1/ = 後方互換パッチのみ。破壊的変更は /v2/ に切り上げ（全アプリのタグ更新が必要）
  • アプリ側の必須設定: <html data-app-id="posimai-myapp"> でアプリ固有のローカルストレージキーを指定
  • _template-minimal/index.html は既に posimai-ui を参照するよう更新済み

posimai-ui を更新する手順

cd C:/Users/maita/posimai-project/posimai-ui
# ファイルを編集後:
git add .
git commit -m "fix/feat: 変更内容"
npm run deploy   # = git push gitea main && git push github main
# → Vercel が自動デプロイ、全アプリに即時反映

posimai-ui を既存アプリに適用する手順

<!-- <head> 内: インライン <style> の大半を削除し、以下に置き換える -->
<link rel="stylesheet" href="https://posimai-ui.vercel.app/v1/base.css">

<!-- </body> 直前: インライン <script> の共通部分を削除し、以下に置き換える -->
<script src="https://posimai-ui.vercel.app/v1/base.js" defer></script>

Synology バックエンド（server.js）

  • ファイル: server.js（ルートに配置、git 管理外）
  • デプロイ方法（必須）: bash deploy-server.sh を実行する（SSH鍵認証・完全無人）
    • 入力不要（SSH鍵 ~/.ssh/id_ed25519 + docker グループで自動実行）
    • スクリプト内の処理: ssh でファイル転送 → docker cp → docker restart posimai_api → ログ確認
    • ⚠️ vercel --prod や File Station での手動アップロードは使わない
  • API base: https://posimai-lab.tail72e846.ts.net/brain/api
  • 主なテーブル: users, articles, journal_posts, site_config, reading_history
  • 主なエンドポイント: /health, /auth-test, /articles, /article, /feeds, /events/rss, /tts/*, /journal/*

デザインシステム（projects.json designRules が正）

--bg: #0D0D0D          背景
--surface: #1A1A1A     カード面
--surface2: #252525    ネスト面
--border: #2D2D2D      ボーダー
--text: #F3F4F6        主テキスト
--text2: #9CA3AF       副テキスト
--text3: #6B7280       弱テキスト
--accent: #6EE7B7      アクセント（Posimai Teal）← デフォルト
--radius: 12px         角丸
  • フォント: Inter（300/400/500/600）
  • アイコン: Lucide（stroke 1.5〜2.0）
  • ヘッダー: 高さ 52px、glassmorphism、アクセントドット + アプリ名
  • 絵文字: 禁止
  • 全アプリ: manifest.json + sw.js + PWA メタタグ必須
  • トランジション: 0.12s〜0.3s の範囲、標準イージング cubic-bezier(0.2, 0.9, 0.2, 1)
  • 空状態 (Empty State): 必ずアイコン + 説明テキストを実装する（空コンテナ禁止）
  • 外部リンク: target="_blank" rel="noopener" を必ずセットで付ける
  • 底面固定要素: padding-bottom: max(Xpx, env(safe-area-inset-bottom)) で safe area 対応
  • SW キャッシュ: クロスオリジン GET は必ずネットワーク経由（キャッシュ禁止） 
    const ORIGIN = self.location.origin;
self.addEventListener('fetch', e => {
    if (!e.request.url.startsWith(ORIGIN)) return; // APIはスルー
});

アプリ別アクセントカラー（デフォルトから意図的に変える場合のみ記載）

アプリ ダーク accent ライト accent 理由
全般（デフォルト） #6EE7B7 Teal #059669 Posimai ブランドカラー
posimai-journal #80CAEE Sky-Blue #0284C7 CMS 系・静かで知的な印象
posimai-site #80CAEE Sky-Blue #0284C7 journal と同系統の公開サイト
ponshu-room #D4A574 琥珀（Amber） #D4A574 Posimai デザインシステム適用外。独立プロダクト。Washi テーマ（和紙×墨×琥珀）を使用。詳細は ponshu-room/ROADMAP.md を参照。

新アプリ作成時のルール：

  1. デフォルト Teal を使うなら何も記載不要
  2. 意図的に変える場合はこの表に追記してから実装する
  3. 同じ用途・系統のアプリは同じアクセントカラーに揃える

新アプリ作成

テンプレート選択

テンプレート 使うべきアプリ
_template/ 複数ビュー・i18n・Magic Link 認証・サイドバーナビが必要なアプリ（brain, daily, together, journal 相当）
_template-minimal/ 単機能ツール・サイドバー不要なアプリ（diff, clean, timer, lens, ambient 相当）

迷ったら _template-minimal/ を選ぶ（後からフル機能に移行する方が簡単）。

create-app.sh で新規アプリを一括セットアップできる（Git 初期化 + Gitea/GitHub リポジトリ作成 + Vercel 連携まで自動）:

bash create-app.sh posimai-myapp "My App Name" "アプリの説明"

create-app.sh は _template/ を使う。_template-minimal/ を使いたい場合は手動でコピーしてから create-app.sh の Step 3 以降と同じ Git セットアップを行う（_template-minimal/README.md 参照）。

完全な手順（Git / Vercel セットアップ含む）は必ず _template/README.md を参照すること。 特に以下の2点は詰まりやすいので注意：

  • Gitea リポジトリは Web UI で先に作成してから git remote add gitea する（create-app.sh は GITEA_TOKEN 環境変数があれば API で自動作成）
  • vercel git connect 後、空コミット push で初回本番デプロイをトリガーする

新アプリ作成後の必須チェックリスト（抜け漏れ禁止）

新しいアプリを作ったら、コード実装の完了直後に必ずこの順番で実行すること：

  1. 【実装前】アクセントカラーを宣言する

    • このアプリのカテゴリを確認（インプット/作成・編集/ツール/共有/インフラ）
    • デフォルト Teal で問題なければ何もしない
    • Sky Blue 等に変える場合は CLAUDE.md の「アプリ別アクセントカラー」テーブルに先に追記してから実装を開始する

  2. Dashboard カード追加

    • posimai-dashboard/src/data/projects.json の projects 配列にエントリを追加
    • 適切な category を設定（posimai-pwa / active / flagship / micro / infra など）

  3. Ecosystem Map 追加

    • posimai-dashboard/src/app/ecosystem/page.tsx の NODES 配列にノードを追加
    • 関連する EDGES（依存関係）も追加

  4. Development Timeline に追記

    • posimai-dashboard/src/app/timeline/page.tsx の EVENTS 配列に今日の日付でエントリを追加
    • type: launch（新規公開）/ feature（機能追加）/ fix（修正）/ infra（インフラ）

  5. Access Guide に追記

    • posimai-dashboard/src/app/access/page.tsx の APPS 配列にエントリを追加
    • accessLevel / codevAccess / authDetail / codevNote を正確に記入する

  6. Dashboard をデプロイ

    cd posimai-dashboard
git add src/data/projects.json src/app/ecosystem/page.tsx src/app/timeline/page.tsx src/app/access/page.tsx
git commit -m "feat: add [app-name] to dashboard"
npm run deploy

  7. プロジェクト構成テーブルを CLAUDE.md に追記（このファイル）

⚠️ ダッシュボード更新（カード・Ecosystem・Timeline）を忘れると、アプリが孤立してエコシステムから見えなくなる。

既存アプリを変更した場合の必須チェックリスト

コードを変更してデプロイしたら、規模を問わず必ず実行すること（「大きな変更のみ」「気づくレベルのみ」は判断基準として使わない）：

  1. posimai-dashboard/src/app/timeline/page.tsx の EVENTS 配列に今日の日付でエントリを追加
    • 複数アプリを変更した場合は1エントリにまとめてよい
    • type: fix（バグ修正）/ feature（機能追加）/ infra（インフラ・設定）
  2. Dashboard をデプロイ

Git リモート（全アプリ共通）

  • gitea → http://100.76.7.3:3000/mai/[app-name].git
  • github → https://github.com/posimai/[app-name].git