agentleFS
ianlkl11234sianlkl11234s/mini-taiwan-pulse/CLAUDE.md

mini-taiwan-pulse

CLAUDE.md547 starsChanged 9 days agoMITView on GitHub

React 19 + TypeScript + Vite (port 3721) · Mapbox GL + Three.js · Supabase (gis-platform) 詳細版規則見 docs/development-rules.md 與全域準則的優先級:全域 ~/.claude/CLAUDE.md 已含通用開發準則(Think Before Coding / Simplicity / Surgical / Goal-Driven);本檔為專案具體化規則,衝突時以下方為準(特別是 Simplicity 對「新增 Layer 7 步驟 + UX 四鐵則」、Surgical 對「跨檔 register 多處」的例外)。不確定算不算違反專案鐵則時,先問用戶。 主題經驗總集(踩坑、best practice、網站哲學、小實驗)先看 docs/LESSONS.md,新教訓寫進正本後在那裡加一行。SessionStart hook 只提供短路由,不預載 STATUS/BACKLOG/PRINCIPLES。有接手需求才依 .claude/memory/README.md 查相關段落;似曾相識的 bug 搜 .claude/pitfalls/。明確收尾時依 wrap-up 的 scope/evidence/release matrix 留本次紀錄,提交/發布沿用各自授權。框架機制按需查 .claude/FRAMEWORK.md。現況入口是 docs/PROJECTS.md(先讀上半部的進行中/待拍板,細節再查 BACKLOG 對應主題群)。 commit 前必跑 npm run verify(tsc -b、lint、樣式盤點、相關測試;project references,禁用 --noEmit)。完整套件由 CI 跑,合併前等 CI 綠;不要在本機重跑一次全套(2026-11-08 使用者決定,原則見 docs/ci.md §5)。 資料不會變或只會整批替換 → PMTiles/R2,不進 Supabase;新 Supabase…

  • Commits and pushes

The file

We split this CLAUDE.md into the rules it gives an agent

1 rule. About 0 are common, 0 are distinctive, and 1 is very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈0

    Distinctive · estimate

    This author's own choices. Worth a look.

  • 1

    Very specific

    Tied to their project's names, files or tools. Probably skip.

  • Common
  • Distinctive
  • Very specific
  1. Very specific:

    commit 遵循 Conventional Commits;本專案特例 memory: 用於 .claude/memory 更新

    line 69

≈ “Common” is an estimate: at least 1 in 5 of the 28,029 CLAUDE.md files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
CLAUDE.md

Mini Taiwan Pulse — 開發規則

React 19 + TypeScript + Vite (port 3721) · Mapbox GL + Three.js · Supabase (gis-platform)

詳細版規則見 docs/development-rules.md

與全域準則的優先級:全域 ~/.claude/CLAUDE.md 已含通用開發準則(Think Before Coding / Simplicity / Surgical / Goal-Driven);本檔為專案具體化規則,衝突時以下方為準(特別是 Simplicity 對「新增 Layer 7 步驟 + UX 四鐵則」、Surgical 對「跨檔 register 多處」的例外)。不確定算不算違反專案鐵則時,先問用戶。

Session 記憶迴圈

主題經驗總集(踩坑、best practice、網站哲學、小實驗)先看 docs/LESSONS.md,新教訓寫進正本後在那裡加一行。SessionStart hook 只提供短路由,不預載 STATUS/BACKLOG/PRINCIPLES。有接手需求才依 .claude/memory/README.md 查相關段落;似曾相識的 bug 搜 .claude/pitfalls/。明確收尾時依 wrap-up 的 scope/evidence/release matrix 留本次紀錄,提交/發布沿用各自授權。框架機制按需查 .claude/FRAMEWORK.md。現況入口是 docs/PROJECTS.md(先讀上半部的進行中/待拍板,細節再查 BACKLOG 對應主題群)。

常用指令

