react-scroll-pkgs/.cursorrules at main · kubo-hide-kun/react-scroll-pkgs · GitHub

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
# Project: react-scroll-pkgs (Turborepo monorepo)
# OSS Project: Open source, Japanese developer, international audience
# Structure:
# - apps/website : demo / docs site
# - packages/*   : publishable libraries
# Tooling: turbo.json, husky, commitlint, prettier
#
# Language Note:
# - This file is in Japanese for Japanese developers
# - Public documentation should be in English
# - Agent-facing docs (.serena/memories/) are in English for international compatibility

## Scope rules
- 変更対象を最小化する。apps と packages をまたぐ変更は「必要性」を先に説明してから実施。
- パッケージ公開（npm publish）に影響する変更は、package.json / exports / build 影響を明示してから実装。
- lockfile（package-lock.json）は、依存追加・更新がない限り触らない。

## Coding rules
- TypeScript/React を優先。
- 既存の Prettier 設定に従う（singleQuote: true, arrowParens: always）。フォーマットは prettier を正とし、手整形で流儀を変えない。
- public API 変更（関数シグネチャ、export、挙動変更）は「互換性」「移行手順」「リリース種別（patch/minor/major）」を必ずコメントで残す。

## Turbo workflow
- コマンドは turbo 経由を優先:
  - `turbo run build` - 全パッケージのビルド（依存関係を考慮）
  - `turbo run lint` - 全パッケージのリント
  - `turbo run lint:fix` - 全パッケージのリント自動修正
  - `turbo run typecheck` - 全パッケージの型チェック
  - `npm run website` - デモサイトの起動（`npm run dev -w website`）
- プロジェクトに定義がなければ package 単位で実行。

## Published packages
- `react-scroll-flip-book` (v1.0.2): React Hook for scroll flip book functionality
  - npm: https://www.npmjs.com/package/react-scroll-flip-book
  - インストール: `npm install react-scroll-flip-book`
- `use-window-scroll-in-element` (v1.1.1): React Hook for get window position of element
  - npm: https://www.npmjs.com/package/use-window-scroll-in-element
  - インストール: `npm install use-window-scroll-in-element`
- これらのパッケージの変更は、GitHub Actions の公開ワークフロー（`publish-component.yml`, `publish-hooks.yml`）に影響する。

## Project links
- GitHub: https://github.com/kubo-hide-kun/react-scroll-pkgs
- デモサイト: https://react-scroll-pkgs.vercel.app/ (Vercel でホスティング)
- npm パッケージ:
  - https://www.npmjs.com/package/react-scroll-flip-book
  - https://www.npmjs.com/package/use-window-scroll-in-element

## PR/commit hygiene
- commitlint 前提：conventional commits 形式でメッセージ案も提示する。
- scope は必須（`all` またはパッケージ名）。例: `feat(react-scroll-flip-book): add new feature`
- 変更後は必ず "型チェック / lint / build / 最低限の動作確認" の結果を箇条書きで報告する。

## Build & Publish workflow
- 各パッケージは `prepublishOnly` スクリプトで自動ビルドされる。
- ビルド出力: `lib/` ディレクトリ（TypeScript コンパイル結果）
- 公開ファイル: `lib/`, `LICENSE` のみ（`files` フィールドで制御）
- GitHub Actions は `npm run build` → `npm publish -w <package-name>` の順で実行される。

## Output format
- まず「計画（最大5ステップ）」→「差分」→「検証結果」→「残リスク」の順で回答する。

## MCP (Model Context Protocol) 活用
- **MCP をフル活用すること**: このプロジェクトでは複数の MCP Server が設定されているため、可能な限り MCP ツールを活用する。
- **利用可能な MCP Servers**:
  - `playwright`: ブラウザ自動化とビジョン機能。Web アプリケーションの動作確認や E2E テストに使用。
  - `chrome-devtools`: Chrome DevTools Protocol を使用したブラウザデバッグ。パフォーマンス分析やデバッグに使用。
  - `serena`: プロジェクトコンテキスト対応の IDE アシスタント。コード検索やシンボル操作に使用。
  - `cipher`: ローカルエンベッダー。コードの意味理解や検索に使用。
- **MCP 使用の優先順位**:
  1. コード検索・シンボル操作: `serena` を優先的に使用
  2. Web アプリケーションの動作確認: `playwright` または `chrome-devtools` を使用
  3. コードの意味理解: `cipher` を活用
  4. 従来のツール（grep、read_file など）は、MCP で対応できない場合のみ使用
- **ブラウザ操作が必要な場合**: `apps/website` の動作確認やデモの検証時は、必ず `playwright` または `chrome-devtools` を使用して実際のブラウザで確認する。

## Validation checklist (実行順序固定)
1. `turbo run lint` - リントエラーの確認
2. `turbo run typecheck` - 型エラーの確認
3. `turbo run build` - ビルド成功の確認（publish ワークフローを壊さないための最重要）
4. `apps/website` の動作確認（デモが壊れていないか）- **MCP の `playwright` または `chrome-devtools` を使用してブラウザで確認**