@aramassa/ai-rules 0.1.1-npmjs.20250910072942

package/artifact/instructions/rules/development/npm-publish.md

@@ -0,0 +1,108 @@
+---
+type: development-rules
+language:
+  - typescript
+  - nodejs
+framework: npm
+---
+
+## Release Types
+
+release_type は、この GitHub Actions ワークフローを手動実行する際に選択するリリース種別の入力パラメータです。
+ワークフローの挙動（バージョン付与や npm publish のタグ）がこの値によって変化します。
+
+主に Github Actions のワークフローを手動で実行する際に、リリースの種類を選択するために使用されます。
+以下の3つの選択肢があります。
+
+### 選択肢
+
+#### stable
+
+本番リリース用。通常のバージョン（例: 1.2.3）で公開され、npm のデフォルトタグ（latest）として公開されます。
+
+#### pre-build
+
+プレリリース（開発途中ビルド）用。バージョンは 1.2.3-pre-build.20250712123456 のようにタイムスタンプ付きで生成され、pre-build タグで公開されます。
+
+#### pre-distribution
+
+配布前のプレリリース用。バージョンは 1.2.3-pre-distribution.20250712123456 のようになり、pre-distribution タグで公開されます。
+
+ワークフロー内での使われ方
+stable の場合は通常のバージョンで publish
+それ以外（pre-build, pre-distribution）は、バージョン末尾に -[release_type].[timestamp] を付与し、指定タグで publish されます
+これにより、安定版とプレリリース版を明確に区別して管理・配布できます。
+
+### .npmignore の最終チェック
+
+npm パッケージの品質確保のため、以下の場面では必ず .npmignore の内容を最終確認すること。
+
+#### 機能追加・リファクタリング後の確認
+
+- 機能追加やリファクタリング後、不要なファイル・ディレクトリがパッケージに含まれていないか .npmignore で最終チェックする
+- 新たに追加されたテストファイル、一時ファイル、開発用ファイルなどが適切に除外されているか確認する
+
+#### リリース前の確認
+
+- .npmignore の更新漏れがないか、リリース前に必ず確認する
+- `npm pack --dry-run` コマンドでパッケージに含まれるファイル一覧を確認し、想定通りの内容になっているかチェックする
+
+#### 参考事例
+
+実際に skel-extractor プロジェクトで .npmignore の見直しが必要となった事例があります。このような問題を未然に防ぐため、上記チェックを徹底してください。
+
+### Sample Action
+
+```yaml
+name: Publish xxxx package
+
+on:
+  workflow_dispatch:
+    inputs:
+      release_type:
+        description: "Release type"
+        required: true
+        default: "pre-build"
+        type: choice
+        options:
+          - stable
+          - pre-build
+          - pre-distribution
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com/
+      - name: Install dependencies
+        run: npm install
+      - name: Run tests
+        run: npm test
+      - name: Build packages
+        run: npm run build:clean && npm run root:build
+      - name: Setup prerelease version
+        if: github.event.inputs.release_type != 'stable'
+        run: |
+          CURRENT_VERSION=$(node -p "require('./package.json').version")
+          TIMESTAMP=$(date +%Y%m%d%H%M%S)
+          PRERELEASE_VERSION="${CURRENT_VERSION}-${{ github.event.inputs.release_type }}.${TIMESTAMP}"
+          npm version $PRERELEASE_VERSION --no-git-tag-version
+          echo "PRERELEASE_VERSION=$PRERELEASE_VERSION" >> $GITHUB_ENV
+      - name: Publish stable release
+        if: github.event.inputs.release_type == 'stable'
+        run: npm publish --verbose
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      - name: Publish prerelease
+        if: github.event.inputs.release_type != 'stable'
+        run: npm publish --tag ${{ github.event.inputs.release_type }} --verbose
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```

package/artifact/instructions/rules/development/typescript-rollup-build.md

