@aramassa/ai-rules 0.1.1-npmjs.20250910072942

package/artifact/instructions/rules/coding/typescript.md

@@ -0,0 +1,92 @@
+---
+type: coding-rules
+language:
+  - typescript
+  - nodejs
+---
+## ドキュメント & ツール
+
+- コードコメントは **TSDoc** 形式で記述し、TypeDoc で API ドキュメントを自動生成する。
+- 図解する場合は、Mermaid を使用する。
+  - 人間が１分で理解できる程度の抽象度で図解する
+- `.editorconfig`, `.npmrc`, `.vscode/settings.json`
+  をリポジトリにコミットし、開発環境差分を減らす。
+
+## アーキテクチャ指針
+
+- **依存性逆転 (DIP)**:
+  Domain から外部サービスに直接依存しない。ポート＆アダプター (Hexagonal) を採用する。
+- **Config‑as‑Code**: 環境差分は `config/`
+  の設定ファイルに集約し、dotenv で注入する。API キーやシークレットは Secret Manager で管理する。
+- **CQRS / Event‑Driven** を検討し、読み取り専用サービスのスケーラビリティを高める。
+
+## コーディングスタイル
+
+## 基本方針
+
+- ESM 形式で書く。
+- 可能な限り `class` を利用する。
+  - メソッドは可能な限りアトミックにし、単一責任を守る。
+- TypeScript の型システムをフル活用し、型安全なコードを書く。
+- メソッドやプロパティの可視性は必ず設定し、不必要に公開範囲を広げない。
+- インターフェースを明確にし、共通化できるところは共通化する。
+  - Factory パターンや Strategy パターンも使えるところでは使う。
+
+- `eslint` + `@typescript-eslint` + `prettier` の導入と設定は**必須**。Airbnb
+  TypeScript ルールをベースに整形・静的解析を自動化する。
+- 新規プロジェクト作成時は必ず ESLint/Prettier の設定ファイル（.eslintrc.json, .prettierrc）を作成すること。
+- 変数は再代入が不要な限り `const` を使用し、`var` は禁止とする。
+- `async/await` を優先し、Promise チェーンやコールバックの多用を避ける。
+- 公開 API（export される関数・クラス メソッド）は必ず戻り値の型を明示する。
+- マジックナンバー／マジックストリングを禁止し、`const enum`
+  または設定ファイル・専用の定数オブジェクトに切り出して一元管理する。
+  - 例: logger 設定値や API エンドポイント、日付パターン、ファイルサイズなどは
+    `src/utils/loggerConfig.ts` のような専用ファイルで管理する。
+  - 既存コードで直値が使われている場合は、リファクタリング時に必ず定数化・集約を行うこと。
+- 関数は 20 行以内、クラスは 400 行以内を目安とし、循環的複雑度 (cyclomatic
+  complexity) は 10 未満に抑える。
+- コンポジションを優先し、継承は必要最小限（例: サードパーティ API の拡張）にとどめる。
+- Top‑level await はエントリポイント以外で使用しない。
+- 非同期エラーは `Result<T, E>` パターンまたは独自の `TypedError` クラスでラップし、`throw` するのは
+  `Error` 派生クラスに限定する。
+- `process.exit` の使用は極力避け、正常終了・異常終了の制御は例外処理やエラーハンドリングで行うこと
+- **必須ツール**: `npx prettier --write .` でコードを整形する。
+- **必須ツール**: `npx eslint . --fix` で静的解析と自動修正を行う。
+- `npx tsc --noEmit` で型チェックを行う。
+
+## エラー処理とロギング
+
+- エラーハンドリングは `try/catch` または `Error Boundary` で捕捉し、必ず `logger.error`
+  でスタックトレースを出力する。
+
+## ビルド・テスト方針
+
+### 必須ワークフロー
+
+- **コード修正後の必須チェック**: コード変更を行った後は、package.json の scripts セクションで定義されたコマンドを順次実行すること
+  - プロジェクトのビルドコマンド（TypeScript コンパイル、workspace ビルド等）
+  - 全テストの実行コマンド
+  - workspace 環境での全テスト実行コマンド
+  - 完全ビルドコマンド（バンドル処理含む）
+
+  ※ 具体的なコマンドは package.json の scripts セクションから確認し、プロジェクト固有の設定に従うこと
+
+- **コミット前の必須確認**: Gitコミット前には必ず以下を確認すること
+  1. ビルドが成功し、コンパイルエラーがないこと
+  2. 全テストが通過すること
+  3. パッケージ品質が維持されていること（パッケージング確認コマンド実行）
+  4. `.npmignore` が適切に設定されていること
+
+## テスト方針
+
+- **TDD ファースト**: ユースケース単位で `describe → it` を書いてから実装する。
+- **Unit Test**: vitest、80% 以上の branch coverage を目標とする。
+- テスト用にファイルが必要な場合は、テストケース内で実行時に作るのではなく、予め `test/fixtures/`
+  に作成しておくこと。
+- テストはdockerが使える環境では docker コンテナ上で実行すること。
+
+```sh
+rm -rf node_modules package-lock.json
+docker run --rm -v $(pwd):/app -w /app node:20 npm install
+docker run --rm -v $(pwd):/app -w /app -e NODE_ENV=test node:20 npm run test
+```

