posimai-root/CLAUDE.md

# 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 以下の全記憶ファイル |

### 新マシンでの復元手順

```bash
# 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 等を変更した後）

```bash
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 が記憶を更新した後）

```bash
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 ルール（必須）

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

```bash
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-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 を更新する手順

```bash
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 を既存アプリに適用する手順

```html
<!-- <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 は必ずネットワーク経由（キャッシュ禁止）
  ```js
  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
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** で初回本番デプロイをトリガーする

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

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

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

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

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

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

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

5. **Dashboard をデプロイ**
   ```bash
   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
   ```

6. **プロジェクト構成テーブルを 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`