@@ -0,0 +1,249 @@
+---
+title: TypeScript Rollup Build
+type: development
+language: typescript
+framework: rollup
+---
+
+## 目次
+- [概要](#概要)
+- [事前調査](#事前調査)
+- [必要な依存関係](#必要な依存関係)
+- [設定ファイル](#設定ファイル)
+- [設定手順](#設定手順)
+- [ビルドの実行方法](#ビルドの実行方法)
+- [主なプラグインと外部依存](#主なプラグインと外部依存)
+- [公開前処理](#公開前処理)
+- [トラブルシューティング](#トラブルシューティング)
+
+## 概要
+
+このリポジトリでは CLI ツールを単一ファイルとして配布するため、
+Rollup を用いたバンドル処理を行っています。各パッケージは TypeScript コンパイルのみ
+ですが、ルートの CLI だけは `rollup.config.mjs` でバンドルされ `dist/cli.js` として
+生成されます。
+
+## 事前調査
+
+1. CLI のエントリーポイントとなるファイルを確認する（例: `src/cli.ts`）
+2. バンドル対象に含める依存パッケージと、実行時に外部化するモジュールを洗い出す
+3. 配布形式（ESM か CJS）や対応 Node.js バージョンを決める
+4. `package.json` の `main` や `bin` フィールド、TypeScript 設定の有無を確認する
+5. ビルド成果物を配置する `dist/` ディレクトリ構成を決定する
+
+## 必要な依存関係
+
+TypeScript + Rollup の構成では以下の依存関係が必要です：
+
+### 必須パッケージ
+
+```bash
+# Rollup 本体とプラグイン
+npm install --save-dev rollup
+npm install --save-dev @rollup/plugin-typescript
+npm install --save-dev @rollup/plugin-node-resolve
+npm install --save-dev @rollup/plugin-commonjs
+npm install --save-dev @rollup/plugin-alias
+npm install --save-dev @rollup/plugin-json
+
+# TypeScript 関連
+npm install --save-dev typescript
+npm install --save-dev tslib
+```
+
+### tslib の重要性
+
+`@rollup/plugin-typescript` は `tslib` に依存しているため、必ずインストールが必要です。
+tslib は TypeScript のヘルパー関数を提供し、バンドルサイズの削減に貢献します。
+
+モノレポ構成では、ルートと各パッケージの両方にインストールすることを推奨します：
+
+```bash
+# ルートプロジェクト
+npm install --save-dev tslib
+
+# 各パッケージ
+cd packages/core && npm install --save-dev tslib
+cd packages/extract && npm install --save-dev tslib
+```
+
+## 設定ファイル
+
+ルートにある `rollup.config.mjs` では以下のような設定を行っています。
+
+- **入力**: `src/cli.ts`
+- **出力**: `dist/cli.js`（ESM 形式）
+- **外部依存**: `yaml` など実行時に必要なモジュールは外部化
+- **プラグイン**:
+  - `@rollup/plugin-alias` でワークスペース内パッケージの `dist` を解決
+  - `@rollup/plugin-typescript` による TypeScript トランスパイル
+  - `@rollup/plugin-node-resolve` と `@rollup/plugin-commonjs` によるモジュール解決
+  - `@rollup/plugin-json` による JSON インポート対応
+
+### 設定時の注意点
+
+- `inlineDynamicImports: true` を指定して依存を 1 ファイルにまとめる
+- **shebang行の重複を避ける**: `banner` は使わず、ソースファイル側に `#!/usr/bin/env node` を記述
+- 外部モジュールは `external` に列挙しバンドル対象から除外する
+- ワークスペース内パッケージは `@rollup/plugin-alias` で `dist` を解決する
+- 本番環境では `sourcemap: false` を設定してファイルサイズを削減
+
+### 実際の設定例
+
+```javascript
+import { defineConfig } from 'rollup';
+import alias from '@rollup/plugin-alias';
+import typescript from '@rollup/plugin-typescript';
+import nodeResolve from '@rollup/plugin-node-resolve';
+import commonjs from '@rollup/plugin-commonjs';
+import json from '@rollup/plugin-json';
+import path from 'path';
+
+export default defineConfig({
+  input: 'src/cli.ts',
+  output: {
+    file: 'dist/cli.js',
+    format: 'esm',
+    inlineDynamicImports: true,
+    sourcemap: false,
+  },
+  external: ['yaml'],
+  plugins: [
+    alias({
+      entries: [
+        { find: '@internal/core', replacement: path.resolve('packages/core/dist/index.js') },
+        { find: '@internal/extract', replacement: path.resolve('packages/extract/dist/index.js') },
+      ],
+    }),
+    nodeResolve({ preferBuiltins: true }),
+    commonjs({
+      transformMixedEsModules: true,
+    }),
+    json(),
+    typescript({
+      tsconfig: './tsconfig.build.json',
+      outputToFilesystem: true,
+    }),
+  ],
+});
+```
+
+### TypeScript 設定 (tsconfig.build.json)
+
+```json
+{
+  "extends": "./tsconfig.json",
+  "compilerOptions": {
+    "outDir": "dist",
+    "rootDir": "src",
+    "declaration": true,
+    "declarationMap": true,
+    "sourceMap": false,
+    "removeComments": false,
+    "types": ["node"],
+    "module": "ESNext",
+    "target": "ES2020",
+    "moduleResolution": "Bundler",
+    "importHelpers": true,
+    "noEmitHelpers": false
+  },
+  "include": ["src/**/*"],
+  "exclude": ["test/**/*", "src/**/*.test.ts", "src/**/*.spec.ts", "**/*.test.ts", "**/*.spec.ts"]
+}
+```
+
+重要なオプション：
+
+- `importHelpers: true`: tslib からヘルパー関数をインポート
+- `noEmitHelpers: false`: ヘルパー関数の出力を許可
+
+## 設定手順
+
+1. `rollup` 本体と必要なプラグイン、`tslib` を `devDependencies` に追加する
+2. ビルド用の `tsconfig.build.json` を用意し、`importHelpers: true` を設定する
+3. `rollup.config.mjs` で入力・出力・プラグイン・external を定義する
+4. `package.json` に `root:build` スクリプトと `prepublishOnly` フックを設定する
+5. ソースファイル（`src/cli.ts`）の先頭に `#!/usr/bin/env node` を追加する
+6. `npm run root:build` を実行して `dist/cli.js` を生成し、実行権限を確認する
+
+## ビルドの実行方法
+
+ワークスペース全体のビルドでは、ルート `package.json` に定義された
+`root:build` スクリプトが利用されます。通常のビルド時は TypeScript の
+コンパイル後に Rollup が実行されます。
+
+```bash
+npm run root:build
+```
+
+テスト実行時 (`NODE_ENV=test`) には Rollup をスキップし
+TypeScript のみをビルドする挙動になっています。
+
+## 主なプラグインと外部依存
+
+Rollup では実行時に別途インストールされるモジュールを `external` として
+扱い、バンドル対象から除外しています。これにより CLI 依存のパッケージを
+必要最小限に抑えつつ、単一ファイルでの配布を実現しています。
+ワークスペース内の各パッケージは `@rollup/plugin-alias` で `dist/` を参照
+するようマッピングされています。
+
+## 公開前処理
+
+`npm publish` 前には `prepublishOnly` スクリプト経由で `root:build` が
+実行され、常に最新のバンドルを生成した状態で公開されます。
+
+```json
+"prepublishOnly": "npm run root:build"
+```
+
+この手順により、CLI のビルド漏れを防いでいます。
+
+## トラブルシューティング
+
+### よくある問題と解決方法
+
+#### 1. tslib エラー
+
+```text
+RollupError: [plugin typescript] @rollup/plugin-typescript: Could not find module 'tslib'
+```
+
+**原因**: tslib がインストールされていない
+**解決**: `npm install --save-dev tslib` でインストール
+
+#### 2. shebang 行の重複
+
+```javascript
+#!/usr/bin/env node
+#!/usr/bin/env node
+```
+
+**原因**: rollup.config.mjs の `banner` とソースファイルの shebang が重複
+**解決**: `banner` オプションを削除し、ソースファイル側のみに shebang を記述
+
+#### 3. モジュール解決エラー
+
+```text
+Error: Could not resolve '@internal/core' from src/cli.ts
+```
+
+**原因**: alias 設定や依存パッケージのビルド順序の問題
+**解決**:
+
+- `npm run --ws build` で各パッケージが先にビルドされているか確認
+- `@rollup/plugin-alias` の path 設定を確認
+
+#### 4. 実行権限エラー
+
+```text
+Permission denied: ./dist/cli.js
+```
+
+**原因**: 生成されたファイルに実行権限がない
+**解決**: `chmod +x dist/cli.js` で実行権限を付与
+
+### デバッグのヒント
+
+- 段階的ビルド: `npm run --ws build` → `tsc -p tsconfig.build.json` → `rollup -c`
+- 依存関係確認: `npm list tslib` で tslib のインストールを確認
+- 設定確認: rollup.config.mjs の external と alias 設定を見直し

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

@@ -0,0 +1,46 @@
+---
+type: development-rules
+language: typescript
+---
+
+## Package Setup
+
+### 必須コード品質ツールの設定
+
+**すべての TypeScript プロジェクト**において、以下のコード品質ツールの導入・設定は**必須**です：
+
+#### 必須ツール
+- **ESLint**: TypeScript 静的解析のため必須
+- **Prettier**: コード整形のため必須
+- **EditorConfig**: エディタ設定統一のため必須
+
+#### 必須パッケージインストール手順
+
+```bash
+# TypeScript 関連の必須パッケージ
+npm install --save-dev typescript @types/node
+
+# ESLint + TypeScript 設定（必須）
+npm install --save-dev eslint @typescript-eslint/parser @typescript-eslint/eslint-plugin
+
+# Prettier 設定（必須）
+npm install --save-dev prettier eslint-config-prettier eslint-plugin-prettier
+```
+
+#### 必須設定ファイル作成
+
+以下の設定ファイルを**必ず作成**すること：
+
+1. `.eslintrc.json` - ESLint 設定（必須）
+2. `.prettierrc` - Prettier 設定（必須）
+3. `.editorconfig` - エディタ設定（必須）
+4. `package.json` に lint/format スクリプトを追加（必須）
+
+#### AI による自動セットアップ時の注意
+
+- パッケージインストールは**必ず npm install コマンド**を使用すること
+- package.json を直接編集してはならない
+- 設定ファイルは適切なテンプレートを使用して作成すること
+
+詳細な設定内容は `code-quality-tools.md` を参照してください。
+

package/artifact/instructions/rules/documentation/common.md

@@ -0,0 +1,16 @@
+---
+type: documentation
+---
+
+## Documentation Guidelines
+
+### Directory Structure
+
+| ディレクトリ                | 用途                                                                                   | 備考                                   |
+|----------------------------|----------------------------------------------------------------------------------------|----------------------------------------|
+| `docs/`                    | 人間に読ませるためのドキュメント。skel/docs の構造と一致するように記載すること         |                                        |
+| `docs-ai/`                 | AI に読ませるためのドキュメントで、人間が理解することはあまり考慮されていない           |                                        |
+| `docs-ai/history/`         | 変更履歴などを保存するためのディレクトリ。冗長であっても事細かに記録していく           |                                        |
+| `docs-ai/learning/`        | AIが実行したタスクから、人間が学べそうなことを抽出して、学習コンテンツにしたもの。特に、使っている技術要素に関して重点的に説明をする |                                        |
+| `docs-ai/internal/`        | 現在修正中のコードベースに関する情報。Gitコミット対象                                  |                                        |
+| `docs-ai/external/`        | そのコードベースに関連する外部の情報。Gitコミット対象外 (gitignore)                    |                                        |

package/artifact/instructions/rules/documentation/docs-ai-external.md

@@ -0,0 +1,12 @@
+---
+type: documentation-ai
+target: ai
+dir: docs-ai/external
+---
+
+## Documentation Guidelines for External AI Documentation
+
+### docs-ai/external ディレクトリの目的
+
+このディレクトリは、プロジェクトが利用する外部ライブラリやフレームワーク、API、ツールなどの情報を集約することを目的としています。
+コマンドラインツールやWEBスクレイピングによって取得された情報を置くので、AIが作業時に出力するものは原則的にありません。

package/artifact/instructions/rules/documentation/docs-ai-history.md

@@ -0,0 +1,46 @@
+---
+type: documentation-ai
+target: ai
+dir: docs-ai/history
+---
+## Documentation Guidelines for AI History Documentation
+
+### docs-ai/history ディレクトリの目的
+
+このディレクトリは、AIが行った変更履歴や過去の経緯を記録することを目的としています。
+AIが自動生成・修正を行う際の判断材料として、過去の変更内容や理由を参照できるようにします。
+この情報は、AIがコードの変更や修正を行う際に、過去の経緯を理解し、適切な判断を下すために重要です。
+
+### AI向け履歴ドキュメント作成ガイドライン
+
+- **ファイル命名規則**
+  履歴ファイルは必ず `YYYYMMDD_NN_[タイトル].md` の形式で命名してください。
+  - `YYYYMMDD` は日付（例: 20240601）
+  - `NN` は同一日付内での連番（01, 02, ...）
+  - `[タイトル]` は内容を簡潔に表す英数字または日本語
+  例: `20240601_01_初回セットアップ.md`
+
+- **ファイルの整理・アーカイブ**
+  古くなった履歴や参照頻度の低いファイルは、`archive/` サブディレクトリに移動してください。
+  - `archive/` 内でも命名規則は維持してください。
+  - 必要に応じて年ごとなどでサブディレクトリを作成しても構いません。
+
+- **履歴の粒度**
+  1つの履歴ファイルには、1つの変更や意思決定に関する内容のみを記載してください。
+  複数のトピックが混在しないように注意してください。
+
+- **内容の記載例**
+  - 変更内容の要約
+  - 変更理由や背景
+  - 影響範囲
+  - 今後の課題やTODO
+
+- **メンテナンス性向上の工夫**
+  - 定期的に不要な履歴や重複した内容を整理してください。
+  - 重要な履歴には `重要:` などのラベルを先頭に付与してください。
+  - 履歴の参照先や関連ファイルがあれば、相対パスで明記してください。
+
+- **その他**
+  - 履歴ファイルの内容はAIが自動で解析しやすいよう、簡潔かつ構造化された記述を心がけてください。
+  - 履歴の追加・整理を行った場合は、必ずこのガイドラインも見直し、必要に応じて更新してください。
+

package/artifact/instructions/rules/documentation/docs-ai-internal.md

@@ -0,0 +1,70 @@
+---
+type: documentation-ai
+target: ai
+dir: docs-ai/internal
+---
+## Documentation Guidelines for Internal AI Documentation
+
+### docs-ai/internal ディレクトリの目的
+
+このディレクトリは、AIが自動生成・修正を行う際の判断材料となる情報を集約することを目的としています。
+記載する内容は、現在のコードベースに関する詳細な仕様、設計意図、運用ルールなどです。
+依存しているライブラリやフレームワークの情報など、外部の情報はここには記載しません。docs-ai/external ディレクトリに記載するので、ここには書かないようにしましょう。
+
+### AI向け内部ドキュメント作成ガイドライン
+
+- **冗長さを恐れず、AIが判断材料にできる情報をできるだけ多く記載すること。**
+  - 例: 型情報、前提条件、設計意図、利用例、制約事項、関連ファイル、依存関係、典型的な失敗パターン、よくある質問など。
+  - **ログ出力、エラーハンドリング、メトリクス（監視・計測）、デプロイメント、パッケージ管理、テスト設計に関する仕様や運用ルールも必ず記載すること。**
+- **人間が読むことを前提としない。AIがパースしやすいよう、明確な見出しやリスト、テーブルを活用する。**
+- **コード例や構造例は、できるだけ具体的に記載する。**
+- **「なぜそうなっているか」「どう使うべきか」など、設計思想や運用ルールも明記する。**
+- **関連する外部ドキュメントや仕様書があれば、パスやURLを明記する。**
+- **AIが参照すべき他のファイルやディレクトリ構成も記載する。**
+
+---
+
+### ファイルごとの情報の出力指針
+
+| ファイル/ディレクトリ                | 記載すべき情報例                                                                                   |
+|--------------------------------------|----------------------------------------------------------------------------------------------------|
+| `docs-ai/internal/`                  | AIがコード生成・修正時に参照すべき内部仕様、設計意図、構造例、運用ルール、典型的な利用例、FAQ、<br>ログ出力方針、エラーハンドリング方針、メトリクス設計、<br>デプロイメント手順・設計、パッケージ管理ルール、テスト設計・方針など   |
+
+---
+
+### 記載例
+
+#### 設計意図・背景
+
+- このディレクトリはAIが自動生成・修正を行う際の判断材料となる情報を集約する。
+- 仕様変更や設計判断の理由も明記し、AIが過去の経緯を参照できるようにする。
+
+#### 典型的な構造例
+
+```plaintext
+docs-ai/internal/
+  ├── overview.md           # 全体像・設計方針・ファイルツリー情報
+  ├── moduleA.md            # モジュールAの詳細仕様・設計意図・利用例
+  ├── moduleB.md            # モジュールBの詳細仕様・設計意図・利用例
+  ├── logging.md            # ログ出力の設計・運用ルール・出力例
+  ├── error-handling.md     # エラーハンドリングの方針・例外設計・運用ルール
+  ├── metrics.md            # メトリクス（監視・計測）の設計・収集項目・運用ルール
+  ├── deployment.md         # デプロイメント設計・手順・CI/CDルール
+  ├── package-management.md # パッケージ管理ルール・依存関係・バージョン管理・運用例
+  └── test-design.md        # テスト設計・テスト方針・テストケース例・カバレッジ基準
+```
+
+#### FAQ例
+
+- Q: どのファイルにどんな情報を記載すべき？
+  - A: 設計意図や運用ルールは `docs-ai/internal/`、履歴や経緯は `docs-ai/history/`、学習用知見は `docs-ai/learning/` へ。
+  - ログ出力やエラーハンドリング、メトリクス、デプロイメント、パッケージ管理、テスト設計に関する詳細は `logging.md`、`error-handling.md`、`metrics.md`、`deployment.md`、`package-management.md`、`test-design.md` などに分割して記載する。
+
+---
+
+### 注意事項
+
+- ドキュメントの粒度は細かく、情報の重複を恐れず記載する。
+- どの情報がどのファイルにあるかを明記し、AIが迷わないようにする。
+- ファイルの先頭に用途や内容を明記すること。
+

package/artifact/instructions/rules/documentation/docs-ai-learning.md

@@ -0,0 +1,53 @@
+---
+type: documentation-ai
+target: ai
+dir: docs-ai/learning
+---
+## Documentation Guidelines for AI Learning Documentation
+
+### docs-ai/learning ディレクトリの目的
+
+このディレクトリは、AIが実行したタスクから人間が学べる内容を抽出し、学習コンテンツとしてまとめることを目的としています。
+特に、使用している技術要素や手法に関して重点的に説明を行います。
+この情報は、AIの学習や改善に役立つだけでなく、人間の開発者がAIの動作や意図を理解するために重要です。
+
+### AI向け学習ドキュメント作成ガイドライン
+
+#### 1. ドキュメントの構成
+
+- 各ドキュメントは、学習テーマごとにサブフォルダを作成し、その中に配置します。
+- 各ファイルの先頭には日付を基準とした連番（例: `20250714_`）を付与し、新しい順に並ぶようにしてください。
+- 例: `typescript/20250714_rollup-bundler.md`
+※ ファイル一覧は日付連番の降順（新しいものが上）で管理・表示してください。
+- 冒頭にYAMLフロントマターで `type`, `target`, `dir` などのメタ情報を記載してください。
+- 見出し（##, ### など）を活用し、内容を論理的に整理します。
+
+#### 2. 記述内容の指針
+
+- AIが実行した具体的なタスクや、その過程で得られた知見・工夫点・失敗例・改善案などを記載します。
+- 使用技術（例: TypeScript, Rollup, テスト手法など）や設計思想、選定理由を明記してください。
+- コード例やコマンド例は、必要に応じてMarkdownのコードブロックで示します。
+
+#### 3. 推奨フォーマット
+
+- 目的・背景
+- 実施内容（手順・工夫点・課題）
+- 結果・得られた知見
+- 今後の改善点や応用例
+
+#### 4. 書き方の注意点
+
+- 主語は「AI」または「本プロジェクト」など、客観的な表現を用いること。
+- 冗長な説明や重複は避け、簡潔かつ明瞭にまとめる。
+- 他のドキュメントや外部リソースへの参照がある場合は、パスやURLを明記する。
+
+#### 5. 更新・管理ルール
+
+- 新たな学習内容が得られた場合は、速やかに追記・新規作成する。
+- 内容の重複や古い情報があれば、適宜整理・統合・削除を行う。
+- 変更履歴は `docs-ai/history/` に記録することを推奨します。
+
+---
+
+このガイドラインに従い、AI学習ドキュメントを継続的に充実させてください。
+

package/artifact/instructions/rules/documentation/docs.md

@@ -0,0 +1,41 @@
+---
+type: documentation
+target: human
+dir: docs
+---
+
+## Documentation Guidelines
+
+docs ディレクトリは、プロジェクトの技術的なドキュメントをまとめる場所です。
+ここでは、技術的な内容を明確に伝えるためのガイドラインを提供します。
+
+### 技術文書作成ガイドライン
+
+- **目的を明確にする**
+  文書の対象読者と目的を最初に明記してください。
+
+- **構造化された見出し**
+  見出し（#, ##, ###）を使い、論理的な階層構造を意識してください。
+
+- **簡潔かつ正確な表現**
+  冗長な表現を避け、専門用語は必要に応じて説明を加えてください。
+
+- **箇条書き・表の活用**
+  複数項目や比較は箇条書きや表を使い、視認性を高めてください。
+
+- **コード例の明示**
+  コードブロックには言語指定を付与し、必要に応じてコメントを記載してください。
+
+- **図やイメージの活用**
+  必要に応じて図やイメージを挿入し、文章だけで伝わりにくい内容を補足してください。
+  mermaid 記法を使用しましょう。
+
+- **更新履歴の記載**
+  文書の末尾に更新履歴を記載し、変更内容を明確にしてください。
+
+- **一貫した用語・表記**
+  プロジェクト内で用語や表記の揺れがないよう統一してください。
+
+- **参考資料・リンクの明記**
+  参考にした資料や関連ドキュメントへのリンクを明記してください。
+