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

298 lines
17 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
> **このファイルについて**: `AGENTS.md` は Claude Code 以外の AI ツール（Antigravity, Gemini, ChatGPT 等）向けの規約ファイルです。内容は `CLAUDE.md`（Claude Code 用）と完全同期しています。変更する場合は **必ず両ファイルを同時に更新**してください。
---
## 新しい AI への引き継ぎチェックリスト（必読）
別の AI エージェント（Antigravity 等）やセッションを新たに始めるときは、**必ず最初にこのセクションを読ませること。**
### 作業前に AI が確認すべき事項
1. **AGENTS.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 / AGENTS.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・AGENTS.md・server.js 等を変更した後）
```bash
cd C:/Users/maita/posimai-project
git add CLAUDE.md AGENTS.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 で確認する
以下のトピックについては、**訓練データの知識だけで答えてはいけない**。回答前に必ず検索ツールで現在の情報を確認すること：
| トピック | 理由 |
|---------|------|
| AI モデルのバージョン・モデル名（Claude, Gemini, GPT 等） | リリースサイクルが速く訓練データがすぐ古くなる |
| npm パッケージの最新バージョン | セキュリティパッチ・breaking changes が頻繁 |
| Vercel / Next.js の設定・API 仕様 | バージョンアップで仕様変更が多い |
| Tailscale / Docker の設定・コマンド | 手順がバージョンで変わることがある |
| ブラウザ API のサポート状況（PWA, Web Share 等） | Can I Use で現在のサポート率を確認 |
**検索してから答える手順：**
1. 検索ツールで「[技術名] [バージョン or latest] site:公式ドキュメント」で検索
2. 取得した情報をもとに回答
3. 回答に「検索日: [今日の日付]」を添えて情報の鮮度を明示する
**検索ツールが使えない・不明な場合：**
- 「訓練データをもとに回答しています。最新情報は公式ドキュメントで確認してください（知識カットオフ: [自分のカットオフ日]）」と明示してから回答する
- 検索できないのに検索したかのように回答してはいけない
### ファイル同期ルール（違反時は即修正）
| 操作 | 必ず同時にやること |
|------|-----------------|
| `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"` には必ずセットで付ける |
| **新アプリ作成前にアクセントカラーを宣言しない** | 実装後に変更コストが大きい。カテゴリ確認→AGENTS.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 直接呼び出し） |
## Synology バックエンド（server.js）
- ファイル: `server.js`（ルートに配置、git 管理外）
- **デプロイ方法（必須）**: `bash deploy-server.sh` を実行する（SSH → docker cp → docker restart まで自動）
- SSHパスワード → sudoパスワードの順に2回入力を求められる
- スクリプト内の処理: `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/` をコピーして使う。`APP_NAME` / `APP_ID` / `APP_DESCRIPTION` を置換するだけで動く。
**完全な手順（Git / Vercel セットアップ含む）は必ず `_template/README.md` を参照すること。**
特に以下の2点は詰まりやすいので注意：
- Gitea リポジトリは **Web UI で先に作成**してから `git remote add gitea` する
- `vercel git connect` 後、**空コミット push** で初回本番デプロイをトリガーする
### 新アプリ作成後の必須チェックリスト（抜け漏れ禁止）
新しいアプリを作ったら、**コード実装の完了直後に必ずこの順番で実行する**こと：
0. **【実装前】アクセントカラーを宣言する**
- このアプリのカテゴリを確認（インプット/作成・編集/ツール/共有/インフラ）
- デフォルト Teal で問題なければ何もしない
- Sky Blue 等に変える場合は AGENTS.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. **プロジェクト構成テーブルを AGENTS.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