24 KiB

Raw Blame History

Posimai Project — AI Instructions

このファイルについて: AGENTS.md は Claude Code 以外の AI ツール（Antigravity, Gemini, ChatGPT 等）向けの規約ファイルです。内容は CLAUDE.md（Claude Code 用）と完全同期しています。変更する場合は 必ず両ファイルを同時に更新してください。

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

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

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

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

ディザスタリカバリ（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 以下の全記憶ファイル

新マシンでの復元手順

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

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

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 で現在のサポート率を確認

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

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

検索ツールが使えない・不明な場合：

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

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

操作	必ず同時にやること
`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 を更新してデプロイしたか（ユーザーに言われる前に完了させる）

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

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

項目	却下理由
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-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 を既存アプリに適用する手順

<!-- <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 → 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 は必ずネットワーク経由（キャッシュ禁止）

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` を参照。

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

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

新アプリ作成

_template/ をコピーして使う。APP_NAME / APP_ID / APP_DESCRIPTION を置換するだけで動く。

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

Gitea リポジトリは AI が必ず自動作成する。git credential store に認証情報があるため、curl + basic auth で作成できる（手動案内は不可）：

GITEA_PASS=$(git credential fill <<< $'protocol=http\nhost=100.76.7.3:3000' | grep password | cut -d= -f2)
curl -s -X POST "http://100.76.7.3:3000/api/v1/user/repos" -u "mai:$GITEA_PASS" \
    -H "Content-Type: application/json" -d "{\"name\":\"APP_ID\",\"private\":false,\"auto_init\":false}"

vercel git connect 後、空コミット push で初回本番デプロイをトリガーする

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

新しいアプリを作ったら、必ずこの順番で実行すること（0番台は実装開始前、1番以降は実装完了後）：

【実装前】アクセントカラーを宣言する
- このアプリのカテゴリを確認（input インプット / routine 日次ルーティン / create 作成・記録 / tools ツール / business ビジネス / infra インフラ / ideas アイデア）
- デフォルト Teal で問題なければ何もしない
- Sky Blue 等に変える場合は AGENTS.md の「アプリ別アクセントカラー」テーブルに先に追記してから実装を開始する

0.5. 【実装前】logo.png 用 Gemini プロンプトを作成・提示する

コード実装と並行して、ユーザーが Gemini Image に貼れるプロンプトを提示する
構成: 以下の共通プロンプト + アプリ固有の追加プロンプト
アプリ固有部分はアプリの目的・体験・隠喩を視覚化する（機能の説明ではなく感覚的な表現）

共通プロンプト（全アプリ固定）:

App icon, 512x512px, squircle shape with rounded corners.

A small translucent glass orb character, soft matte-frosted surface with
inner teal (#6EE7B7) luminescence glowing from within, gentle light refraction.

Two tiny calm black dot eyes, subtle implied smile.

Background: deep charcoal (#0D0D0D) with barely visible teal ambient gradient.

Style: Apple Liquid Glass, multi-material, 2026 premium minimal.

No outline, no harsh edges. Soft depth, subsurface scattering.

アプリ固有の追加プロンプト例（posimai-veil）:

+ The character gently lifts the edge of a thin translucent frosted veil
(like a sheer fabric curtain), peering out from underneath it.

Behind the veil, a soft 3x3 grid of tiny glowing app dots is barely
visible — implied home screen icons, diffused through the frosted layer.

The veil itself is semi-transparent glass-like material, teal-tinted,
catching the orb's inner glow at the lifted corner.

Git 初期化・リポジトリ作成・初回 push

cd posimai-[app-name]
git init && git add . && git commit -m "feat: initial commit"

# Gitea リポジトリ作成（AI が必ず実行。手動案内は禁止）
GITEA_PASS=$(git credential fill <<< $'protocol=http\nhost=100.76.7.3:3000' | grep password | cut -d= -f2)
curl -s -X POST "http://100.76.7.3:3000/api/v1/user/repos" \
    -H "Content-Type: application/json" \
    -u "mai:$GITEA_PASS" \
    -d "{\"name\":\"posimai-[app-name]\",\"private\":false,\"auto_init\":false}"
git remote add gitea http://100.76.7.3:3000/mai/posimai-[app-name].git

# GitHub リポジトリ作成（AI が必ず実行）
gh repo create posimai/posimai-[app-name] --private --source=. --remote=github
npm run deploy   # = git push gitea main && git push github main

Vercel に接続して初回デプロイをトリガーする

echo "https://github.com/posimai/posimai-[app-name].git" | vercel git connect --yes
git commit --allow-empty -m "ci: trigger initial Vercel deployment"
npm run deploy

これを省略すると Vercel にプロジェクトが登録されず自動デプロイが走らない。

Dashboard カード追加
- posimai-dashboard/src/data/projects.json の projects 配列にエントリを追加
- 適切な category を設定（posimai-pwa / active / flagship / micro / infra など）
App Browser カテゴリに追加
- posimai-dashboard/src/app/apps/page.tsx の APP_CATEGORIES 配列から適切なカテゴリを選び projectIds に追加
- カテゴリ: input（インプット）/ routine（日次ルーティン）/ create（作成・記録）/ tools（ツール）/ business（ビジネス）/ infra（インフラ）/ ideas（アイデア）
- ここに追加しないと App Browser に表示されない（Ecosystem Map には出るが App Browser は別管理）
Ecosystem Map 追加
- posimai-dashboard/src/app/ecosystem/page.tsx の NODES 配列にノードを追加
- 関連する EDGES（依存関係）も追加
Development Timeline に追記
- posimai-dashboard/src/app/timeline/page.tsx の EVENTS 配列に今日の日付でエントリを追加
- type: launch（新規公開）/ feature（機能追加）/ fix（修正）/ infra（インフラ）
Access Guide に追記
- posimai-dashboard/src/app/access/page.tsx の APPS 配列にエントリを追加
- accessLevel / codevAccess / authDetail / codevNote を正確に記入する
Roadmap サイドバーに追加
- posimai-roadmap/roadmap.json の apps 配列に空エントリを追加する
```
{ "id": "posimai-[app-name]", "tasks": [] }
```
- 追加後にデプロイする（既存ユーザーの localStorage には自動マージされる）
```
cd posimai-roadmap
git add roadmap.json && git commit -m "feat: add posimai-[app-name] to roadmap" && npm run deploy
```

Dashboard をデプロイ

cd posimai-dashboard
git add src/data/projects.json src/app/apps/page.tsx 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

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

logo.png をデプロイする（ユーザーが logo.png を配置した後）

cd posimai-[app-name]
git add logo.png && git commit -m "chore: add logo" && npm run deploy

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

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

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

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

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

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

24 KiB Raw Blame History Unescape Escape