leanspec-development

LeanSpec 開発スキル

LeanSpec のすべての開発に関する統合ガイドです。コーディング、コマンド、公開、CI/CD、ランナーの調査を扱います。

クイックナビゲーション

目的	参照先
必須ルールと規約	RULES.md
変更履歴の形式とワークフロー	変更履歴（以下）
i18n ファイルの場所とパターン	I18N.md
モノレポの構成とパッケージ	STRUCTURE.md
リリースの完全なチェックリスト	PUBLISHING.md
npm 配布アーキテクチャ	NPM-DISTRIBUTION.md
開発版の公開ワークフロー	DEV-PUBLISHING.md
CI ワークフローの詳細	CI-WORKFLOWS.md
gh CLI コマンドリファレンス	CI-COMMANDS.md
CI のトラブルシューティング	CI-TROUBLESHOOTING.md
ランナーエコシステムカタログ	runners-catalog.md

基本原則

1. pnpm を使用する — npm や yarn は使用しないでください
2. DRY — 共通ロジックを抽出し、重複を避けてください
3. 重要な箇所をテストする — 表示ではなく、ビジネスロジックとデータの整合性をテストしてください
4. Turborepo を活用する — スマートキャッシュによりビルドを高速化します（19s → 126ms）
5. i18n は必須です — ユーザー向けの文字列はすべて en と zh-CN の両方に対応させてください（I18N.md を参照）
6. Rust の品質基準に従う — すべてのコードで cargo clippy -- -D warnings を通過する必要があります

---

コマンド

日常の開発

pnpm install              # Install dependencies
pnpm dev                  # Start web UI + Rust HTTP server
pnpm dev:watch            # Same + auto-rebuild Rust on changes
pnpm dev:web              # Start web UI only
pnpm dev:desktop          # Start desktop app
pnpm build                # Build all TS packages
pnpm build:rust           # Build Rust (debug)
pnpm build:rust:release   # Build Rust (release)
pnpm typecheck            # ← NEVER SKIP before marking work complete
pnpm test                 # Run all tests
pnpm test:watch           # Watch mode
pnpm test:coverage        # With coverage
pnpm test:rust            # Rust tests only
pnpm format               # Format all code
pnpm cli                  # Run LeanSpec CLI

検証

pnpm pre-push             # Quick: typecheck + clippy
pnpm pre-release          # Full: build + typecheck + test + lint

⚠️ 作業を完了とする前に、必ず pnpm typecheck を実行してください。

Rust

pnpm build:rust           # Debug build
pnpm build:rust:release   # Release build
pnpm check:rust           # Quick check without building
pnpm lint:rust            # Clippy with warnings as errors
pnpm format:rust          # Format Rust code
pnpm format:rust:check    # Check Rust formatting

# Low-level
cargo build --manifest-path rust/Cargo.toml
node scripts/copy-rust-binaries.mjs --debug

ドキュメント

pnpm docs:dev             # Start docs dev server
pnpm docs:build           # Build docs site

デスクトップ

pnpm dev:desktop          # Start desktop app in dev mode
cd packages/desktop
pnpm bundle:linux         # Debian package
pnpm bundle:macos         # DMG
pnpm bundle:windows       # NSIS installer

---

重要なルール

フックまたは CI によって適用されるルール：

1. ライト／ダークテーマ — すべての UI で両方のテーマをサポートする必要があります
2. i18n — en と zh-CN の両方を更新してください → I18N.md ⚠️ よく忘れられます
3. 回帰テスト — バグ修正には、失敗した後に成功するテストを必ず含めてください
4. Rust の品質 — cargo clippy -- -D warnings を通過する必要があります
5. Rust のパラメーター構造体 — 引数が 7 個を超える関数では、パラメーター構造体を使用する必要があります（clippy.toml によって適用されます）
6. shadcn/ui を使用する — 標準の HTML フォーム要素は使用しないでください
7. cursor-pointer — クリック可能な項目すべてで cursor-pointer を使用する必要があります

要件の全容は RULES.md を参照してください。

---

公開とリリース

本番リリース（推奨）

# 1. Update version (root only)
npm version patch  # or minor/major

# 2. Sync all packages
pnpm sync-versions

# 3. Validate everything
pnpm pre-release

# 4. Commit and push with tags
git add .
git commit -m "chore: release vX.X.X"
git push --follow-tags

# 5. Create GitHub Release (triggers publish workflow)
gh release create vX.X.X --title "vX.X.X" --notes "Release notes here"

開発版リリース

# Publish dev version via GitHub Actions
gh workflow run publish.yml --field dev=true

# Dry run (validates without publishing)
gh workflow run publish.yml --field dev=true --field dry_run=true

# Install and test
npm install -g lean-spec@dev
lean-spec --version

バージョン管理

• ルートの package.json をバージョンの唯一の情報源とします
• pnpm sync-versions ですべてのパッケージ（Rust クレートを含む）に反映します
• CI でバージョンの整合性が自動的に検証されます
• パッケージのバージョンを手動で編集しないでください — npm version と pnpm sync-versions を使用してください

