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

341 lines
19 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# 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 を更新してデプロイしたか**（ユーザーに言われる前に完了させる）
---
## 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`
Reference in New Issue View Git Blame Copy Permalink