指令用途
npm run dev啟動 dev server (port 3721)
npm run verifycommit/PR 前必跑:型別、lint、樣式盤點,加上和 origin/develop 相比有改動的測試(約 1 分內);全套交給 CI
npm run check依序跑 CI 的全部檢查(lint、樣式盤點、coral、worker、build、test);CI 紅燈要在本機重現時才用
npm run lint只跑 ESLint 守門規則(自訂規則見 development-rules §6);修掉既有違規後跑 npm run lint:prune
npx tsc -bTypeScript 驗證(禁用 --noEmit)
npm test跑測試(含 layerConsistency 擋漏接圖例;owner-local 測試用 npm run test:owner)
/new-layer <name>新增 layer 骨架(強烈建議走,免漏 manifest/spec/邏輯檔三步 + 四鐵則)
/check-rpc <name>自動 EXPLAIN 判斷 RPC 效能

必守規則

1. TypeScript 驗證

commit 前必跑 npm run verify(tsc -b、lint、樣式盤點、相關測試;project references,禁用 --noEmit)。完整套件由 CI 跑,合併前等 CI 綠;不要在本機重跑一次全套(2026-11-08 使用者決定,原則見 docs/ci.md §5)。

2. 資料來源管理

資料來源契約(動態走 public.* RPC / Statistics 一律走 R2 snapshot / 靜態走 CDN 資產 / 禁前端直打 live.*(舊 realtime schema 已併入 live))→ docs/development-rules.md §1

資料不會變或只會整批替換 → PMTiles/R2,不進 Supabase;新 Supabase 表必登記保留期限+S3 正本。 網站結構與各儲存職責正本:GIS .gis-agent-system/decisions/0026-pulse-architecture-and-data-placement.md(ADR-0026)。

統計新增/整合/UI 調整另見 統計圖層規則:配色與 icon 使用共用規則,保留來源語意,同步補齊資料來源總覽,包含原始與衍生選項。

3. 資料載入必須有 Loading UI ⚠️

所有非同步載入必註冊 loadingRegistry,禁靜默 .rpc().then() → development-rules §2

4. 資料庫優化(Pre-aggregate Pattern)

RPC >1s 或 >10k rows 必套 pre-aggregate → docs/supabase-optimization.md + /supabase-optimize skill + /check-rpc。DB 效能鐵則 R1–R4(前端 RPC 冷快取 <300ms/上限 1s、預算表要登記讀者、排程只算增量、監控不掃表)正本在該檔 §0,gis-platform CI 與每週體檢會擋

5. 新增 Layer 強制順序 ⚠️

新增 Layer → /new-layer 產骨架 + layer-onboarding skill 驗收;接線順序見 development-rules §4。 AR-22 Phase 4 起登記簿不再手寫:一筆 layerManifest.ts entry + 一筆 layerParamsSpec.ts 規格派生 6 張表,你只寫實質邏輯(loader / hook / overlay)。layerConsistency 測試驗 manifest 完整性(沒 entry / 欄位空殼 / 用 null 靜默豁免鐵則 → 紅)。

5a. 圖層 UX 四鐵則(⚠️ 缺一不可)

圖層 UX 四鐵則(opacity / 圖例 / popup / select)→ development-rules §4a + layer-onboarding Step 3-4

5b. 新資料層 Agent 查詢關卡

新圖層:在 pulse-data registry 有 warehouse 區塊、並經發包與組裝上線(ADR-0023,流程見 layer-onboarding)即為 L2 可分析,詳見 PLAN-warehouse-20260926。系統驗收以已接受來源版本為基準,確認查詢與計算忠實使用原座標;來源定位的真實世界限制要標示,但不因一般不確定性反覆重審既有資料。地圖可見不等於分析可用;純展示、權利或幾何受限者明標 DISPLAY_ONLY/HOLD 與解鎖條件。

6. 動態圖層時間訂閱(⚠️ 強制)

動態圖層禁止把 currentTime 放進 deps,一律走 timeStore 訂閱 → development-rules §8(正本)+ docs/TIMELINE_ARCHITECTURE.md

7. UI 規範(Design System)⚠️

