@aramassa/ai-rules 0.4.2 → 0.5.0

package/artifact/chatmodes/Planning.md

@@ -5,6 +5,7 @@ chatmode: planning
 tools:
   - "changes"
   - "searchResults"
+  - "createFile"
   - "editFiles"
   - "search"
   - "add_sub_issue"

package/artifact/instructions/rules/workspace-management/nodejs.md

@@ -0,0 +1,358 @@
+---
+type: package-management
+category: workspace
+language: nodejs
+applyTo: "**/package.json"
+human-instruction: |-
+  ## npm Workspaces の特性
+
+  npm workspaces は npm 7.0+ で利用可能な、単一リポジトリ内で複数のパッケージを管理する仕組みです。
+
+  特に注意すべき点：
+  - npm 7.0 以降が必須
+  - ワークスペース間の依存関係は自動的にシンボリックリンクされる
+  - `--workspace` フラグで特定のパッケージに対してコマンドを実行可能
+---
+
+# Node.js (npm) Workspace Management Rules
+
+## 目次
+
+- [Overview](#overview)
+- [Workspace Configuration](#workspace-configuration)
+- [Package Structure Rules](#package-structure-rules)
+- [Package Management Commands](#package-management-commands)
+- [Build and Development Workflow](#build-and-development-workflow)
+- [Local CLI Execution](#local-cli-execution)
+- [Package Distribution Check（必須）](#package-distribution-check必須)
+- [Common Issues](#common-issues)
+- [Best Practices](#best-practices)
+- [Example Project Structure](#example-project-structure)
+
+## Overview
+
+このルールでは **npm のみ** を使用します（yarn/pnpm は使用禁止）。
+
+npm workspaces（npm 7.0+）で単一リポジトリ内の複数パッケージを管理します。
+
+## Workspace Configuration
+
+ルートの `package.json`:
+
+```json
+{
+  "name": "my-monorepo",
+  "private": true,
+  "workspaces": ["packages/*"]
+}
+```
+
+## Package Structure Rules
+
+### 必須パッケージ
+
+| パッケージ名 | 説明 | 依存関係ルール |
+|:-----------|:-----|:-------------|
+| `core` | プロジェクトの主機能 | `common` に依存可能 |
+| `common` | 共有機能 | 他パッケージに依存不可 |
+
+### オプションパッケージ
+
+- `cli` - CLI（`core` に依存）
+- `types` - 型定義（依存なし）
+- `utils` - ユーティリティ（`common` に依存可能）
+
+### 依存関係のルール
+
+```
+common (依存なし)
+  ↑
+core (common に依存可能)
+  ↑
+cli, その他 (core, common に依存可能)
+```
+
+**禁止**: `core` が `cli` などに依存、`common` が他の内部パッケージに依存
+
+### テストのルール
+
+**重要**: 各パッケージのテストは、そのパッケージ内で完結する必要があります。
+
+- ✅ **許可される**: 自パッケージ内のコードのみをテスト
+- ✅ **許可される**: 依存しているパッケージ（`common`、`core`）の公開APIを使用
+- ❌ **禁止**: 他パッケージの内部実装に依存したテスト
+- ❌ **禁止**: テストのために他パッケージのテストヘルパーをインポート
+
+```bash
+# 各パッケージで独立してテスト実行可能
+cd packages/common && npm test  # common のテストのみ
+cd packages/core && npm test    # core のテストのみ
+cd packages/cli && npm test     # cli のテストのみ
+
+# 全体テストも実行可能
+npm test --workspaces
+```
+
+**ベストプラクティス**:
+- テストヘルパーやモックが必要な場合は、各パッケージ内に配置
+- 共通のテストユーティリティが必要な場合は、`common` または専用の `test-utils` パッケージを作成
+
+## Package Management Commands
+
+```bash
+# インストール
+npm install
+
+# パッケージ追加
+npm install <package> --workspace=packages/core
+npm install <package> --workspaces  # 全ワークスペース
+
+# ワークスペース間依存
+cd packages/core
+npm install @scope/common
+# → node_modules/@scope/common は packages/common へのシンボリックリンク
+```
+
+## Build and Development Workflow
+
+```bash
+# ビルド（依存順に手動実行推奨）
+cd packages/common && npm run build
+cd ../core && npm run build
+cd ../cli && npm run build
+
+# または全体ビルド
+npm run build --workspaces
+
+# 開発時 watch
+npm run dev --workspaces
+npm run dev --workspace=packages/core
+
+# テスト
+npm test --workspaces
+npm test --workspace=packages/core
+npm test --workspaces --if-present  # スクリプトがない場合スキップ
+```
+
+## Local CLI Execution
+
+```bash
+# 1. ビルド実行（必須）
+npm run build --workspaces
+
+# 2. CLI 実行
+node packages/cli/dist/index.js
+npx @scope/cli  # bin フィールドがある場合
+
+# 開発時リンク
+npm link --workspace=packages/cli
+my-cli --version
+npm unlink --workspace=packages/cli -g  # 解除
+
+# TypeScript 直接実行（開発時）
+npx tsx packages/cli/src/index.ts
+```
+
+## Package Distribution Check（必須）
+
+### コミット前・リリース前の確認
+
+```bash
+cd packages/core
+npm pack --dry-run
+
+# 出力例：
+# npm notice 📦  @scope/core@1.0.0
+# npm notice === Tarball Contents ===
+# npm notice 1.2kB  dist/index.js
+# npm notice 256B   package.json
+```
+
+### 除外設定
+
+`package.json` の `files` フィールド（推奨）:
+
+```json
+{
+  "files": ["dist", "README.md", "LICENSE"]
+}
+```
+
+または `.npmignore`:
+
+```
+src/
+*.test.ts
+*.spec.ts
+tsconfig.json
+```
+
+### 確認タイミング
+
+- ✅ 新機能追加時
+- ✅ リファクタリング後
+- ✅ コミット前（必須）
+- ✅ リリース前（必須）
+
+## Common Issues
+
+### 型定義が認識されない
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [{ "path": "../common" }]
+}
+```
+
+```bash
+npx tsc --build
+```
+
+### ローカル変更が反映されない
+
+```bash
+npm run build --workspaces
+# または watch モード
+npm run dev --workspaces
+```
+
+### 循環依存エラー
+
+```
+ERROR: Circular dependency detected:
+  @scope/core -> @scope/cli -> @scope/core
+```
+
+解決策:
+1. 依存関係ルールを確認
+2. 共通機能を `common` に移動
+
+### npm install が遅い
+
+```bash
+rm -rf node_modules packages/*/node_modules
+npm install
+# または CI 環境で
+npm ci
+```
+
+## Best Practices
+
+1. **ビルド前提**: CLI/スクリプト実行前に必ずビルド
+2. **依存管理**: `core` → `common` の一方向を守る
+3. **配布物確認**: `npm pack --dry-run` を徹底
+4. **private 設定**: ルートの package.json に `"private": true"`
+5. **TypeScript**: プロジェクト参照で型定義を共有
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── package.json              # workspaces 定義、private: true
+├── package-lock.json
+├── node_modules/
+├── packages/
+│   ├── common/
+│   │   ├── package.json      # @scope/common
+│   │   ├── src/
+│   │   └── dist/
+│   ├── core/
+│   │   ├── package.json      # @scope/core
+│   │   ├── src/
+│   │   └── dist/
+│   └── cli/
+│       ├── package.json      # @scope/cli
+│       ├── src/
+│       └── dist/
+└── tsconfig.json
+```
+
+### 除外確認のタイミング
+
+- ✅ 新機能追加時
+- ✅ リファクタリング後
+- ✅ コミット前（必須）
+- ✅ リリース前（必須）
+
+## Common Issues and Solutions
+
+### Issue: ワークスペース間の型定義が認識されない
+
+```bash
+# 解決方法: TypeScript のプロジェクト参照を設定
+# packages/core/tsconfig.json
+{
+  "references": [
+    { "path": "../common" }
+  ]
+}
+
+# ビルド時に --build フラグを使用
+npx tsc --build
+```
+
+### Issue: ローカルパッケージの変更が反映されない
+
+```bash
+# 解決方法: ビルドを再実行
+npm run build --workspaces
+
+# または watch モードで開発
+npm run dev --workspaces
+```
+
+### Issue: パッケージの循環依存
+
+```
+ERROR: Circular dependency detected:
+  @scope/core -> @scope/cli -> @scope/core
+```
+
+解決方法:
+1. 依存関係ルールを確認（`core` は `cli` に依存してはいけない）
+2. 共通機能を `common` に移動
+3. アーキテクチャを見直し
+
+### Issue: npm install が遅い
+
+```bash
+# node_modules をクリーンアップ
+rm -rf node_modules packages/*/node_modules
+npm install
+
+# または npm ci を使用（CI環境推奨）
+npm ci
+```
+
+## Best Practices
+
+1. **ビルド前提の実行**: CLI やスクリプトを実行する前に必ずビルドを実行
+2. **厳格な依存関係管理**: `core` → `common` の一方向依存を守る
+3. **型定義の共有**: TypeScript プロジェクト参照を活用
+4. **配布物の確認**: `npm pack --dry-run` でリリース前確認を徹底
+5. **private フラグ**: ルートの package.json には `"private": true` を設定
+6. **バージョン管理**: 各パッケージのバージョンを適切に管理
+
+## Example Project Structure
+
+```
+my-monorepo/
+├── package.json              # ルート設定（workspaces 定義、private: true）
+├── package-lock.json         # ロックファイル
+├── node_modules/             # すべてのパッケージの依存関係
+├── packages/
+│   ├── common/
+│   │   ├── package.json      # @scope/common
+│   │   ├── src/
+│   │   └── dist/             # ビルド成果物
+│   ├── core/
+│   │   ├── package.json      # @scope/core（common に依存）
+│   │   ├── src/
+│   │   └── dist/
+│   └── cli/
+│       ├── package.json      # @scope/cli（core, common に依存）
+│       ├── src/
+│       └── dist/
+└── tsconfig.json             # ルート TypeScript 設定
+```

package/artifact/instructions/{python/workspace-management.md → rules/workspace-management/python.md}

@@ -184,7 +184,7 @@ if ! command -v uv &> /dev/null; then
     echo "📦 Installing uv..."
     curl -LsSf https://astral.sh/uv/install.sh | sh
     source $HOME/.cargo/env
-    
+
     # Verify installation
     if ! command -v uv &> /dev/null; then
         echo "❌ Failed to install uv. Please install manually."
@@ -547,21 +547,21 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    
+
     - name: Install uv
       uses: astral-sh/setup-uv@v1
       with:
         version: "latest"
-    
+
     - name: Set up Python ${{ matrix.python-version }}
       run: uv python install ${{ matrix.python-version }}
-    
+
     - name: Install dependencies
       run: uv sync --dev
-    
+
     - name: Run quality checks
       run: ./scripts/check-quality.sh
-    
+
     - name: Upload coverage reports
       uses: codecov/codecov-action@v3
       if: matrix.python-version == '3.11'
@@ -575,16 +575,16 @@ jobs:
    ```bash
    # 1. 開発環境更新
    uv sync --dev
-   
+
    # 2. 品質チェック
    ./scripts/check-quality.sh
-   
+
    # 3. 実装
    # ... コード変更 ...
-   
+
    # 4. テスト実行
    uv run pytest packages/target-package/tests/
-   
+
    # 5. 最終品質チェック
    ./scripts/check-quality.sh
    ```
@@ -649,7 +649,7 @@ uv run mypy packages/target-package/ --show-error-codes
    ```bash
    # poetry.lock から requirements.txt 生成
    poetry export --output requirements.txt
-   
+
    # UV での依存関係インストール
    uv add $(cat requirements.txt | cut -d'=' -f1)
    ```
@@ -670,4 +670,4 @@ uv run mypy packages/target-package/ --show-error-codes
 - [ ] 品質チェックがパス
 - [ ] CI/CD パイプラインが動作
 
-このガイドラインに従うことで、保守性が高く、開発効率の良い Python プロジェクトを UV workspace で管理できます。
+このガイドラインに従うことで、保守性が高く、開発効率の良い Python プロジェクトを UV workspace で管理できます。

package/artifact/instructions/rules/workspace-management/typescript.md

@@ -0,0 +1,337 @@
+---
+type: package-management
+category: workspace
+language: typescript
+applyTo: "**/tsconfig.json"
+human-instruction: |-
+  ## TypeScript Project References の特性
+
+  TypeScript のプロジェクト参照（Project References）は、複数のパッケージ間での型情報共有とビルド最適化を実現する仕組みです。
+
+  特に注意すべき点：
+  - `references` フィールドでパッケージ間の依存関係を明示する
+  - `composite: true` を設定することで、プロジェクト参照が有効になる
+  - `tsc --build` コマンドで依存関係を考慮した段階的ビルドが可能
+---
+
+# TypeScript Workspace Management Rules
+
+## 目次
+
+- [Overview](#overview)
+- [TypeScript Configuration](#typescript-configuration)
+- [Project References](#project-references)
+- [Build Strategy](#build-strategy)
+- [Type Definition Management](#type-definition-management)
+- [Common Issues](#common-issues)
+- [Best Practices](#best-practices)
+
+## Overview
+
+このドキュメントは **TypeScript Project References** に特化したルールです。
+
+基本的なワークスペース管理については [nodejs.md](./nodejs.md) を参照してください。
+
+## TypeScript Configuration
+
+### Root tsconfig.json
+
+ルートの `tsconfig.json` は共通設定を定義します：
+
+```json
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "commonjs",
+    "lib": ["ES2020"],
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "composite": true,
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true
+  },
+  "exclude": ["node_modules", "dist"]
+}
+```
+
+### Package-level tsconfig.json
+
+各パッケージの `tsconfig.json`:
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    { "path": "../common" }
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts"]
+}
+```
+
+## Project References
+
+### 依存関係の定義
+
+パッケージ間の依存関係は `references` フィールドで明示します：
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [
+    { "path": "../common" }
+  ]
+}
+```
+
+```json
+// packages/cli/tsconfig.json
+{
+  "references": [
+    { "path": "../common" },
+    { "path": "../core" }
+  ]
+}
+```
+
+### composite フラグ（必須）
+
+プロジェクト参照を有効にするため、各パッケージで `composite: true` を設定：
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true
+  }
+}
+```
+
+**composite: true の効果**:
+- `.d.ts` ファイル（型定義）の生成を強制
+- `tsconfig.tsbuildinfo` ファイルによる段階的ビルドの有効化
+- プロジェクト参照による高速な型チェック
+
+## Build Strategy
+
+### 推奨ビルドコマンド
+
+```bash
+# TypeScript の段階的ビルド（推奨）
+npx tsc --build
+
+# watch モード（開発時）
+npx tsc --build --watch
+
+# クリーンビルド
+npx tsc --build --clean
+npx tsc --build
+```
+
+### package.json の scripts
+
+```json
+{
+  "scripts": {
+    "build": "tsc --build",
+    "build:clean": "tsc --build --clean",
+    "build:watch": "tsc --build --watch"
+  }
+}
+```
+
+## Type Definition Management
+
+### 型定義の export
+
+各パッケージで型定義を適切に export します：
+
+```typescript
+// packages/common/src/index.ts
+export type { CommonConfig } from './types';
+export { createCommon } from './common';
+```
+
+```json
+// packages/common/package.json
+{
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": ["dist"]
+}
+```
+
+### 型定義の import
+
+```typescript
+// packages/core/src/index.ts
+import type { CommonConfig } from '@scope/common';
+import { createCommon } from '@scope/common';
+
+export function createCore(config: CommonConfig) {
+  const common = createCommon(config);
+  // ...
+}
+```
+
+### 共有型定義パッケージ
+
+プロジェクト全体で使用する型定義は `types` パッケージに集約：
+
+```typescript
+// packages/types/src/index.ts
+export type ProjectConfig = {
+  name: string;
+  version: string;
+};
+
+export type Result<T, E = Error> =
+  | { success: true; data: T }
+  | { success: false; error: E };
+```
+
+## Common Issues
+
+### 型定義が認識されない
+
+**原因**: プロジェクト参照の設定漏れ
+
+```json
+// packages/core/tsconfig.json
+{
+  "references": [{ "path": "../common" }],
+  "compilerOptions": {
+    "composite": true
+  }
+}
+```
+
+```bash
+npx tsc --build
+```
+
+### ビルドエラー: "Project references may not form a circular chain"
+
+**原因**: 循環参照（`core` → `cli` → `core`）
+
+解決策: 依存関係を見直し、共通機能を `common` に移動
+
+### import の型解決ができない
+
+**原因**: `declaration: true` の設定漏れ
+
+```json
+{
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true
+  }
+}
+```
+
+## Best Practices
+
+1. **composite フラグの徹底**: 全パッケージで `composite: true` を設定
+2. **型定義の明示的 export**: 公開する型は必ず `export type` で export
+3. **段階的ビルドの活用**: `tsc --build` でビルド時間を短縮
+4. **declarationMap の活用**: デバッグ時にソースコードにジャンプ可能
+5. **tsconfig の継承**: 共通設定はルートで定義して `extends` で継承
+
+### tsconfig.json テンプレート
+
+```json
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    // 依存するパッケージのパスを記載
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+### Example Project Structure
+
+```
+my-monorepo/
+├── tsconfig.json             # ルート設定
+├── packages/
+│   ├── types/
+│   │   ├── tsconfig.json     # composite: true
+│   │   └── src/index.ts
+│   ├── common/
+│   │   ├── tsconfig.json     # references: [types]
+│   │   └── src/index.ts
+│   ├── core/
+│   │   ├── tsconfig.json     # references: [types, common]
+│   │   └── src/index.ts
+│   └── cli/
+│       ├── tsconfig.json     # references: [types, common, core]
+│       └── src/index.ts
+└── tsconfig.tsbuildinfo      # ビルドキャッシュ（.gitignore）
+```
+
+## Related Documentation
+
+- [Node.js Workspace Management](./nodejs.md) - npm workspaces の基本ルール
+  "compilerOptions": {
+    "composite": true,
+    "declaration": true,
+    "declarationMap": true,
+    "outDir": "./dist",
+    "rootDir": "./src"
+  },
+  "references": [
+    // 依存するパッケージを記載
+  ],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+### Example Project Structure
+
+```
+my-monorepo/
+├── tsconfig.json             # ルート設定
+├── package.json
+├── packages/
+│   ├── types/
+│   │   ├── tsconfig.json     # composite: true
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   ├── common/
+│   │   ├── tsconfig.json     # references: [types]
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   ├── core/
+│   │   ├── tsconfig.json     # references: [types, common]
+│   │   ├── package.json
+│   │   └── src/
+│   │       └── index.ts
+│   └── cli/
+│       ├── tsconfig.json     # references: [types, common, core]
+│       ├── package.json
+│       └── src/
+│           └── index.ts
+└── tsconfig.tsbuildinfo      # ビルドキャッシュ（gitignore）
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aramassa/ai-rules",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "This repository collects guidelines and instructions for developing AI agents. It contains documents covering communication rules, coding standards, testing strategies, and general operational practices.",
   "workspaces": [
     "packages/extract",

package/presets/monorepo/nodejs.yaml

@@ -0,0 +1,14 @@
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - title: Node.js Workspace Management Rules
+    frontmatter:
+      description: |
+        Rules for managing npm workspaces in a monorepo environment.
+        This includes package structure, dependency management, and build workflows.
+      applyTo: "**/package.json"
+    out: nodejs-workspace.instructions.md
+    type: package-management
+    category: workspace
+    language: nodejs

package/presets/monorepo/typescript.yaml

@@ -0,0 +1,25 @@
+config:
+  baseDir: .github/instructions
+
+recipe:
+  - title: Node.js Workspace Management Rules
+    frontmatter:
+      description: |
+        Rules for managing npm workspaces in a monorepo environment.
+        This includes package structure, dependency management, and build workflows.
+      applyTo: "**/package.json"
+    out: typescript-workspace.instructions.md
+    type: package-management
+    category: workspace
+    language: nodejs
+  - title: TypeScript Workspace Management Rules
+    mode: append
+    frontmatter:
+      description: |
+        Rules for managing TypeScript project references in a monorepo environment.
+        This includes tsconfig configuration, project references, and type definition management.
+      applyTo: "**/tsconfig.json"
+    out: typescript-workspace.instructions.md
+    type: package-management
+    category: workspace
+    language: typescript