package/artifact/instructions/rules/development/ansible.md

@@ -0,0 +1,258 @@
+---
+type: infrastructure
+category: configuration-management
+language: ansible
+human-instruction: |-
+  ## Ansibleによるインフラ自動化について
+
+  Ansibleはインフラストラクチャの設定管理と自動化のためのツールです。
+  AIはAnsibleのベストプラクティスを理解していますが、以下の点で人間の判断が重要です：
+
+  - **環境固有の設定**: 本番環境の機密情報や環境固有の設定値
+  - **セキュリティポリシー**: 組織のセキュリティポリシーに準拠した設定
+  - **変更影響の評価**: インフラ変更が他システムに与える影響の評価
+  - **ロールバック戦略**: 変更失敗時の復旧手順の策定
+
+  これらの領域では、必ず人間の開発者・運用者の判断を仰いでください。
+---
+
+# Ansible Infrastructure Automation Rules
+
+## Ansible Playbook 開発ルール
+
+### ディレクトリ構造
+
+```text
+ansible/
+├── playbooks/         # メインのPlaybook
+├── roles/             # 再利用可能なRole
+├── inventory/         # インベントリファイル
+├── group_vars/        # グループ変数
+├── host_vars/         # ホスト変数
+├── files/             # 静的ファイル
+├── templates/         # Jinja2テンプレート
+└── vault/             # Ansible Vault暗号化ファイル
+```
+
+### Playbook作成ルール
+
+#### 基本構造
+
+- **名前の明確化**: 各task、play、roleには明確で説明的な名前を付ける
+- **冪等性の確保**: 何度実行しても同じ結果になるよう設計する
+- **チェックモード対応**: `--check`モードで実行可能にする
+
+#### タスク記述
+
+```yaml
+
+### Playbook作成ルール
+
+#### 基本構造
+- **名前の明確化**: 各task、play、roleには明確で説明的な名前を付ける
+- **冪等性の確保**: 何度実行しても同じ結果になるよう設計する
+- **チェックモード対応**: `--check`モードで実行可能にする
+
+#### タスク記述
+```yaml
+- name: "Install nginx package"
+  package:
+    name: nginx
+    state: present
+  become: yes
+  tags:
+    - packages
+    - nginx
+```
+
+#### 変数管理
+- 環境固有の変数は`group_vars/`または`host_vars/`に配置
+- 機密情報は`ansible-vault`で暗号化
+- デフォルト値は`roles/*/defaults/main.yml`に定義
+
+### Role 開発ルール
+
+#### Role構造
+```
+roles/webserver/
+├── tasks/main.yml      # メインタスク
+├── handlers/main.yml   # ハンドラー
+├── defaults/main.yml   # デフォルト変数
+├── vars/main.yml       # Role変数
+├── files/              # 静的ファイル
+├── templates/          # テンプレートファイル
+├── meta/main.yml       # Role依存関係
+└── README.md           # Role説明書
+```
+
+#### Role設計原則
+- **単一責任**: 1つのRoleは1つの機能に特化
+- **再利用性**: 環境に依存しない汎用的な設計
+- **依存関係**: `meta/main.yml`で明示的に管理
+
+### セキュリティルール
+
+#### 機密情報管理
+```bash
+# Vaultファイルの作成
+ansible-vault create vault/secrets.yml
+
+# Vaultファイルの編集
+ansible-vault edit vault/secrets.yml
+
+# 暗号化された変数の使用
+ansible-playbook -i inventory/production playbook.yml --ask-vault-pass
+```
+
+#### 権限管理
+- `become: yes`は必要最小限のタスクのみで使用
+- sudoユーザーの権限を適切に制限
+- SSH鍵認証を推奨、パスワード認証は避ける
+
+### インベントリ管理
+
+#### 静的インベントリ例
+
+```yaml
+# inventory.yml
+all:
+  children:
+    webservers:
+      hosts:
+        web1.example.com:
+        web2.example.com:
+    databases:
+      hosts:
+        db1.example.com:
+    production:
+      children:
+        webservers:
+        databases:
+```
+
+#### 動的インベントリ
+- クラウド環境では動的インベントリを活用
+- AWS、Azure、GCPの公式プラグインを使用
+
+### テストとデバッグ
+
+#### チェックモード
+```bash
+# 変更を実際に適用せずに確認
+ansible-playbook -i inventory/staging playbook.yml --check
+```
+
+#### 構文チェック
+```bash
+# Playbook構文の検証
+ansible-playbook playbook.yml --syntax-check
+```
+
+#### デバッグ出力
+```yaml
+- name: "Debug variable"
+  debug:
+    var: some_variable
+    verbosity: 2
+```
+
+### パフォーマンス最適化
+
+#### 並列実行
+```yaml
+- name: "Parallel task execution"
+  package:
+    name: "{{ item }}"
+    state: present
+  with_items:
+    - nginx
+    - mysql
+  async: 300
+  poll: 0
+```
+
+#### ファクト収集の最適化
+```yaml
+- hosts: all
+  gather_facts: no  # 不要な場合は無効化
+  tasks:
+    - setup:  # 必要な時のみ実行
+      when: ansible_facts is not defined
+```
+
+### エラーハンドリング
+
+#### 失敗時の継続
+```yaml
+- name: "Task that might fail"
+  command: /some/command
+  ignore_errors: yes
+  register: result
+
+- name: "Handle failure"
+  debug:
+    msg: "Command failed: {{ result.stderr }}"
+  when: result.failed
+```
+
+#### 条件分岐
+```yaml
+- name: "Install package on RedHat family"
+  yum:
+    name: httpd
+    state: present
+  when: ansible_os_family == "RedHat"
+
+- name: "Install package on Debian family"
+  apt:
+    name: apache2
+    state: present
+  when: ansible_os_family == "Debian"
+```
+
+### ベストプラクティス
+
+#### Playbookの分割
+- 大きなPlaybookは機能別に分割
+- `import_playbook`や`include_playbook`を活用
+
+#### 変数の命名規則
+- Roleプレフィックスを使用: `nginx_port`, `mysql_root_password`
+- 環境別プレフィックス: `prod_`, `stage_`, `dev_`
+
+#### ドキュメント化
+- 各Roleに`README.md`を作成
+- 変数、依存関係、使用例を記載
+- Playbookにはコメントで実行順序と目的を説明
+
+#### バージョン管理
+- `requirements.yml`でRole依存関係を管理
+- Gitタグを使用してバージョン管理
+- 変更履歴を`CHANGELOG.md`に記録
+
+### 継続的デプロイメント
+
+#### CI/CDパイプライン
+```yaml
+# .github/workflows/ansible.yml
+name: Ansible Deployment
+on:
+  push:
+    branches: [main]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v2
+      - name: Run Ansible Playbook
+        run: |
+          ansible-playbook -i inventory/production deploy.yml
+```
+
+#### テスト環境
+- ステージング環境で事前テスト
+- `molecule`を使用したRole単体テスト
+- `vagrant`でローカル検証環境を構築
+
+これらのルールに従うことで、保守性が高く、安全で効率的なAnsible自動化を実現できます。

package/artifact/instructions/rules/development/code-quality-tools.md

@@ -0,0 +1,181 @@
+---
+type: [development-rules, best-practices]
+category: code-quality
+focus: mandatory-tools
+language:
+  - typescript
+  - javascript
+---
+
+# 必須コード品質ツール設定ルール
+
+## 概要
+
+すべての新規プロジェクトにおいて、ESLint・Prettierなどのコード整形・静的解析ツールの導入と設定は**必須**です。
+これらのツールは、コード品質・一貫性の担保のために不可欠であり、プロジェクトセットアップ時に必ず設定してください。
+
+## 必須化ルール
+
+### 新規プロジェクト作成時の必須事項
+
+- **ESLint**: 静的解析ツールとして必ず導入・設定すること
+- **Prettier**: コード整形ツールとして必ず導入・設定すること
+- **EditorConfig**: エディタ横断の設定統一のため必ず設定すること
+- **設定ファイル**: `.eslintrc.json`, `.prettierrc`, `.editorconfig` を必ず作成すること
+
+### AI による自動セットアップ時の要件
+
+- 依存パッケージのインストールは**必ず `npm install` コマンド**で実行すること
+- `package.json` を直接編集せず、npm コマンドを使用すること
+- 設定ファイルの作成は手動で行い、プロジェクトに適した設定を含めること
+
+### 必須パッケージとコマンド
+
+#### TypeScript プロジェクトの場合
+
+```bash
+npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
+npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier
+npm install --save-dev @types/node
+```
+
+#### JavaScript/Node.js プロジェクトの場合
+
+```bash
+npm install --save-dev eslint
+npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier
+```
+
+## 必須設定ファイルテンプレート
+
+### .eslintrc.json (TypeScript プロジェクト用)
+
+```json
+{
+  "root": true,
+  "env": {
+    "browser": true,
+    "es2021": true,
+    "node": true
+  },
+  "extends": [
+    "eslint:recommended",
+    "@typescript-eslint/recommended",
+    "prettier"
+  ],
+  "parser": "@typescript-eslint/parser",
+  "parserOptions": {
+    "ecmaVersion": "latest",
+    "sourceType": "module"
+  },
+  "plugins": ["@typescript-eslint"],
+  "rules": {
+    "@typescript-eslint/no-unused-vars": "error",
+    "@typescript-eslint/explicit-function-return-type": "warn"
+  },
+  "ignorePatterns": ["dist/", "node_modules/", "*.js", "*.mjs"]
+}
+```
+
+### .prettierrc
+
+```json
+{
+  "printWidth": 100,
+  "tabWidth": 2,
+  "useTabs": false,
+  "semi": true,
+  "singleQuote": false,
+  "quoteProps": "as-needed",
+  "trailingComma": "es5",
+  "bracketSpacing": true,
+  "arrowParens": "always",
+  "proseWrap": "always"
+}
+```
+
+### .editorconfig
+
+```ini
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 2
+
+[*.md]
+trim_trailing_whitespace = false
+```
+
+## 必須 npm scripts
+
+`package.json` の `scripts` セクションに以下を必ず追加すること：
+
+```json
+{
+  "scripts": {
+    "lint": "eslint . --ext .ts,.js",
+    "lint:fix": "eslint . --ext .ts,.js --fix",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
+  }
+}
+```
+
+## AI 指示時の具体的な文言例
+
+### プロジェクトセットアップ時
+
+```
+新しいTypeScriptプロジェクトをセットアップしてください。
+以下の必須要件を満たすこと：
+
+1. ESLint と Prettier を必ずインストールして設定すること
+2. 依存パッケージは npm install コマンドで追加すること
+3. .eslintrc.json, .prettierrc, .editorconfig を作成すること
+4. package.json に lint, format スクリプトを追加すること
+```
+
+### 既存プロジェクトの改善時
+
+```
+このプロジェクトにESLintとPrettierの設定がありません。
+コード品質ツールの設定は必須のため、以下を実行してください：
+
+1. eslint, prettier, @typescript-eslint関連パッケージをインストール
+2. 適切な設定ファイル(.eslintrc.json, .prettierrc)を作成
+3. npm scriptsにlint/formatコマンドを追加
+```
+
+## チェックリスト
+
+新規プロジェクト作成時、または既存プロジェクトの改善時に以下を確認すること：
+
+- [ ] ESLint がインストールされている
+- [ ] Prettier がインストールされている
+- [ ] TypeScript プロジェクトの場合、@typescript-eslint 関連パッケージが入っている
+- [ ] `.eslintrc.json` ファイルが存在し、適切な設定が含まれている
+- [ ] `.prettierrc` ファイルが存在し、適切な設定が含まれている
+- [ ] `.editorconfig` ファイルが存在している
+- [ ] `package.json` に lint, format スクリプトが定義されている
+- [ ] VSCode を使用する場合、適切な `.vscode/settings.json` が設定されている
+
+## 違反時の対応
+
+もしコード品質ツールの設定が不十分なプロジェクトを発見した場合：
+
+1. **即座に設定を追加**: 上記のテンプレートを使用して必要な設定を追加する
+2. **依存関係の追加**: npm install コマンドで必要なパッケージを追加する
+3. **設定の検証**: `npm run lint` と `npm run format:check` で動作確認する
+4. **ドキュメント更新**: プロジェクトの README に設定手順を記載する
+
+## 背景・理由
+
+- **コード品質の担保**: 静的解析により潜在的な問題を早期発見
+- **コードスタイルの統一**: チーム開発における可読性・保守性の向上
+- **開発効率の向上**: 自動整形により手動でのフォーマット作業を削減
+- **問題の予防**: 設定抜けによるコードスタイル不統一や静的解析漏れを防止

package/artifact/instructions/rules/development/github.md

@@ -0,0 +1,140 @@
+---
+type: development
+category: github
+focus: issue-templates
+human-instruction: |-
+  ## GitHub Issue Template の遵守について
+
+  このルールは、GitHub Issue を作成する際にプロジェクトで設定されている ISSUE_TEMPLATE の内容に従って記載することを求めています。
+  AIはテンプレートの構造を理解できますが、以下の点で人間の判断が重要です：
+
+  - **適切なテンプレートの選択**: 報告内容に最も適したテンプレートの選択
+  - **詳細な情報提供**: テンプレートの各項目に対する具体的で詳細な情報の記載
+  - **優先度の判断**: バグや機能要求の重要度・緊急度の評価
+  - **関連情報の補足**: テンプレートにない場合でも必要な追加情報の提供
+---
+
+# GitHub Issue Template Rules
+
+## 概要
+
+GitHub Issue を作成する際は、リポジトリに設定されている `.github/ISSUE_TEMPLATE` の内容に従って Issue 本文を作成してください。
+
+## 基本ルール
+
+### テンプレートの使用
+
+- Issue 作成時は、必ず適切な Issue Template を選択してください
+- テンプレートで定義されているすべての必須項目を記載してください
+- テンプレートの構造と形式を維持してください
+
+### テンプレートの動的確認
+
+プロジェクトによってIssueテンプレートの構成は異なるため、Issue作成前に必ず以下の手順でテンプレートを確認してください：
+
+#### 1. テンプレートファイルの確認
+- `.github/ISSUE_TEMPLATE/` ディレクトリ内のファイルを確認
+- 各 `.yml` ファイルがどのような種類のIssueを対象としているかを把握
+
+#### 2. テンプレート構造の分析
+各テンプレートファイルで以下の項目を確認：
+- `name`: テンプレートの名前
+- `description`: テンプレートの用途
+- `body`: フォームの構造と必須項目
+  - `validations.required: true` が設定されている項目は必須
+  - `type` により入力形式（textarea, input, dropdown, checkboxes等）を確認
+  - `attributes.label` により項目名を確認
+  - `attributes.description` により詳細要求を確認
+
+#### 3. 適切なテンプレートの選択
+- Issue の内容に最も適したテンプレートを選択
+- テンプレートの `description` と報告内容を照合
+- 複数該当する場合は主要な目的に基づいて判断
+
+## 実装ガイドライン
+
+### Issue 作成前の確認事項
+
+1. **テンプレートの確認**
+   - `.github/ISSUE_TEMPLATE/` ディレクトリの内容を確認してください
+   - 利用可能なテンプレートファイル（`.yml`）とその構造を把握してください
+
+2. **既存 Issue の確認**
+   - 同様の内容の Issue が既に存在しないか検索してください
+   - 関連する Issue があれば参照してください
+
+3. **適切なテンプレートの選択**
+   - 確認したテンプレートの中から、報告・提案内容に最も適したものを選択してください
+   - 複数のカテゴリに該当する場合は、主要な目的に基づいて選択してください
+
+4. **情報の収集**
+   - 選択したテンプレートで要求される情報を事前に収集してください
+   - 必須項目（`validations.required: true`）は必ず用意してください
+   - 再現可能な例や具体的なケースを用意してください
+
+### Issue 記載時の注意事項
+
+1. **必須項目の記載**
+   - `validations: required: true` が設定されている項目は必ず記載してください
+   - 「該当なし」や「不明」の場合もその旨を明記してください
+
+2. **具体的な記述**
+   - 抽象的な表現ではなく、具体的で詳細な情報を記載してください
+   - コード例、コマンド例、エラーメッセージは正確に記載してください
+
+3. **構造の維持**
+   - テンプレートで定義された見出しや構造を変更しないでください
+   - 追加情報がある場合は、適切なセクションに記載してください
+
+## 違反例と修正例
+
+### ❌ 悪い例
+
+```markdown
+# バグ報告
+
+動かない。エラーが出る。
+
+どうすればいい？
+```
+
+### ✅ 良い例
+
+適切なテンプレートに従った記載例：
+
+```markdown
+### Version
+v1.0.0
+
+### What happened?
+`npx ai-rules extract` コマンドを実行すると、ModuleNotFoundError が発生して処理が停止します。
+
+### Steps to reproduce
+1. 新しいディレクトリで `npm init -y` を実行
+2. `npm install @aramassa/ai-rules` でパッケージをインストール
+3. `npx ai-rules extract --type coding-rule` を実行
+4. エラーが発生
+
+### Expected behavior
+ルールの抽出が正常に実行され、結果が出力される
+
+### Actual behavior
+以下のエラーメッセージが表示される：
+```
+Error: Cannot find module '@internal/core'
+```
+
+### Environment
+- OS: Ubuntu 22.04
+- Node.js version: v18.17.0
+- Package manager: npm 9.6.7
+- Shell: bash
+```
+
+この例では、選択したテンプレートの全ての必須項目（`validations.required: true`）が適切に記載され、具体的で詳細な情報が提供されています。
+
+## 運用における注意点
+
+- テンプレートの内容は定期的に見直し、プロジェクトの変化に応じて更新してください
+- Issue の質を向上させるため、テンプレートの使用状況を定期的に確認してください
+- 新しいチームメンバーには、Issue 作成のガイドラインを共有してください