任何 UI 改動(面板、popup、控制項、樣式表)必須遵守 docs/design-system/spec.md(PR 前照 §8 checklist)。npm run lint 的 pulse/design-*(TS/TSX 與 CSS)紅燈要修程式碼,不可用改基準繞過;只有違規確實減少時才跑 npm run lint:prune 降低基準。

Git Workflow(develop → master,2026-10-04 起)

  • develop 是所有 PR 的 base(gh pr create --base develop);master = 正式站,只收 develop 的發布合併與 hotfix/*。GitHub 預設分支已是 develop(2026-10-04 起)。
  • develop → master 會觸發 Cloudflare Worker 正式部署(.github/workflows/deploy-workers.yml),須使用者拍板;發布步驟、版號(SemVer)、tag 與 GitHub Release → docs/RELEASING.md
  • 每個 user-facing PR 在根目錄 CHANGELOG.md 的 ## [Unreleased] 加一行
  • 保留完整 commit 歷史:使用一般 merge commit(gh pr merge --merge);禁止 squash merge 或 rebase merge(使用者 2026-09-15 指示)。未經明確要求,不壓縮、合併或改寫既有 commit。
  • branch 命名 / PR 流程 / hotfix 判準 → docs/git-workflow.md
  • PR 描述用 .github/pull_request_template.md(gh pr create 自動帶入)
  • commit 遵循 Conventional Commits;本專案特例 memory: 用於 .claude/memory 更新

跨 repo 同步順序(有資料契約變動時)

上游先動、下游後動:

  1. taipei-gis-analytics:pipeline 改 + docs/handoff/<slug>.md 更新 + push
  2. gis-platform:migration 補 + push
  3. data-collectors:若涉 collector 改 + push
  4. mini-taiwan-pulse:前端接線 + docs/features/<slug>/handoff.md 反向引用 + PR 到 develop(上游部署完才發布到 master)

反向亂序會造成「上線時前端硬依賴的欄位不存在」。

目錄規則

用途位置
Supabase fetchersrc/data/*Loader.ts
Layer hooksrc/hooks/use*Layer.ts
Three.js scenesrc/three/*Scene.ts
Custom WebGL layersrc/map/*CustomLayer.ts
靜態 GeoJSON / PMTilespublic/<domain>/;URL 與 manifest source 是契約,既有資產不可任意搬路徑
預處理腳本scripts/preprocess/
S3 部署腳本scripts/deploy/
外部 API fetchscripts/fetch/
DB 匯出scripts/export/

環境變數

變數用途
VITE_SUPABASE_URL / VITE_SUPABASE_ANON_KEY前端
SUPABASE_SERVICE_ROLE_KEY腳本(禁止進 bundle)
SUPABASE_DB_URLpsql 直連
VITE_DATA_SOURCE=supabase啟用 Supabase(否則用 Pulse API)

相關資源

類型路徑用途
經驗docs/LESSONS.md主題經驗總集(主入口)
進度docs/PROJECTS.md專案追蹤總表(做到一半的專案)
規則docs/development-rules.md詳細版 + 範例(含 §4a 四鐵則完整)
規則docs/supabase-optimization.mdPre-aggregate pattern 完整指南 + OOM 5 條
規則docs/ci.mdCI 原則:job 結構、何時跳過、加速取捨、本機與 CI 分工
規則docs/TIMELINE_ARCHITECTURE.md時間軸 / timeStore 架構
參考docs/audit/supabase-rpc-audit-2026-04-09.mdRPC 效能盤點
參考docs/features/bus/design.md公車 progress-based 全台擴展
參考.claude/memory/INCIDENTS.md歷史 bug + 診斷指令(舊 known-issues 已併入,2026-10-16)
參考docs/research/決策軌跡 / 跨系統比對 / 故事 cookbook
關聯 repo../gis-platformSupabase migrations
關聯 repo../data-collectors資料收集 + SQL 範本
關聯 repo../pulse-apiFastAPI 備援(已停用,2026-04 起無 commit)
關聯 repo../mini-taipei-v3鐵道資料來源

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

  • It worked
  • Partly
  • It didn't
What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.