配布アーキテクチャ

LeanSpec では、プラットフォーム固有の Rust バイナリにオプションの依存関係を使用しています。

種類	パッケージ
メイン（公開）	lean-spec、@leanspec/mcp、@leanspec/ui
プラットフォーム（公開）	@leanspec/cli-{platform}、@leanspec/mcp-{platform}（それぞれ 5 プラットフォーム）
内部（非公開）	@leanspec/desktop、@leanspec/ui-components

⚠️ メインパッケージより先に、プラットフォームパッケージを公開する必要があります。 CI ワークフローがこれを自動的に処理します。

詳細は PUBLISHING.md と NPM-DISTRIBUTION.md を参照してください。

---

変更履歴

Keep a Changelog の形式と セマンティックバージョニング に従って CHANGELOG.md を更新してください。

変更の確認

# Commits since last tag
git log $(git describe --tags --abbrev=0)..HEAD --oneline

# Files changed since last release
git diff $(git describe --tags --abbrev=0)..HEAD --stat

エントリーの形式

リリース済み／実装済みの変更のみを含めてください — 予定されている仕様、草案、作業中の項目は含めないでください。

Added、Changed、Fixed、Deprecated、Removed、Security、Technical のカテゴリを使用し、## [Unreleased] の下に追加してください。

- **Feature Name** ([spec 123](https://web.lean-spec.dev/specs/123)) - Brief description
  - Sub-bullet with implementation details

執筆スタイル

1. 機能名を太字にし、その後に説明を記載します
2. 該当する場合は、関連する仕様へのリンクを記載します
3. 現在形を使用します。「追加しました」ではなく「サポートを追加します」のように記載します
4. 具体的に記載します。コマンド名、フラグ名、コンポーネント名を含めます
5. 関連する変更は、1つの箇条書きにまとめ、その下にサブ箇条書きを記載します
6. 破壊的変更には Breaking: の接頭辞を付けます

リリースの作成

1. [Unreleased] の項目を新しいバージョンに移動します：## [X.Y.Z] - YYYY-MM-DD
2. 末尾にリリースリンクを追加します：[X.Y.Z]: https://github.com/codervisor/lean-spec/releases/tag/vX.Y.Z

---

CI/CD（GitHub Actions）

ワークフローの操作にはすべて gh CLI を使用します。新しい実行を開始する前にステータスを確認してください。ポーリングの間隔は最低30秒空けてください。

利用可能なワークフロー

ワークフロー	ファイル	トリガー	目的
CI	ci.yml	push、mainへのPR	ビルド、テスト、リンティング（Node.js + Rust）
Publish	publish.yml	リリース、手動	npmに公開（全プラットフォーム）
Desktop Build	desktop-build.yml	push、PR、手動	Tauriデスクトップアプリをビルド
Copilot Setup	copilot-setup-steps.yml	push、PR、手動	Copilotエージェント用の環境をセットアップ

クイックリファレンス

# Check status
gh run list --limit 10
gh run list --workflow ci.yml --limit 5
gh run view <run-id>
gh run watch <run-id>

# Trigger
gh workflow run ci.yml
gh workflow run publish.yml --field dev=true

# Debug failures
gh run view <run-id> --log-failed
gh run rerun <run-id> --failed

# Artifacts
gh run download <run-id>
gh run download <run-id> --name ui-dist

詳細については、CI-WORKFLOWS.md、CI-COMMANDS.md、CI-TROUBLESHOOTING.mdを参照してください。

---

ランナーの調査

エコシステムの進化に合わせてLeanSpecのランナーレジストリを最新の状態に保つため、AIエージェントランナーを調査します。

ワークフロー

1. 現在の状態を確認：rust/leanspec-core/src/sessions/runner.rs（RunnerRegistry::builtins()）
2. カタログを確認：runners-catalog.md
3. web_searchで調査：設定形式の変更、CLIの変更、新しい環境変数、新しい機能、非推奨化、新しいランナー
4. 比較して不足点を特定：調査結果をレジストリと照合します
5. 報告：小規模な更新はカタログに直接反映し、大規模な変更は仕様を作成します

ランナーのティア

1. ティア1（優先度高）：Claude Code、Copilot、Cursor、Windsurf、Codex、Gemini
2. ティア2（優先度中）：Kiro、Amp、Aider、Goose、Continue、Roo Code
3. ティア3（監視対象）：Droid、Kimi、Qodo、Trae、Qwen Code、OpenHands、Crush、CodeBuddy、Kilo、Augment

主なソースファイル

ファイル	目的
rust/leanspec-core/src/sessions/runner.rs	検出設定を含むランナーレジストリ
schemas/runners.json	カスタムランナー設定用のJSONスキーマ
packages/cli/templates/_shared/agents-components/	AGENTS.mdテンプレートコンポーネント