From c0bad83f7ee3272d191e41425613955617a96920 Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Wed, 20 May 2026 02:59:14 +0000 Subject: [PATCH 1/2] =?UTF-8?q?Docs:=20AGENTS.md=20=E3=81=AE=E3=83=AA?= =?UTF-8?q?=E3=83=9D=E3=82=B8=E3=83=88=E3=83=AAURL=E3=82=92=20devbasex/ai-?= =?UTF-8?q?plugins=20=E3=81=AB=E6=9B=B4=E6=96=B0?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 旧URL (takemi-ohama/ai-plugins) は archive 予定のため、 正規のリポジトリURL (devbasex/ai-plugins) に差し替える。 Co-Authored-By: Claude Opus 4.7 (1M context) --- AGENTS.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/AGENTS.md b/AGENTS.md index 529f407e..9831fdc5 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -4,7 +4,7 @@ **Claude Codeプラグインマーケットプレイス**の開発プロジェクトです。チーム全体でClaude Codeの導入を加速するための事前設定されたプラグインを提供します。 -**リポジトリ**: https://github.com/takemi-ohama/ai-plugins +**リポジトリ**: https://github.com/devbasex/ai-plugins ## ポリシー From 90f0d28c811350cfa6f198b0a48431d029e6264f Mon Sep 17 00:00:00 2001 From: "takemi.ohama" Date: Wed, 20 May 2026 03:10:44 +0000 Subject: [PATCH 2/2] =?UTF-8?q?Docs:=20takemi-ohama/ai-plugins=20=E5=8F=82?= =?UTF-8?q?=E7=85=A7=E3=82=92=20devbasex/ai-plugins=20=E3=81=AB=E7=B5=B1?= =?UTF-8?q?=E4=B8=80?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - docs/project-overview.md: オーナー名・リポジトリURL・marketplace add コマンド - README.md: marketplace add / git clone コマンド - plugins/ndf/AGENTS.md, plugins/ndf/README.md: リポジトリURL・marketplace add・issue URL - plugins/mcp-playwright/README.md, plugin.json: issue URL・author.url - plugins/affaan-m/README.md: issue URL 旧リポジトリ (takemi-ohama/ai-plugins) は archive 済みのため、 アクティブな参照は全て新リポジトリ URL に統一する。 著作権表示 (plugin.json author / 作成者欄)、過去 PR レビュー記録 (docs/external-reviews/)、別リポジトリ参照 (mcp-dbhub の dbhub fork) は 変更対象外として残す。 あわせて takemi-ohama URL を含む古い issue メモを削除: - issues/old/, issues/PLAN10/, issues/PLAN15.md, issues/PLAN17.md, issues/template09.md, issues/i12.md, issues/i15.md, issues/ndf-presentation.md Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 4 +- docs/project-overview.md | 6 +- issues/PLAN10/01-analysis.md | 272 ----- issues/PLAN10/02-migration-plan.md | 376 ------- issues/PLAN10/03-installation-usage.md | 424 -------- issues/PLAN10/04-feature-comparison.md | 216 ---- issues/PLAN10/README.md | 195 ---- issues/PLAN15.md | 153 --- issues/PLAN17.md | 289 ------ issues/i12.md | 13 - issues/i15.md | 438 -------- issues/ndf-presentation.md | 247 ----- issues/old/i001.md | 610 ----------- issues/old/i01.md | 102 -- issues/old/i02.md | 48 - issues/old/i03.md | 20 - issues/old/i04.md | 24 - issues/old/i05.md | 32 - issues/old/i06.md | 26 - issues/old/i07-skills-design.md | 943 ------------------ issues/old/i07.md | 286 ------ issues/old/i08.md | 64 -- issues/old/report01.md | 210 ---- issues/old/report02.md | 151 --- issues/old/report03.md | 249 ----- issues/old/report04.md | 249 ----- issues/old/report05.md | 184 ---- issues/old/report08.md | 788 --------------- ...63\346\247\213\346\210\220\346\241\210.md" | 307 ------ ...13\347\231\272\346\214\207\351\207\235.md" | 69 -- issues/template09.md | 77 -- plugins/affaan-m/README.md | 2 +- .../mcp-playwright/.claude-plugin/plugin.json | 2 +- plugins/mcp-playwright/README.md | 2 +- plugins/ndf/AGENTS.md | 2 +- plugins/ndf/README.md | 4 +- 36 files changed, 11 insertions(+), 7073 deletions(-) delete mode 100644 issues/PLAN10/01-analysis.md delete mode 100644 issues/PLAN10/02-migration-plan.md delete mode 100644 issues/PLAN10/03-installation-usage.md delete mode 100644 issues/PLAN10/04-feature-comparison.md delete mode 100644 issues/PLAN10/README.md delete mode 100644 issues/PLAN15.md delete mode 100644 issues/PLAN17.md delete mode 100644 issues/i12.md delete mode 100644 issues/i15.md delete mode 100644 issues/ndf-presentation.md delete mode 100644 issues/old/i001.md delete mode 100644 issues/old/i01.md delete mode 100644 issues/old/i02.md delete mode 100644 issues/old/i03.md delete mode 100644 issues/old/i04.md delete mode 100644 issues/old/i05.md delete mode 100644 issues/old/i06.md delete mode 100644 issues/old/i07-skills-design.md delete mode 100644 issues/old/i07.md delete mode 100644 issues/old/i08.md delete mode 100644 issues/old/report01.md delete mode 100644 issues/old/report02.md delete mode 100644 issues/old/report03.md delete mode 100644 issues/old/report04.md delete mode 100644 issues/old/report05.md delete mode 100644 issues/old/report08.md delete mode 100644 "issues/old/\343\203\227\343\203\254\343\202\274\343\203\263\346\247\213\346\210\220\346\241\210.md" delete mode 100644 "issues/old/\351\226\213\347\231\272\346\214\207\351\207\235.md" delete mode 100644 issues/template09.md diff --git a/README.md b/README.md index 6f086a0b..916f2717 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,7 @@ Claude CodeプラグインおよびKiro CLI向けのスキル・MCP設定を共 #### 1. マーケットプレイスの追加 ```bash -/plugin marketplace add https://github.com/takemi-ohama/ai-plugins +/plugin marketplace add https://github.com/devbasex/ai-plugins ``` #### 2. プラグインのインストール @@ -41,7 +41,7 @@ Claude CodeプラグインおよびKiro CLI向けのスキル・MCP設定を共 #### 1. リポジトリをクローン ```bash -git clone https://github.com/takemi-ohama/ai-plugins.git +git clone https://github.com/devbasex/ai-plugins.git cd ai-plugins ``` diff --git a/docs/project-overview.md b/docs/project-overview.md index bbed21e6..06923deb 100644 --- a/docs/project-overview.md +++ b/docs/project-overview.md @@ -7,9 +7,9 @@ Claude Codeプラグインマーケットプレイス（内部用）として、 ## リポジトリ情報 - **リポジトリ名**: ai-plugins -- **オーナー**: takemi-ohama +- **オーナー**: devbasex - **ライセンス**: MIT -- **URL**: https://github.com/takemi-ohama/ai-plugins +- **URL**: https://github.com/devbasex/ai-plugins ## 配布コンポーネント @@ -39,7 +39,7 @@ ai-plugins/ ### マーケットプレイスの追加 ```bash -/plugin marketplace add https://github.com/takemi-ohama/ai-plugins +/plugin marketplace add https://github.com/devbasex/ai-plugins ``` ### プラグインのインストール diff --git a/issues/PLAN10/01-analysis.md b/issues/PLAN10/01-analysis.md deleted file mode 100644 index aadaac7b..00000000 --- a/issues/PLAN10/01-analysis.md +++ /dev/null @@ -1,272 +0,0 @@ -# ai-plugins → Kiro CLI 移植調査結果 - -## 調査日時 -2026-02-05 - -## 1. NDFプラグインの機能調査 - -### 1.1 プラグイン構成 - -**plugin.json**: -- バージョン: 2.5.0 -- 9つのカスタムコマンド -- 6つのサブエージェント -- 13個のスキル -- フック機能（SessionStart、Stop） - -### 1.2 MCPサーバー統合 (.mcp.json) - -| MCPサーバー | タイプ | 用途 | 認証 | -|------------|--------|------|------| -| Serena | stdio | セマンティックコード操作 | GOOGLE_API_KEY, ANTHROPIC_API_KEY | -| Notion | http | Notion統合 | NOTION_TOKEN | -| BigQuery | stdio | BigQueryクエリ | GCPサービスアカウント | -| DBHub | stdio | データベース操作 | DSN | -| Chrome DevTools | stdio | ブラウザ自動化 | なし | -| AWS Docs | stdio | AWS文書検索 | なし | -| Codex CLI | stdio | Codex統合 | Codex認証 | - -### 1.3 カスタムコマンド (commands/) - -| コマンド | 機能 | -|---------|------| -| `/ndf:serena` | Serena MCP操作ガイド | -| `/ndf:pr` | PR作成ワークフロー | -| `/ndf:pr-tests` | Test Plan自動実行 | -| `/ndf:fix` | レビュー指摘修正 | -| `/ndf:review` | コードレビュー | -| `/ndf:merged` | マージ後処理 | -| `/ndf:clean` | ブランチクリーンアップ | -| `/ndf:mem-review` | Memory戦略レビュー | -| `/ndf:mem-capture` | Memory記録 | - -### 1.4 サブエージェント (agents/) - -| エージェント | 役割 | ツール | -|------------|------|--------| -| director | タスク統括・指揮者 | 全ツール | -| data-analyst | データ分析 | BigQuery, DBHub | -| corder | コーディング | GitHub, Serena | -| researcher | 調査 | Web検索, AWS Docs | -| scanner | ファイル読み取り | fs_read, PDF/Excel解析 | -| qa | 品質管理 | セキュリティスキャン | - -### 1.5 スキル (skills/) - -| スキル | 機能 | -|--------|------| -| data-analyst-sql-optimization | SQL最適化 | -| data-analyst-export | データエクスポート | -| corder-code-templates | コードテンプレート | -| corder-test-generation | テスト生成 | -| researcher-report-templates | レポートテンプレート | -| scanner-pdf-analysis | PDF解析 | -| scanner-excel-extraction | Excel抽出 | -| qa-security-scan | セキュリティスキャン | -| markdown-writing | Markdown文書作成 | -| memory-handling | Memory戦略 | -| python-execution | Python実行環境判定 | -| docker-container-access | Dockerコンテナアクセス | -| skill-development | Skill開発ガイド | - -### 1.6 フック (hooks/) - -**SessionStart**: -1. NDF Plugin Guideを`CLAUDE.md`に自動注入 -2. Memory戦略を`.serena/memories`に初期化 - -**Stop**: -- Slack通知（セッション終了時） - -## 2. Claude Code Plugin Marketplace仕様 - -### 2.1 マーケットプレイス構造 - -``` -.claude-plugin/ -└── marketplace.json # マーケットプレイス定義 -``` - -**marketplace.json**: -```json -{ - "name": "marketplace-name", - "owner": { "name": "...", "url": "..." }, - "plugins": [ - { - "name": "plugin-name", - "source": "./plugins/plugin-name" - } - ] -} -``` - -### 2.2 プラグイン構造 - -``` -plugins/{plugin-name}/ -├── .claude-plugin/ -│ └── plugin.json # 必須 -├── commands/ # スラッシュコマンド -├── agents/ # サブエージェント -├── skills/ # プロジェクトスキル -├── hooks/ # フック -└── .mcp.json # MCP設定（オプション） -``` - -### 2.3 主要機能 - -| 機能 | Claude Code | 説明 | -|------|-------------|------| -| Marketplace | ✅ | プラグインカタログ | -| Plugin | ✅ | 拡張パッケージ | -| Commands | ✅ | スラッシュコマンド | -| Agents | ✅ | サブエージェント | -| Skills | ✅ | 自動起動機能 | -| Hooks | ✅ | ライフサイクルフック | -| MCP | ✅ | Model Context Protocol | - -## 3. Kiro CLI類似機能調査 - -### 3.1 Kiro CLIの機能 - -| 機能 | Kiro CLI | 説明 | -|------|----------|------| -| Marketplace | ❌ | なし | -| Plugin | ❌ | なし | -| Commands | ✅ | スラッシュコマンド（組み込み） | -| Agents | ✅ | エージェント設定（JSON） | -| Skills | ❌ | なし | -| Hooks | ✅ | コンテキストフック | -| MCP | ✅ | MCP統合 | - -### 3.2 Kiro CLIの組み込みコマンド - -``` -/quit, /clear, /agent, /chat, /context, /code, /editor, /reply, -/compact, /tools, /issue, /logdump, /changelog, /prompts, /hooks, -/usage, /mcp, /model, /experiment, /plan, /todos, /paste, /help -``` - -### 3.3 Kiro CLIのエージェント - -**エージェント設定ファイル**: `.kiro/agents/{agent-name}.json` - -```json -{ - "description": "エージェントの説明", - "tools": ["fs_read", "fs_write", "execute_bash"], - "allowedTools": ["fs_read"], - "toolsSettings": { - "fs_write": { - "allowedPaths": ["~/projects"] - } - }, - "resources": [ - "file://README.md", - "file://docs/**/*.md" - ] -} -``` - -### 3.4 Kiro CLIのフック - -**フック設定**: エージェント設定内の`hooks`フィールド - -```json -{ - "hooks": { - "agentSpawn": [...], - "userPromptSubmit": [...], - "preToolUse": [...], - "postToolUse": [...], - "stop": [...] - } -} -``` - -### 3.5 Kiro CLIのMCP - -**MCP設定**: `.kiro/mcp.json` - -```json -{ - "mcpServers": { - "server-name": { - "command": "...", - "args": [...], - "env": {...} - } - } -} -``` - -### 3.6 Kiro CLIのプロンプト - -**プロンプト**: `.kiro/prompts/{name}.md` - -- `@research`: コードベース調査 -- `@plan`: 実装計画作成 -- `@implement`: 計画実行 -- `@validate`: 実装検証 -- `@commit`: Git コミット - -## 4. 機能マッピング - -| Claude Code機能 | Kiro CLI相当機能 | 移植可否 | 備考 | -|----------------|-----------------|---------|------| -| Marketplace | なし | ❌ | Kiro CLIに概念なし | -| Plugin | なし | ❌ | Kiro CLIに概念なし | -| Commands | スラッシュコマンド | ⚠️ | 組み込みのみ、カスタム不可 | -| Agents | エージェント設定 | ✅ | JSON設定で実現可能 | -| Skills | なし | ⚠️ | プロンプト+エージェントで代替 | -| Hooks | フック | ✅ | 同等機能あり | -| MCP | MCP | ✅ | 同等機能あり | - -### 4.1 移植戦略 - -#### ✅ 直接移植可能 -- **MCP統合**: `.kiro/mcp.json`に設定 -- **フック**: エージェント設定の`hooks`フィールド -- **エージェント**: `.kiro/agents/`にJSON設定 - -#### ⚠️ 代替実装が必要 -- **カスタムコマンド**: プロンプト（`.kiro/prompts/`）で代替 -- **スキル**: プロンプト+エージェント設定で代替 - -#### ❌ 移植不可 -- **Marketplace**: Kiro CLIに概念なし -- **Plugin**: Kiro CLIに概念なし - -## 5. 結論 - -### 5.1 移植 vs 拡張 - -**結論**: **別リポジトリで移植** - -**理由**: -1. Kiro CLIにはMarketplace/Plugin概念がない -2. 同じリポジトリで管理すると混乱を招く -3. Kiro CLI向けの独自構造が必要 - -### 5.2 新リポジトリ名案 - -- `kiro-ndf-config` -- `ndf-kiro` -- `kiro-ndf-agents` - -### 5.3 移植範囲 - -**Phase 1: コア機能** -- MCP統合（7サーバー） -- 基本エージェント（6種類） -- 基本フック（Slack通知） - -**Phase 2: 拡張機能** -- プロンプト（コマンド代替） -- スキル相当のプロンプト - -**Phase 3: ドキュメント** -- インストールガイド -- 使用方法 -- トラブルシューティング diff --git a/issues/PLAN10/02-migration-plan.md b/issues/PLAN10/02-migration-plan.md deleted file mode 100644 index d71ab831..00000000 --- a/issues/PLAN10/02-migration-plan.md +++ /dev/null @@ -1,376 +0,0 @@ -# Kiro CLI移植計画 - -## プロジェクト概要 - -**目的**: Claude Code用NDFプラグインをKiro CLI向けに移植し、同等の開発体験を提供する - -**アプローチ**: 別リポジトリで新規プロジェクトとして移植 - -**新リポジトリ名**: `kiro-ndf-config` - -## Phase 1: プロジェクト基盤構築 - -### 1.1 リポジトリ作成 - -**タスク**: -- [ ] GitHubリポジトリ作成: `kiro-ndf-config` -- [ ] 基本ディレクトリ構造作成 -- [ ] README.md作成 -- [ ] LICENSE追加（MIT） -- [ ] .gitignore設定 - -**ディレクトリ構造**: -``` -kiro-ndf-config/ -├── .kiro/ -│ ├── agents/ # エージェント設定 -│ ├── prompts/ # プロンプト（コマンド代替） -│ └── mcp.json # MCP設定 -├── scripts/ # ヘルパースクリプト -├── docs/ # ドキュメント -├── .env.example # 環境変数テンプレート -├── README.md -└── LICENSE -``` - -### 1.2 ドキュメント作成 - -**タスク**: -- [ ] README.md: プロジェクト概要、インストール手順 -- [ ] INSTALL.md: 詳細インストールガイド -- [ ] USAGE.md: 使用方法 -- [ ] AGENTS.md: エージェント説明 -- [ ] MCP.md: MCP設定ガイド - -## Phase 2: MCP統合 - -### 2.1 MCP設定ファイル作成 - -**タスク**: -- [ ] `.kiro/mcp.json`作成 -- [ ] 7つのMCPサーバー設定を移植: - - [ ] Serena MCP - - [ ] Notion MCP - - [ ] BigQuery MCP - - [ ] DBHub MCP - - [ ] Chrome DevTools MCP - - [ ] AWS Docs MCP - - [ ] Codex CLI MCP - -**設定例**: -```json -{ - "mcpServers": { - "serena": { - "command": "uvx", - "args": [ - "--from", - "git+https://github.com/oraios/serena", - "serena", - "start-mcp-server", - "--context", - "ide-assistant", - "--enable-web-dashboard", - "False" - ], - "env": { - "SERENA_HOME": "${SERENA_HOME:-.serena}", - "GOOGLE_API_KEY": "${GOOGLE_API_KEY}", - "ANTHROPIC_API_KEY": "${ANTHROPIC_API_KEY}" - } - } - } -} -``` - -### 2.2 環境変数テンプレート - -**タスク**: -- [ ] `.env.example`作成 -- [ ] 各MCPサーバーの必要な環境変数を記載 -- [ ] コメントで取得方法を説明 - -## Phase 3: エージェント移植 - -### 3.1 基本エージェント作成 - -**タスク**: -- [ ] `.kiro/agents/director.json` - タスク統括 -- [ ] `.kiro/agents/data-analyst.json` - データ分析 -- [ ] `.kiro/agents/corder.json` - コーディング -- [ ] `.kiro/agents/researcher.json` - 調査 -- [ ] `.kiro/agents/scanner.json` - ファイル読み取り -- [ ] `.kiro/agents/qa.json` - 品質管理 - -**エージェント設定例** (director.json): -```json -{ - "description": "タスク統括・指揮者エージェント。複雑なタスクを分解し、適切なサブエージェントに委譲します。", - "tools": ["@builtin", "@serena/*", "@github/*"], - "allowedTools": ["fs_read", "fs_write", "execute_bash", "use_subagent"], - "toolsSettings": { - "execute_bash": { - "autoAllowReadonly": true - } - }, - "resources": [ - "file://README.md", - "file://docs/**/*.md" - ], - "hooks": { - "agentSpawn": [ - { - "command": "echo 'Director agent activated'", - "description": "エージェント起動通知" - } - ] - } -} -``` - -### 3.2 エージェント間連携 - -**タスク**: -- [ ] `use_subagent`ツールの活用方法をドキュメント化 -- [ ] エージェント選択ガイドライン作成 -- [ ] サブエージェント呼び出しパターン例 - -## Phase 4: プロンプト作成（コマンド代替） - -### 4.1 開発ワークフロープロンプト - -**タスク**: -- [ ] `.kiro/prompts/pr.md` - PR作成ワークフロー -- [ ] `.kiro/prompts/pr-tests.md` - Test Plan自動実行 -- [ ] `.kiro/prompts/fix.md` - レビュー指摘修正 -- [ ] `.kiro/prompts/review.md` - コードレビュー -- [ ] `.kiro/prompts/merged.md` - マージ後処理 -- [ ] `.kiro/prompts/clean.md` - ブランチクリーンアップ - -**プロンプト例** (pr.md): -```markdown ---- -name: pr -description: Pull Request作成ワークフロー ---- - -# PR作成ワークフロー - -このプロンプトは、Pull Request作成を支援します。 - -## 手順 - -1. 変更内容の確認 -2. コミットメッセージの作成 -3. PRタイトルと説明の生成 -4. テストの実行確認 - -## 使用方法 - -``` -@pr -``` - -## 実行内容 - -[詳細な手順...] -``` - -### 4.2 Memory管理プロンプト - -**タスク**: -- [ ] `.kiro/prompts/mem-review.md` - Memory戦略レビュー -- [ ] `.kiro/prompts/mem-capture.md` - Memory記録 - -### 4.3 Serena操作プロンプト - -**タスク**: -- [ ] `.kiro/prompts/serena.md` - Serena MCP操作ガイド - -## Phase 5: スキル相当機能 - -### 5.1 スキルプロンプト作成 - -**タスク**: -- [ ] `.kiro/prompts/skills/sql-optimization.md` -- [ ] `.kiro/prompts/skills/code-templates.md` -- [ ] `.kiro/prompts/skills/test-generation.md` -- [ ] `.kiro/prompts/skills/pdf-analysis.md` -- [ ] `.kiro/prompts/skills/excel-extraction.md` -- [ ] `.kiro/prompts/skills/security-scan.md` -- [ ] `.kiro/prompts/skills/markdown-writing.md` -- [ ] `.kiro/prompts/skills/python-execution.md` -- [ ] `.kiro/prompts/skills/docker-access.md` - -**スキルプロンプト例**: -```markdown ---- -name: sql-optimization -description: SQL最適化支援 ---- - -# SQL最適化 - -このプロンプトは、SQLクエリの最適化を支援します。 - -## 最適化パターン - -1. インデックス活用 -2. JOIN最適化 -3. サブクエリ改善 - -[詳細...] -``` - -## Phase 6: フック実装 - -### 6.1 Slack通知フック - -**タスク**: -- [ ] `scripts/slack-notify.sh`作成 -- [ ] エージェント設定に`stop`フック追加 -- [ ] Slack Webhook URL設定ガイド - -**フック設定例**: -```json -{ - "hooks": { - "stop": [ - { - "command": "bash ${KIRO_CONFIG_ROOT}/scripts/slack-notify.sh", - "description": "Slack通知送信" - } - ] - } -} -``` - -### 6.2 セットアップフック - -**タスク**: -- [ ] `scripts/setup-memory.sh`作成 -- [ ] エージェント設定に`agentSpawn`フック追加 - -## Phase 7: インストールスクリプト - -### 7.1 自動セットアップスクリプト - -**タスク**: -- [ ] `scripts/install.sh`作成 -- [ ] 以下の処理を自動化: - - [ ] `.kiro/`ディレクトリのコピー - - [ ] `.env`ファイルの作成（`.env.example`から） - - [ ] MCP設定の確認 - - [ ] 必要なツールのインストール確認 - -**インストールスクリプト例**: -```bash -#!/bin/bash -set -e - -echo "Kiro NDF Config インストール開始..." - -# .kiro/ディレクトリをコピー -cp -r .kiro ~/.kiro/ndf-config - -# .envファイル作成 -if [ ! -f .env ]; then - cp .env.example .env - echo ".envファイルを作成しました。必要な環境変数を設定してください。" -fi - -echo "インストール完了！" -``` - -## Phase 8: ドキュメント整備 - -### 8.1 ユーザーガイド - -**タスク**: -- [ ] `docs/getting-started.md` - 初心者向けガイド -- [ ] `docs/agents-guide.md` - エージェント使用ガイド -- [ ] `docs/prompts-guide.md` - プロンプト使用ガイド -- [ ] `docs/mcp-setup.md` - MCP設定詳細 -- [ ] `docs/troubleshooting.md` - トラブルシューティング - -### 8.2 開発者ガイド - -**タスク**: -- [ ] `docs/development.md` - カスタマイズガイド -- [ ] `docs/contributing.md` - コントリビューションガイド - -## Phase 9: テストとデバッグ - -### 9.1 機能テスト - -**タスク**: -- [ ] 各エージェントの動作確認 -- [ ] MCP統合の動作確認 -- [ ] プロンプトの動作確認 -- [ ] フックの動作確認 - -### 9.2 ドキュメントレビュー - -**タスク**: -- [ ] インストール手順の検証 -- [ ] 使用例の検証 -- [ ] トラブルシューティングの検証 - -## Phase 10: リリース - -### 10.1 バージョン管理 - -**タスク**: -- [ ] CHANGELOG.md作成 -- [ ] バージョン1.0.0リリース -- [ ] GitHubリリースノート作成 - -### 10.2 公開 - -**タスク**: -- [ ] README.mdの最終確認 -- [ ] リポジトリの公開設定 -- [ ] コミュニティへの告知 - -## 成功基準 - -### 機能要件 -- ✅ 7つのMCPサーバーが正常に動作 -- ✅ 6つのエージェントが利用可能 -- ✅ 9つのプロンプト（コマンド代替）が動作 -- ✅ Slack通知フックが動作 - -### ドキュメント要件 -- ✅ インストール手順が明確 -- ✅ 使用方法が理解しやすい -- ✅ トラブルシューティングが充実 - -### ユーザー体験 -- ✅ Claude Code NDFプラグインと同等の機能 -- ✅ Kiro CLI固有の利点を活用 -- ✅ 簡単にセットアップ可能 - -## リスクと対策 - -### リスク1: MCP互換性 -**対策**: 各MCPサーバーの動作確認を徹底 - -### リスク2: エージェント設定の複雑さ -**対策**: デフォルト設定を提供、段階的なカスタマイズを推奨 - -### リスク3: ドキュメント不足 -**対策**: 豊富な例とトラブルシューティングを用意 - -## タイムライン - -- **Week 1-2**: Phase 1-3（基盤、MCP、エージェント） -- **Week 3-4**: Phase 4-6（プロンプト、スキル、フック） -- **Week 5**: Phase 7-8（インストール、ドキュメント） -- **Week 6**: Phase 9-10（テスト、リリース） - -## 次のステップ - -1. GitHubリポジトリ作成 -2. 基本ディレクトリ構造の作成 -3. MCP設定ファイルの作成 -4. 最初のエージェント（director）の実装 diff --git a/issues/PLAN10/03-installation-usage.md b/issues/PLAN10/03-installation-usage.md deleted file mode 100644 index 65dd8b85..00000000 --- a/issues/PLAN10/03-installation-usage.md +++ /dev/null @@ -1,424 +0,0 @@ -# インストール方法と利用方法 - -## インストール方法 - -### 前提条件 - -**必須**: -- Kiro CLI がインストール済み -- Git -- Python 3.10以上（BigQuery MCP用） -- `uvx` がインストール済み（`pip install uv`） - -**オプション**: -- Node.js（DBHub、Chrome DevTools MCP用） -- Codex CLI（Codex CLI MCP用） - -### ステップ1: リポジトリのクローン - -```bash -git clone https://github.com/takemi-ohama/kiro-ndf-config.git -cd kiro-ndf-config -``` - -### ステップ2: 自動インストール - -```bash -./scripts/install.sh -``` - -このスクリプトは以下を実行します： -1. `.kiro/`ディレクトリをホームディレクトリにコピー -2. `.env`ファイルを作成（`.env.example`から） -3. 必要なツールのインストール確認 - -### ステップ3: 環境変数の設定 - -`.env`ファイルを編集し、必要な認証情報を設定します： - -```bash -# Serena MCP (推奨) -SERENA_HOME=.serena -GOOGLE_API_KEY=your_google_api_key -ANTHROPIC_API_KEY=your_anthropic_api_key - -# Notion MCP (オプション) -NOTION_TOKEN=your_notion_token - -# BigQuery MCP (オプション) -BIGQUERY_PROJECT=your_project_id -BIGQUERY_LOCATION=US -BIGQUERY_KEY_FILE=/path/to/service-account-key.json - -# DBHub MCP (オプション) -DSN=your_database_connection_string - -# Slack通知 (オプション) -SLACK_BOT_TOKEN=your_slack_bot_token -SLACK_CHANNEL_ID=your_channel_id -SLACK_USER_MENTION=<@U0123456789> -``` - -### ステップ4: MCP設定の確認 - -```bash -kiro-cli mcp -``` - -7つのMCPサーバーが表示されることを確認します。 - -### ステップ5: エージェントの確認 - -```bash -kiro-cli agent list -``` - -6つのエージェント（director、data-analyst、corder、researcher、scanner、qa）が表示されることを確認します。 - -## 利用方法 - -### 基本的な使い方 - -#### 1. エージェントの起動 - -```bash -# Directorエージェント（タスク統括） -kiro-cli chat --agent director - -# データ分析エージェント -kiro-cli chat --agent data-analyst - -# コーディングエージェント -kiro-cli chat --agent corder - -# 調査エージェント -kiro-cli chat --agent researcher - -# ファイル読み取りエージェント -kiro-cli chat --agent scanner - -# 品質管理エージェント -kiro-cli chat --agent qa -``` - -#### 2. プロンプトの使用 - -プロンプトは`@`で呼び出します： - -```bash -# PR作成ワークフロー -@pr - -# Test Plan自動実行 -@pr-tests - -# レビュー指摘修正 -@fix - -# コードレビュー -@review - -# マージ後処理 -@merged - -# ブランチクリーンアップ -@clean - -# Memory戦略レビュー -@mem-review - -# Memory記録 -@mem-capture - -# Serena MCP操作ガイド -@serena -``` - -#### 3. スキルプロンプトの使用 - -```bash -# SQL最適化 -@sql-optimization - -# コードテンプレート -@code-templates - -# テスト生成 -@test-generation - -# PDF解析 -@pdf-analysis - -# Excel抽出 -@excel-extraction - -# セキュリティスキャン -@security-scan - -# Markdown文書作成 -@markdown-writing - -# Python実行環境判定 -@python-execution - -# Dockerコンテナアクセス -@docker-access -``` - -### エージェント別の使用例 - -#### Directorエージェント（タスク統括） - -複雑なタスクを分解し、適切なサブエージェントに委譲します。 - -```bash -kiro-cli chat --agent director - -> 新しいREST APIを実装してください。認証、データベース接続、テストも含めて。 - -# Directorが以下のように分解: -# 1. Corderエージェント: API実装 -# 2. Data-analystエージェント: データベース設計 -# 3. QAエージェント: テスト作成 -``` - -#### Data-analystエージェント（データ分析） - -BigQuery、DBHubを使用したデータ分析。 - -```bash -kiro-cli chat --agent data-analyst - -> BigQueryでユーザーの行動分析を実行してください - -# BigQuery MCPを使用してクエリ実行 -# 結果の可視化と分析 -``` - -#### Corderエージェント（コーディング） - -GitHub、Serenaを使用したコーディング支援。 - -```bash -kiro-cli chat --agent corder - -> ユーザー認証機能を実装してください - -# Serena MCPでコード構造を理解 -# GitHub MCPでPR作成 -``` - -#### Researcherエージェント（調査） - -Web検索、AWS Docsを使用した調査。 - -```bash -kiro-cli chat --agent researcher - -> AWS Lambdaのベストプラクティスを調査してください - -# AWS Docs MCPで公式ドキュメント検索 -# Web検索で最新情報収集 -``` - -#### Scannerエージェント（ファイル読み取り） - -PDF、Excelファイルの解析。 - -```bash -kiro-cli chat --agent scanner - -> この請求書PDFから金額を抽出してください - -# PDF解析スキルを使用 -# 構造化データとして出力 -``` - -#### QAエージェント（品質管理） - -セキュリティスキャン、コードレビュー。 - -```bash -kiro-cli chat --agent qa - -> このコードのセキュリティ脆弱性をチェックしてください - -# セキュリティスキャンスキルを使用 -# OWASP Top 10チェック -``` - -### ワークフロー例 - -#### PR作成ワークフロー - -```bash -kiro-cli chat --agent corder - -> @pr - -# 1. 変更内容の確認 -# 2. コミットメッセージの作成 -# 3. PRタイトルと説明の生成 -# 4. GitHub MCPでPR作成 -``` - -#### レビュー対応ワークフロー - -```bash -kiro-cli chat --agent corder - -> @fix - -# 1. PRのレビューコメント取得 -# 2. 指摘事項の修正 -# 3. コミット -# 4. レビュー対応コメント -``` - -#### マージ後処理ワークフロー - -```bash -kiro-cli chat --agent director - -> @merged - -# 1. マージ確認 -# 2. ローカルブランチの削除 -# 3. リモートブランチの削除 -# 4. mainブランチの更新 -``` - -### MCP統合の活用 - -#### Serena MCP（セマンティックコード操作） - -```bash -kiro-cli chat --agent corder - -> Serenaを使ってこのファイルのシンボル一覧を取得してください - -# Serena MCPのget_symbols_overviewを使用 -``` - -#### Notion MCP（Notion統合） - -```bash -kiro-cli chat --agent researcher - -> Notionのプロジェクトページを更新してください - -# Notion MCPでページ更新 -``` - -#### BigQuery MCP（BigQueryクエリ） - -```bash -kiro-cli chat --agent data-analyst - -> BigQueryでユーザーテーブルから集計してください - -# BigQuery MCPでクエリ実行 -``` - -### フックの活用 - -#### Slack通知 - -エージェント終了時に自動的にSlack通知が送信されます。 - -```bash -# .envファイルでSlack設定 -SLACK_BOT_TOKEN=xoxb-... -SLACK_CHANNEL_ID=C0123456789 -SLACK_USER_MENTION=<@U0123456789> - -# エージェント終了時に自動通知 -kiro-cli chat --agent director -> タスク完了 -> /quit - -# Slackに通知が送信される -``` - -## トラブルシューティング - -### MCPサーバーが起動しない - -```bash -# MCP設定の確認 -kiro-cli mcp - -# ログの確認 -kiro-cli logdump - -# 環境変数の確認 -cat .env -``` - -### エージェントが見つからない - -```bash -# エージェント一覧の確認 -kiro-cli agent list - -# エージェント設定ファイルの確認 -ls ~/.kiro/agents/ -``` - -### プロンプトが動作しない - -```bash -# プロンプト一覧の確認 -kiro-cli prompts - -# プロンプトファイルの確認 -ls ~/.kiro/prompts/ -``` - -## アップデート - -```bash -cd kiro-ndf-config -git pull -./scripts/install.sh -``` - -## アンインストール - -```bash -# エージェント設定の削除 -rm -rf ~/.kiro/agents/director.json -rm -rf ~/.kiro/agents/data-analyst.json -rm -rf ~/.kiro/agents/corder.json -rm -rf ~/.kiro/agents/researcher.json -rm -rf ~/.kiro/agents/scanner.json -rm -rf ~/.kiro/agents/qa.json - -# プロンプトの削除 -rm -rf ~/.kiro/prompts/pr.md -rm -rf ~/.kiro/prompts/pr-tests.md -rm -rf ~/.kiro/prompts/fix.md -rm -rf ~/.kiro/prompts/review.md -rm -rf ~/.kiro/prompts/merged.md -rm -rf ~/.kiro/prompts/clean.md -rm -rf ~/.kiro/prompts/mem-review.md -rm -rf ~/.kiro/prompts/mem-capture.md -rm -rf ~/.kiro/prompts/serena.md - -# MCP設定の削除 -rm -rf ~/.kiro/mcp.json -``` - -## サポート - -問題が発生した場合： -1. [トラブルシューティングガイド](docs/troubleshooting.md)を確認 -2. [GitHubイシュー](https://github.com/takemi-ohama/kiro-ndf-config/issues)を作成 -3. [ドキュメント](docs/)を参照 - -## 参考リンク - -- [Kiro CLI公式ドキュメント](https://kiro.dev/docs/cli/) -- [MCP仕様](https://modelcontextprotocol.io) -- [Serena MCP](https://github.com/oraios/serena) -- [元のNDFプラグイン](https://github.com/takemi-ohama/ai-plugins/tree/main/plugins/ndf) diff --git a/issues/PLAN10/04-feature-comparison.md b/issues/PLAN10/04-feature-comparison.md deleted file mode 100644 index cf9dea25..00000000 --- a/issues/PLAN10/04-feature-comparison.md +++ /dev/null @@ -1,216 +0,0 @@ -# 機能比較表 - -## Claude Code NDFプラグイン vs Kiro CLI移植版 - -| 機能カテゴリ | Claude Code NDF | Kiro CLI移植版 | 実装方法 | 備考 | -|------------|----------------|---------------|---------|------| -| **MCP統合** | ✅ 7サーバー | ✅ 7サーバー | `.kiro/mcp.json` | 同等 | -| **エージェント** | ✅ 6種類 | ✅ 6種類 | `.kiro/agents/*.json` | 同等 | -| **カスタムコマンド** | ✅ 9コマンド | ⚠️ プロンプト | `.kiro/prompts/*.md` | 代替実装 | -| **スキル** | ✅ 13スキル | ⚠️ プロンプト | `.kiro/prompts/skills/*.md` | 代替実装 | -| **フック** | ✅ SessionStart, Stop | ✅ agentSpawn, stop | エージェント設定 | 同等 | -| **Slack通知** | ✅ 自動 | ✅ 自動 | stopフック | 同等 | -| **Marketplace** | ✅ あり | ❌ なし | - | Kiro CLIに概念なし | -| **Plugin** | ✅ あり | ❌ なし | - | Kiro CLIに概念なし | - -## 詳細機能比較 - -### MCP統合 - -| MCPサーバー | Claude Code | Kiro CLI | 設定方法 | 互換性 | -|-----------|-------------|----------|---------|--------| -| Serena | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| Notion | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| BigQuery | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| DBHub | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| Chrome DevTools | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| AWS Docs | ✅ | ✅ | `.kiro/mcp.json` | 100% | -| Codex CLI | ✅ | ✅ | `.kiro/mcp.json` | 100% | - -### エージェント - -| エージェント | Claude Code | Kiro CLI | 実装方法 | 機能差異 | -|------------|-------------|----------|---------|---------| -| Director | ✅ | ✅ | `.kiro/agents/director.json` | なし | -| Data-analyst | ✅ | ✅ | `.kiro/agents/data-analyst.json` | なし | -| Corder | ✅ | ✅ | `.kiro/agents/corder.json` | なし | -| Researcher | ✅ | ✅ | `.kiro/agents/researcher.json` | なし | -| Scanner | ✅ | ✅ | `.kiro/agents/scanner.json` | なし | -| QA | ✅ | ✅ | `.kiro/agents/qa.json` | なし | - -### カスタムコマンド → プロンプト - -| コマンド | Claude Code | Kiro CLI | 実装方法 | UX差異 | -|---------|-------------|----------|---------|--------| -| `/ndf:pr` | ✅ | ⚠️ `@pr` | `.kiro/prompts/pr.md` | `/`→`@` | -| `/ndf:pr-tests` | ✅ | ⚠️ `@pr-tests` | `.kiro/prompts/pr-tests.md` | `/`→`@` | -| `/ndf:fix` | ✅ | ⚠️ `@fix` | `.kiro/prompts/fix.md` | `/`→`@` | -| `/ndf:review` | ✅ | ⚠️ `@review` | `.kiro/prompts/review.md` | `/`→`@` | -| `/ndf:merged` | ✅ | ⚠️ `@merged` | `.kiro/prompts/merged.md` | `/`→`@` | -| `/ndf:clean` | ✅ | ⚠️ `@clean` | `.kiro/prompts/clean.md` | `/`→`@` | -| `/ndf:mem-review` | ✅ | ⚠️ `@mem-review` | `.kiro/prompts/mem-review.md` | `/`→`@` | -| `/ndf:mem-capture` | ✅ | ⚠️ `@mem-capture` | `.kiro/prompts/mem-capture.md` | `/`→`@` | -| `/ndf:serena` | ✅ | ⚠️ `@serena` | `.kiro/prompts/serena.md` | `/`→`@` | - -**UX差異の説明**: -- Claude Code: `/ndf:pr`（スラッシュコマンド） -- Kiro CLI: `@pr`（プロンプト） -- 機能的には同等だが、呼び出し方法が異なる - -### スキル → プロンプト - -| スキル | Claude Code | Kiro CLI | 実装方法 | 自動起動 | -|--------|-------------|----------|---------|---------| -| SQL最適化 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/sql-optimization.md` | ❌ | -| コードテンプレート | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/code-templates.md` | ❌ | -| テスト生成 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/test-generation.md` | ❌ | -| PDF解析 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/pdf-analysis.md` | ❌ | -| Excel抽出 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/excel-extraction.md` | ❌ | -| セキュリティスキャン | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/security-scan.md` | ❌ | -| Markdown文書作成 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/markdown-writing.md` | ❌ | -| Python実行環境判定 | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/python-execution.md` | ❌ | -| Dockerコンテナアクセス | ✅ 自動 | ⚠️ 手動 | `.kiro/prompts/skills/docker-access.md` | ❌ | - -**自動起動の差異**: -- Claude Code: スキルは特定のキーワードで自動起動 -- Kiro CLI: プロンプトは明示的に`@skill-name`で呼び出し -- 機能的には同等だが、UXが異なる - -### フック - -| フック | Claude Code | Kiro CLI | 実装方法 | 互換性 | -|--------|-------------|----------|---------|--------| -| SessionStart | ✅ | ✅ agentSpawn | エージェント設定 | 同等 | -| Stop | ✅ | ✅ stop | エージェント設定 | 同等 | -| PreToolUse | ✅ | ✅ preToolUse | エージェント設定 | 同等 | -| PostToolUse | ✅ | ✅ postToolUse | エージェント設定 | 同等 | - -### Slack通知 - -| 機能 | Claude Code | Kiro CLI | 実装方法 | 互換性 | -|------|-------------|----------|---------|--------| -| セッション終了通知 | ✅ | ✅ | stopフック | 100% | -| AI要約生成 | ✅ | ✅ | スクリプト | 100% | -| メンション | ✅ | ✅ | 環境変数 | 100% | - -## ユーザー体験の違い - -### コマンド実行 - -**Claude Code**: -``` -/ndf:pr -``` - -**Kiro CLI**: -``` -@pr -``` - -### スキル起動 - -**Claude Code**: -``` -# 自動起動（キーワード検出） -> SQLクエリを最適化してください -# → SQL最適化スキルが自動起動 -``` - -**Kiro CLI**: -``` -# 明示的呼び出し -@sql-optimization -> SQLクエリを最適化してください -``` - -### エージェント切り替え - -**Claude Code**: -``` -# サブエージェント呼び出し -/agent data-analyst -``` - -**Kiro CLI**: -``` -# エージェント切り替え -/agent data-analyst - -# またはサブエージェント使用 -> use_subagent tool -``` - -## 移植による利点 - -### Kiro CLI固有の利点 - -| 機能 | 説明 | Claude Codeにない利点 | -|------|------|---------------------| -| `/code` | LSP統合 | コードインテリジェンス | -| `/knowledge` | ナレッジベース | 永続的な知識管理 | -| `/todos` | TODOリスト | タスク管理 | -| `/checkpoint` | チェックポイント | 状態管理 | -| `/tangent` | タンジェントモード | 会話分岐 | -| AWS統合 | `use_aws`ツール | AWS CLI統合 | - -### 統合の可能性 - -Kiro CLI移植版では、以下の統合が可能： - -1. **コードインテリジェンス + Serena MCP** - - LSPとSerenaの組み合わせで強力なコード理解 - -2. **ナレッジベース + プロジェクトドキュメント** - - `/knowledge`でプロジェクト知識を永続化 - -3. **TODOリスト + タスク管理** - - `/todos`でタスク追跡 - -4. **AWS統合 + AWS Docs MCP** - - `use_aws`とAWS Docs MCPの組み合わせ - -## 移植の制約 - -### 実装できない機能 - -| 機能 | 理由 | 代替案 | -|------|------|--------| -| Marketplace | Kiro CLIに概念なし | Gitリポジトリで配布 | -| Plugin | Kiro CLIに概念なし | 設定ファイルで配布 | -| スキル自動起動 | Kiro CLIに機能なし | プロンプトで明示的呼び出し | -| カスタムスラッシュコマンド | Kiro CLIに機能なし | プロンプトで代替 | - -### UXの違い - -| 項目 | Claude Code | Kiro CLI | 影響 | -|------|-------------|----------|------| -| コマンド呼び出し | `/ndf:command` | `@command` | 軽微 | -| スキル起動 | 自動 | 手動 | 中程度 | -| プラグインインストール | `/plugin install` | `git clone` + `./install.sh` | 中程度 | -| 更新 | `/plugin update` | `git pull` + `./install.sh` | 軽微 | - -## 推奨事項 - -### ユーザーへの推奨 - -1. **Claude Codeユーザー**: - - NDFプラグインを使用（ネイティブ体験） - -2. **Kiro CLIユーザー**: - - Kiro NDF Configを使用（同等機能） - - Kiro CLI固有機能も活用 - -3. **両方使用**: - - 環境に応じて使い分け - - 設定は別々に管理 - -### 開発者への推奨 - -1. **新機能追加時**: - - 両方のプラットフォームで実装を検討 - -2. **ドキュメント**: - - プラットフォーム別のガイドを提供 - -3. **互換性**: - - 可能な限り同等の体験を提供 diff --git a/issues/PLAN10/README.md b/issues/PLAN10/README.md deleted file mode 100644 index ec7f0db2..00000000 --- a/issues/PLAN10/README.md +++ /dev/null @@ -1,195 +0,0 @@ -# Kiro CLI移植計画 - サマリー - -## 調査結果 - -### NDFプラグインの構成 -- **MCP統合**: 7サーバー（Serena、Notion、BigQuery、DBHub、Chrome DevTools、AWS Docs、Codex CLI） -- **カスタムコマンド**: 9コマンド（PR作成、テスト実行、レビュー、修正、マージ、クリーンアップ、Memory管理） -- **サブエージェント**: 6種類（director、data-analyst、corder、researcher、scanner、qa） -- **スキル**: 13個（SQL最適化、コードテンプレート、テスト生成、PDF解析、Excel抽出、セキュリティスキャン等） -- **フック**: SessionStart、Stop（Slack通知） - -### Kiro CLIの類似機能 -- **MCP統合**: ✅ 同等機能あり（`.kiro/mcp.json`） -- **エージェント**: ✅ 同等機能あり（`.kiro/agents/*.json`） -- **カスタムコマンド**: ⚠️ プロンプト（`.kiro/prompts/*.md`）で代替 -- **スキル**: ⚠️ プロンプトで代替（自動起動は不可） -- **フック**: ✅ 同等機能あり（エージェント設定内） -- **Marketplace/Plugin**: ❌ 概念なし - -## 移植戦略 - -### 結論: 別リポジトリで移植 - -**新リポジトリ名**: `kiro-ndf-config` - -**理由**: -1. Kiro CLIにはMarketplace/Plugin概念がない -2. 同じリポジトリで管理すると混乱を招く -3. Kiro CLI向けの独自構造が必要 - -### 機能マッピング - -| Claude Code機能 | Kiro CLI実装 | 互換性 | -|----------------|-------------|--------| -| MCP統合 | `.kiro/mcp.json` | 100% | -| エージェント | `.kiro/agents/*.json` | 100% | -| カスタムコマンド | `.kiro/prompts/*.md` | 代替（`/`→`@`） | -| スキル | `.kiro/prompts/skills/*.md` | 代替（手動起動） | -| フック | エージェント設定 | 100% | - -## 実装計画 - -### Phase 1: プロジェクト基盤（Week 1-2） -- GitHubリポジトリ作成 -- ディレクトリ構造作成 -- 基本ドキュメント作成 - -### Phase 2: MCP統合（Week 1-2） -- `.kiro/mcp.json`作成 -- 7つのMCPサーバー設定 -- `.env.example`作成 - -### Phase 3: エージェント移植（Week 1-2） -- 6つのエージェント設定作成 -- エージェント間連携ドキュメント - -### Phase 4: プロンプト作成（Week 3-4） -- 9つの開発ワークフロープロンプト -- 13個のスキルプロンプト - -### Phase 5: フック実装（Week 3-4） -- Slack通知スクリプト -- セットアップスクリプト - -### Phase 6: インストールスクリプト（Week 5） -- 自動セットアップスクリプト -- 環境確認スクリプト - -### Phase 7: ドキュメント整備（Week 5） -- ユーザーガイド -- 開発者ガイド -- トラブルシューティング - -### Phase 8: テストとリリース（Week 6） -- 機能テスト -- ドキュメントレビュー -- v1.0.0リリース - -## インストール方法（予定） - -```bash -# リポジトリのクローン -git clone https://github.com/takemi-ohama/kiro-ndf-config.git -cd kiro-ndf-config - -# 自動インストール -./scripts/install.sh - -# 環境変数の設定 -vi .env - -# 確認 -kiro-cli mcp -kiro-cli agent list -``` - -## 利用方法（予定） - -### エージェント起動 -```bash -kiro-cli chat --agent director -kiro-cli chat --agent data-analyst -kiro-cli chat --agent corder -``` - -### プロンプト使用 -```bash -@pr # PR作成 -@review # コードレビュー -@fix # レビュー修正 -@sql-optimization # SQL最適化 -``` - -### MCP活用 -```bash -# Serena MCPでコード操作 -> Serenaを使ってシンボル一覧を取得 - -# BigQuery MCPでデータ分析 -> BigQueryでユーザー集計 -``` - -## ユーザー体験の違い - -### コマンド呼び出し -- **Claude Code**: `/ndf:pr` -- **Kiro CLI**: `@pr` - -### スキル起動 -- **Claude Code**: 自動起動（キーワード検出） -- **Kiro CLI**: 明示的呼び出し（`@skill-name`） - -### プラグインインストール -- **Claude Code**: `/plugin install ndf@ai-plugins` -- **Kiro CLI**: `git clone` + `./install.sh` - -## Kiro CLI固有の利点 - -移植版では、Kiro CLI固有の機能も活用可能： - -1. **コードインテリジェンス** (`/code`): LSP統合 -2. **ナレッジベース** (`/knowledge`): 永続的な知識管理 -3. **TODOリスト** (`/todos`): タスク管理 -4. **チェックポイント** (`/checkpoint`): 状態管理 -5. **タンジェントモード** (`/tangent`): 会話分岐 -6. **AWS統合** (`use_aws`): AWS CLI統合 - -## 成功基準 - -### 機能要件 -- ✅ 7つのMCPサーバーが正常に動作 -- ✅ 6つのエージェントが利用可能 -- ✅ 9つのプロンプト（コマンド代替）が動作 -- ✅ 13個のスキルプロンプトが動作 -- ✅ Slack通知フックが動作 - -### ドキュメント要件 -- ✅ インストール手順が明確 -- ✅ 使用方法が理解しやすい -- ✅ トラブルシューティングが充実 - -### ユーザー体験 -- ✅ Claude Code NDFプラグインと同等の機能 -- ✅ Kiro CLI固有の利点を活用 -- ✅ 簡単にセットアップ可能 - -## リスクと対策 - -### リスク1: MCP互換性 -**対策**: 各MCPサーバーの動作確認を徹底 - -### リスク2: エージェント設定の複雑さ -**対策**: デフォルト設定を提供、段階的なカスタマイズを推奨 - -### リスク3: ドキュメント不足 -**対策**: 豊富な例とトラブルシューティングを用意 - -### リスク4: UXの違い -**対策**: 明確なドキュメントと移行ガイド - -## 次のステップ - -1. ✅ 調査完了 -2. ✅ 移植計画作成 -3. ⏭️ GitHubリポジトリ作成 -4. ⏭️ 基本ディレクトリ構造の作成 -5. ⏭️ MCP設定ファイルの作成 -6. ⏭️ 最初のエージェント（director）の実装 - -## 参考資料 - -- [調査結果](./01-analysis.md) -- [移植計画](./02-migration-plan.md) -- [インストール・利用方法](./03-installation-usage.md) -- [機能比較表](./04-feature-comparison.md) diff --git a/issues/PLAN15.md b/issues/PLAN15.md deleted file mode 100644 index d62865e2..00000000 --- a/issues/PLAN15.md +++ /dev/null @@ -1,153 +0,0 @@ -# PLAN15: playwright-scenario-test v0.3.0 — OSS リリース品質化 - -## 関連リンク - -- 親 PR: [#55 feat(ndf): playwright-scenario-test ... v4.1.0](https://github.com/takemi-ohama/ai-plugins/pull/55) -- 親 PR の自己レビュー: [comment #3142670254](https://github.com/takemi-ohama/ai-plugins/pull/55#issuecomment-3142670254) - -## 概要 - -PR #55 で残った以下を 1 PR で全対応し、playwright-scenario-test を **OSS リリース品質** まで引き上げる。 - -| 項目 | 由来 | -|------|------| -| Maj-7: `playwright_executor.py` 責務分離 | 自己レビュー Major | -| Min-2: `_slugify` 衝突 | 自己レビュー Minor | -| Min-4: HAR upload 用スクリプト不在 | 自己レビュー Minor | -| pytest-playwright + locator-first 移行 | PR #55 description (v0.3.0) | -| web-first assertion (`expect`) 統一 | PR #55 description (v0.3.0) | -| docs の "v0.3.0 以降" 記述解消 | PR #55 description | -| 録画→YAML 自動変換 | PR #55 description (v0.4.0 → 前倒し) | -| a11y / CWV を runner に組込 | PR #55 description (v0.4.0 → 前倒し) | - -**後方互換は不要** (誰も使っていない開発中段階)。古い実装は躊躇なく削除し、最終形のみを残す。 - -## 設計方針 (no back-compat) - -1. **testcase YAML スキーマを最終形へ刷新**: 旧 `path` ベース step を削除し、`goto` / `click` / `fill` / `expect` の **明示的 step kind** に統一 -2. **runner は pytest-playwright ベース**: `scenario-test` CLI は pytest を呼ぶ薄いラッパに縮退 -3. **assertion は `expect()` のみ**: 文字列 match / `body_check` の正規表現は `expect(locator).not_to_contain_text(...)` などへ移行 -4. **evidence (trace / HAR / video) 収集は単一モジュール**: `evidence.py` で集中管理、scripts は `upload_evidence.py` に統合 -5. **deprecated/dead code は削除**: `trace_link.py` shim は残さず削除、過去の互換層も持たない -6. **a11y / CWV 自動付加**: page_role に応じて axe-core / Core Web Vitals を runner が自動実行し report に含める - -## 修正対象 (主要ファイル) - -### 削除 - -- `scripts/trace_link.py` (`upload_evidence.py` に吸収) -- `scenario_test/nav_helpers.py` の旧 `path` ベース helper (`navigate_post`, `find_click_target`, `detect_body_errors`, `slug_for`) — locator + expect で置換 -- `scenario_test/curl_executor.py` の `_curl()` で使う path-only step (curl タイプは残すが step 表現を新スキーマに合わせる) - -### 新規 - -- `scenario_test/evidence.py` — `EvidenceCollectors` dataclass + listener / tracing / HAR 集中管理 -- `scenario_test/locator_steps.py` — YAML step kind → Playwright Locator 操作の dispatcher -- `scenario_test/a11y.py` — axe-core 実行 + 結果集計 (page_role 自動判定) -- `scenario_test/cwv.py` — Core Web Vitals 計測ラッパ (LCP/CLS/TTFB/INP-proxy) -- `scripts/upload_evidence.py` — trace/HAR/video 共通アップロード -- `scripts/record_to_yaml.py` — Playwright codegen 出力を YAML testcase へ変換 -- `tests/test_evidence.py` -- `tests/test_locator_steps.py` -- `tests/test_a11y.py` -- `tests/test_cwv.py` -- `tests/test_upload_evidence.py` -- `tests/test_record_to_yaml.py` -- `tests/test_default_test_id.py` - -### 大幅改訂 - -- `scenario_test/playwright_executor.py` (678 → 約 350 行目標。pytest-playwright 連携 + locator dispatcher 委譲) -- `scenario_test/testcase.py` (新 step kind スキーマ + バリデーション) -- `scripts/generate_test_plan.py` (`_default_test_id` で URL path 全体 + sha1[:6] 衝突回避、`_yaml_dump` 撤去して `pyyaml` の `safe_dump` を直接利用) -- `templates/testcase-*.yaml.template` (全 6 ファイル新スキーマで書き直し) -- `templates/config.example.yaml` (a11y/CWV セクション追加) -- `SKILL.md` (新ランナー / 新 step kind / 新 scripts へ全面刷新) -- `docs/01-methodology.md` 〜 `05-bug-report.md` (旧 helper 言及を locator-first へ更新) -- `docs/04-playwright-mapping.md` (`expect_aria_snapshot` を実装済みとして書き直し) -- `pyproject.toml` (version 0.2.0 → 0.3.0、`pytest-playwright` を dev に追加) -- `plugins/ndf/.claude-plugin/plugin.json` (4.1.0 → 4.2.0) -- `plugins/ndf/CLAUDE.md` (v4.2.0 開発履歴追記) - -## タスク分解 - -### Task 1: 新スキーマ確立 (testcase.py + locator_steps.py) - -- `TestCase.steps` を `list[Step]` (union of `GotoStep / ClickStep / FillStep / ExpectStep / ExtractStep`) に変更 -- `locator_steps.py` で各 step kind を Locator 操作に dispatch (例: `ClickStep(role="button", name="保存")` → `page.get_by_role("button", name="保存").click()`) -- 旧 `NavStep` (`path` only) は削除。step 不正時は ValueError でエラー -- `KNOWN_PAGE_ROLES` 検証は維持 -- `tests/test_locator_steps.py` で各 step → Locator 構築を smoke (Playwright 不要なテスト含む) - -### Task 2: evidence.py へ集中管理 - -- `EvidenceCollectors` dataclass: `trace_path`, `har_path`, `video_path`, `console_errors`, `page_errors`, `axe_violations`, `cwv_metrics` -- `EvidenceCollectors.attach(context, page, config, tc, log_lines)` で listener / tracing / HAR を一括 setup -- `EvidenceCollectors.finalize()` で trace.stop / a11y / CWV 実行 -- `playwright_executor` から evidence 関連コードを除去 (約 200 行削減) - -### Task 3: a11y.py / cwv.py 実装 - -- `a11y.py`: `axe-playwright-python` を呼び出し WCAG 2.0/2.1/2.2 違反を集計 - - page_role が `lp / list / form / dashboard / cart / checkout / settings` のとき自動実行 - - violations を `EvidenceCollectors.axe_violations` に格納し、report に表示 -- `cwv.py`: `check_cwv.py` (既存) のロジックを module 化し runner から呼び出せるように - - LCP / CLS / TTFB / longest_task を計測 - - page_role が `lp / list / dashboard` のとき自動実行 -- どちらも threshold を `config.yaml` で上書き可能 - -### Task 4: pytest-playwright ベース runner - -- `playwright_executor.py` を pytest-playwright fixture (`page`, `browser_context_args`) に再構築 -- `scenario-test` CLI は `pytest` を `subprocess.run` で呼ぶ薄いラッパ -- 並列は `pytest-xdist` (`-n {workers}`) で実装 -- 録画 / trace は `browser_context_args` で設定 -- `expect()` のみを assertion に使用、自前 `body_check` は `expect_no_text` step kind で代替 - -### Task 5: scripts 整理 - -- `upload_evidence.py` (新規): `--kind {trace,har,video,any}` を受ける統合 uploader -- `trace_link.py` 削除 -- `record_to_yaml.py` (新規): Playwright codegen の Python 出力を読み、新 step kind YAML へ変換 -- `record_scenario.py` は `record_to_yaml.py` 呼び出しのみに簡略化 - -### Task 6: テンプレート + docs 全面更新 - -- `templates/testcase-*.yaml.template` を 6 ファイル全部新スキーマで書き直し -- `templates/config.example.yaml` に `a11y`, `cwv` セクション追加 -- `SKILL.md` を新ランナー前提でクイックスタートから書き直し -- `docs/01〜05` の旧 helper 言及を locator-first へ更新 -- `docs/04-playwright-mapping.md` の `aria_snapshot` を実装済みとして書き直し -- `docs/05-bug-report.md` の `generate_bug_report.py` を実装済みとして書き直す (Task 5 にスクリプト追加) - -### Task 7: バージョン bump + 開発履歴 - -- `pyproject.toml`: `version = "0.3.0"` + `dev` extras に `pytest-playwright>=0.5`, `pytest-xdist>=3.0` -- `plugins/ndf/.claude-plugin/plugin.json`: `4.1.0` → `4.2.0` -- `plugins/ndf/CLAUDE.md` の開発履歴に v4.2.0 セクションを追加 (本 PR の概要) -- 古い `i09.md` 等の参照ノートで古くなった部分があれば追記 - -## 影響範囲 - -- **互換性破壊**: あり (testcase YAML スキーマ変更、`trace_link.py` 削除、`scenario-test` CLI の内部実装が pytest 委譲) -- **依存追加**: `pytest-playwright>=0.5` (dev), `pytest-xdist>=3.0` (dev), `axe-playwright-python>=0.1.4` (a11y extras はすでに追加済み) -- **ユーザ影響**: 利用者ゼロ (本人検証段階) のため気にしない - -## テスト計画 - -- [ ] `uv run pytest` (新規 + 既存) **全 pass** (目標 100+ ケース) -- [ ] `uv run scenario-test --help` smoke -- [ ] 新スキーマの testcase YAML を最低 3 件 (auth / form / list role) 用意し、テスト用ローカル HTTP サーバ (Python `http.server`) に対して実行成功 -- [ ] a11y 違反を意図的に持つ HTML を fixture 化し、`a11y.py` が拾うことを確認 -- [ ] CWV しきい値を超える遅延 fixture で `cwv.py` が FAIL を返すことを確認 -- [ ] `upload_evidence.py --kind any` が拡張子から正しく分岐 -- [ ] `record_to_yaml.py` で Playwright codegen の Python 出力 → YAML 変換 round-trip -- [ ] `playwright_executor.py` 行数 678 → 約 350 行を確認 -- [ ] `grep -r "v0.3.0 以降\|v0.4.0 以降\|TODO\|FIXME" plugins/ndf/skills/playwright-scenario-test/` で 0 hit (リリース品質チェック) -- [ ] `docs/` の旧 helper 言及 (`navigate_post`, `find_click_target`, `detect_body_errors`) が 0 hit - -## 進め方 - -タスクは依存順に Task 1 → 7 で進める。Task 4 (pytest-playwright runner) は最大規模なので、Task 1〜3 完了後に着手する。 - -各タスク完了ごとに `uv run pytest` を回し、リグレッションがないことを確認する。 diff --git a/issues/PLAN17.md b/issues/PLAN17.md deleted file mode 100644 index a8a4649f..00000000 --- a/issues/PLAN17.md +++ /dev/null @@ -1,289 +0,0 @@ -# PLAN17: playwright-scenario-test v0.3.0 — pure pytest-playwright 完全移行 - -> ## 🚨 引継ぎメモ (2026-04-26 セッション切替時点) -> -> ### 現在の状態 -> -> - **PR #56 (v0.2.5 transition) はマージ済み** (mergeCommit `d288f92`、2026-04-26T04:04:26Z) -> - 削除済 feature ブランチ: `feature/scenario-test-v0.3.0-oss-quality` -> - 現在のブランチ: **`main`** (`origin/main` と同期済み) -> - 関連 PR の経緯はすべて `plugins/ndf/CLAUDE.md` の v4.1.1 セクションに記録済み -> - 本 PLAN17 は **これから実装する** (まだコード変更ゼロ) -> -> ### 未着手のタスク (本 PLAN17 の Task 1〜8) -> -> 何も着手していない。下記「タスク分解」節を上から順に実行してください。 -> -> ### 着手前にやること -> -> 1. `git -C /work/ai-plugins checkout -b feature/scenario-test-v0.3.0-pytest-native` で新ブランチ作成 -> 2. `cd /work/ai-plugins/plugins/ndf/skills/playwright-scenario-test` -> 3. `uv sync` で依存解決確認 (現状 v0.2.5 = locator-first DSL 中間版) -> 4. `uv run pytest` で **126 件 全 pass** することを確認 (出発点) -> -> ### v0.2.5 から v0.3.0 への影響範囲 (削除予定の DSL 層) -> -> 以下を削除/全面書き換えすることを忘れない: -> -> - `scenario_test/testcase.py` の `Step` / `LocatorSpec` / `KNOWN_STEP_KINDS` / `discover_testcases` / `filter_testcases` / `parse_filter` (testcase.py 自体は残しても良いが、`Step` 系は削除) -> - `scenario_test/locator_steps.py` (全削除) -> - `scenario_test/runner.py` (全削除) -> - `scenario_test/cli.py` (全削除 or `pytest` invoker 薄ラッパに縮退) -> - `scenario_test/playwright_executor.py` (login 部分のみ fixture へ移植して全廃) -> - `scenario_test/report.py` (pytest plugin の `pytest_terminal_summary` hook で再実装) -> - `scripts/record_to_yaml.py` (codegen Python をそのまま test ファイルに使うため不要) -> - `scripts/generate_test_plan.py` (pytest 雛形生成版に置換) -> - `templates/testcase-*.yaml.template` 6 ファイル (pytest テスト雛形に置換) -> - `templates/config.example.yaml` (`scenario.config.yaml` ベースに変更) -> - `tests/test_step_schema.py` / `test_locator_steps.py` / `test_record_to_yaml.py` / `test_filter_and_slug.py` / `test_templates.py` (削除して新フィクスチャ向けに書き直し) -> -> ### 残す物 (carry forward, v0.2.5 から) -> -> - `scenario_test/a11y.py` (`scan_page` / `is_available` / `should_auto_scan`) -> - `scenario_test/cwv.py` (`measure_page` / `judge` / `passed`) -> - `scenario_test/evidence.py` の listener / tolerated patterns ロジック (fixture 内に再構成) -> - `scenario_test/hud.py` (HUD overlay JS 一式) -> - `scenario_test/video.py` (webm → mp4 変換) -> - `scripts/upload_evidence.py` (Drive 連携 CLI) -> - `scripts/run_a11y_scan.py` / `check_cwv.py` / `record_scenario.py` (CLI 単発) -> - `scripts/build_gdoc_with_drive_links.py`, `gdrive_upload_dir.py`, `_drive_auth.py`, `upload_md_as_gdoc.py` -> - `docs/` 配下 (方法論ドキュメント、checklists) -> -> ### バージョン bump 予定 -> -> - `pyproject.toml`: `0.2.5` → **`0.3.0`** -> - `plugins/ndf/.claude-plugin/plugin.json`: `4.1.1` → **`4.2.0`** -> - `plugins/ndf/CLAUDE.md` に v4.2.0 セクションを追加 -> -> ### 着手順序の推奨 (本 PLAN17 の段階的実装より具体化) -> -> Phase 1 (Task 1-2): pytest plugin 骨組み + auth fixture を作って、最小 1 テスト (`def test_login(page, ndf_role_admin): page.goto("/")`) が pytest 経由で通ることを確認 -> → ここで一旦 commit (旧 DSL は残したまま新 fixture と両立) -> -> Phase 2 (Task 3-4): evidence + a11y/CWV autouse hook 追加 -> → axe-core 違反を含むダミー HTML で fixture が機能することを確認 -> -> Phase 3 (Task 5-6): HUD overlay + report.md + Drive 連携 を fixture/hook で実装 -> → ここで end-to-end のスモークが完成 -> -> Phase 4 (Task 7): templates / docs / SKILL.md / pyproject.toml / plugin.json を一気に書き直し -> -> Phase 5 (Task 8): **旧 DSL を一括削除**。最後にまとめて削除すると PR の見通しが効く -> -> ### 検証 -> -> 各 Phase 完了ごとに `uv run pytest` を実行し、リグレッションがないことを確認。Phase 5 まで完了したら最終的に `100+ 件 (smoke + unit) 全 pass` を目指す。 -> -> ### 関連リンク -> -> - 親 PR (v0.2.5 transition): https://github.com/takemi-ohama/ai-plugins/pull/56 -> - mergeCommit: `d288f92` -> -> --- - -## 関連リンク - -- 親 PR (v0.2.5 transition): [#56 feat(ndf): playwright-scenario-test ...](https://github.com/takemi-ohama/pull/56) -- 関連プラン: [issues/PLAN15.md](./PLAN15.md) (v0.2.5) -- 廃止: ~~issues/PLAN16.md~~ (Codex レビューで「自前 DSL より pytest 直接利用が OSS 品質として優れる」と判断、PLAN17 に置換) - -## 概要 - -playwright-scenario-test を **自前 YAML DSL → pure pytest-playwright** に全面移行し、OSS リリース品質に到達させる。本リポジトリで投資した locator-first DSL / runner / dispatcher は捨て、pytest エコシステムの恩恵を最大化する。 - -| 項目 | 由来 | -|------|------| -| `scenario_test/` の DSL 層 (testcase.py / locator_steps.py / runner.py / cli.py) を全廃 | Codex 第二意見レビュー (PR #56) | -| pytest-playwright fixture 上で利用者が直接 `def test_xxx(page): ...` を書く形に移行 | OSS quality + IDE 統合 + ecosystem | -| HUD 字幕 / 動画 / Drive / report.md / a11y / CWV / 認証 ヘルパは pytest plugin + fixture として再実装 | 既存資産の再利用 | - -## 採用判断の根拠 - -Codex レビュー (PR #56) で指摘された **Major 7 + Minor 4** のうち、**6 件は pytest-native への移行で自動解決** する: - -| Codex 指摘 | 自前 DSL | pure pytest | -|---|---|---| -| Major-3 step failure 後の続行 | `continue_on_failure` schema 拡張 | **pytest 標準: assertion で test 関数即終了** | -| Major-5 CWV silent PASS | SKIP/UNKNOWN 状態を自前で設計 | **`pytest.skip()` / `pytest.xfail()`** | -| Major-6 trace_relpath が結果モデルに無い | dataclass 拡張 + report.py 修正 | **pytest-playwright 標準 artifact** | -| Major-7 lifecycle 抱え込み | executor を pure 化する大改修 | **fixture として最初から分離** | -| Major-1 record_to_yaml 順序非保証 | `ast.NodeVisitor` で書き直し | **不要: codegen の Python そのまま使う** | -| Major-2 record_to_yaml chain 欠落 | locator chain 表現を schema 拡張 | **不要: codegen 出力をそのまま利用** | - -加えて IDE 統合 (VS Code Test Explorer / JetBrains)、`pytest-html` / `allure-pytest`、`pytest-xdist`、`to_have_screenshot()` (visual regression) などのエコシステムが直接使える。 - -## 設計方針 - -### 利用者は通常の pytest テストを書く - -```python -# tests/test_admin_dashboard.py -import pytest -from playwright.sync_api import Page, expect - -@pytest.mark.page_role("dashboard") -@pytest.mark.role("admin") -def test_admin_kpi_view(page: Page, ndf_role_admin): - page.goto("/admin/dashboard") - expect(page.get_by_role("heading", name="売上サマリ")).to_be_visible() - page.get_by_role("link", name="ユーザ管理").click() - expect(page).to_have_url(lambda u: "/admin/users" in u) -``` - -NDF 提供物は (1) **fixture 群**, (2) **pytest plugin**, (3) **テンプレート**, (4) **CLI script (Drive 連携 / a11y 単発)** に縮退。 - -### 提供物の責務分離 - -| 提供物 | 役割 | -|---|---| -| `scenario_test/pytest_plugin.py` | pytest entry point (fixture / hook / report.md / Drive 連携 / a11y/CWV autouse / HUD overlay) | -| `scenario_test/fixtures/auth.py` | `ndf_config` / `ndf_role_` (login 済み page を返す) | -| `scenario_test/fixtures/evidence.py` | `ndf_evidence` (HAR / trace artifact 統合) | -| `scenario_test/fixtures/a11y.py` | `ndf_a11y_scan` (axe-core, autouse condition: page_role marker) | -| `scenario_test/fixtures/cwv.py` | `ndf_cwv_measure` (Core Web Vitals, autouse condition: page_role marker) | -| `scenario_test/hud.py` | 既存維持 (HUD overlay JS) | -| `scripts/upload_evidence.py` | 既存維持 (CLI: trace/HAR/video Drive アップ) | -| `scripts/run_a11y_scan.py` | 既存維持 (CLI: 単発スキャン) | -| `scripts/check_cwv.py` | 既存維持 (CLI: 単発計測) | -| `templates/conftest.py.template` | 利用者の `tests/conftest.py` 雛形 | -| `templates/test_*.py.template` | 役割別 (auth / list / form / edit) のテスト雛形 | - -## 削除する物 (v0.2.5 で投資した DSL 層) - -- `scenario_test/testcase.py` の `Step` / `LocatorSpec` / `KNOWN_STEP_KINDS` / `discover_testcases` / `filter_testcases` / `parse_filter` -- `scenario_test/locator_steps.py` 全体 -- `scenario_test/runner.py` 全体 -- `scenario_test/cli.py` 全体 (またはごく薄い `pytest` invoker に縮退) -- `scenario_test/playwright_executor.py` 全体 (login 部分のみ fixture へ移植) -- `scenario_test/report.py` 全体 (pytest plugin の terminal_summary hook + 独自 writer に再実装) -- `scripts/record_to_yaml.py` 全体 (codegen Python をそのまま `tests/test_*.py` として保存する) -- `scripts/generate_test_plan.py` 全体 (pytest 雛形生成スクリプトに置換) -- `templates/testcase-*.yaml.template` 6 ファイル -- `templates/config.example.yaml` - -## 残す物 (v0.2.5 から carry forward) - -- `scenario_test/a11y.py` (`scan_page` / `is_available` / `should_auto_scan`) -- `scenario_test/cwv.py` (`measure_page` / `judge` / `passed`) -- `scenario_test/evidence.py` (listener / tolerated patterns ロジックを fixture 内に再構成) -- `scenario_test/hud.py` (HUD overlay JS 一式) -- `scenario_test/video.py` (webm → mp4 変換) -- `scripts/upload_evidence.py` (Drive 連携) -- `scripts/run_a11y_scan.py` (CLI 単発) -- `scripts/check_cwv.py` (CLI 単発) -- `scripts/record_scenario.py` (Playwright codegen 起動) -- `scripts/build_gdoc_with_drive_links.py`, `gdrive_upload_dir.py` (Drive 連携) -- `docs/` 配下 (方法論ドキュメント、checklists) - -## 利用者プロジェクトの構成 - -``` -my-e2e/ -├── pyproject.toml # [tool.pytest.ini_options] markers + ndf-config 設定 -├── conftest.py # NDF plugin の自動 discover (`pytest -p ndf_plugin`) -├── scenario.config.yaml # base_url / roles / a11y/CWV 設定 -└── tests/ - ├── test_admin_dashboard.py - ├── test_user_form.py - └── ... -``` - -利用者が書く Python は通常の pytest テスト。NDF が提供する markers / fixtures を使って role / page_role / a11y を表現する。 - -## タスク分解 - -### Task 1: pytest plugin 骨組み - -- **対象**: `scenario_test/pytest_plugin.py` (新規), `pyproject.toml` (`[project.entry-points."pytest11"]`) -- **変更内容**: - - `pytest_addoption(parser)`: `--ndf-config` / `--ndf-out-dir` / `--ndf-no-evidence` 等 - - `pytest_configure(config)`: `ndf_config` を読み込み Session に保存 - - markers の登録: `page_role(*roles)` / `role(role_id)` / `phase(num)` / `priority(level)` - - `pytest_runtest_setup(item)` で marker 検査 - -### Task 2: 認証 fixture (`fixtures/auth.py`) - -- **対象**: `scenario_test/fixtures/auth.py` (新規), `scenario_test/pytest_plugin.py` -- **変更内容**: - - `ndf_config` fixture: `Config.load(...)` を session scope で - - 各 role に対し `ndf_role_` fixture を動的生成 (login 済み storage_state を function scope で渡す) - - storage_state の caching (1 session 内で同じ role はログインを 1 回に減らす) - -### Task 3: evidence fixture + autouse hook - -- **対象**: `scenario_test/fixtures/evidence.py` (新規), `scenario_test/pytest_plugin.py` -- **変更内容**: - - `ndf_evidence` fixture: HAR / trace 設定を `browser_context_args` に inject - - `pytest_runtest_makereport(item, call)` で FAIL 時に trace 保存パスを confirm - - tolerated_console_errors / tolerated_page_errors を listener として attach (現 `evidence.py` ロジック流用) - -### Task 4: a11y / CWV を marker autouse 化 - -- **対象**: `scenario_test/fixtures/a11y.py` (新規), `scenario_test/fixtures/cwv.py` (新規) -- **変更内容**: - - `@pytest.mark.page_role("form")` が付与された test の終了直前に axe-core を自動実行 - - 同様に CWV を計測 - - 違反は `pytest.fail()` (default) または `pytest.skip()` で SKIP 扱い (config 切替) - -### Task 5: HUD overlay を `browser_context_args` で注入 - -- **対象**: `scenario_test/pytest_plugin.py` -- **変更内容**: - - `browser_context_args` fixture を override し、`hud.HUD_INIT_SCRIPT` を `add_init_script` で全 page に inject - - 字幕の更新 API (`set_caption`) を fixture 経由で公開 → 利用者がオプションで叩ける - - default は HUD なしで OK (動画必要なときだけ `--ndf-hud` で有効化) - -### Task 6: report.md 生成 + Drive 連携 - -- **対象**: `scenario_test/pytest_plugin.py`, `scenario_test/report.py` (再実装、薄く) -- **変更内容**: - - `pytest_terminal_summary(terminalreporter, exitstatus, config)` で全 test の result を収集 - - 既存 report.md と同等のフォーマットで `reports//report.md` を生成 - - `--ndf-drive-folder=` 指定時は `pytest_sessionfinish` で `upload_evidence.py` の関数を直接呼び、Drive アップロード + リンク差し込み - -### Task 7: テンプレート / docs / scripts 整理 - -- **対象**: `templates/conftest.py.template`, `templates/test_*.py.template` 4-5 ファイル, `templates/scenario.config.yaml`, `scripts/generate_test_plan.py` (pytest 雛形生成版に置換), `SKILL.md` 全面書き直し, `docs/04-playwright-mapping.md` 更新, `docs/05-bug-report.md` 更新, `pyproject.toml` (version 0.2.5 → 0.3.0), `plugins/ndf/.claude-plugin/plugin.json` (4.1.1 → 4.2.0), `plugins/ndf/CLAUDE.md` v4.2.0 セクション -- **変更内容**: - - 利用者向け: pytest 直書き例 / `pytest -m "page_role:form"` / `pytest -n 4` / `pytest --html=` 等の標準パイプライン - - SKILL.md は「pytest 採用 + NDF が提供する fixture/marker」を中心に書き直す - - docs は locator-first 表現を pytest コードでそのまま例示 (DSL 言及を全削除) - -### Task 8: 旧 DSL 削除 + テスト全置換 - -- **対象**: 上記「削除する物」リストを実行、`tests/` も新フィクスチャ向けに書き直し -- **変更内容**: - - 単体テストは `pure 関数` (a11y.judge / cwv.judge / detect_kind / detect_mime / hud constants 等) のみ残す - - 統合テストとして tmp http server + pytest-playwright で `tests/integration/test_smoke.py` を 1 件追加 (本来 OSS だと CI を望むため) - - 削除対象テスト: `test_step_schema.py` / `test_locator_steps.py` / `test_record_to_yaml.py` / `test_filter_and_slug.py` (parse_filter / slugify 部分は廃止) / `test_templates.py` (templates 自体が変わるため作り直し) - -## 影響範囲 - -- **互換性**: v0.2.5 → v0.3.0 で完全な breaking change。利用者は YAML を書き直す必要あり (誰も使っていない前提なので問題なし) -- **依存追加 (main)**: `pytest>=8.0`, `pytest-playwright>=0.5`, `pytest-xdist>=3.0` -- **依存削除**: なし (既存依存はすべて流用) -- **CI**: pytest 標準なので GitHub Actions で簡単に回せる (`uv run pytest -n auto`) - -## テスト計画 - -- [ ] `uv run pytest tests/unit/` で pure 関数テスト (a11y.judge / cwv.judge / detect_mime / hud / video) が **全 pass** -- [ ] `uv run pytest tests/integration/test_smoke.py` で local http server (`http.server` で 1 ページ起動) に対する end-to-end (login → click → expect) が pass -- [ ] `pytest -p ndf.pytest_plugin -n 4 tests/` で並列 4 worker で smoke tests が pass -- [ ] `pytest --ndf-drive-folder=` でテスト後に Drive 連携が動作 (手動確認) -- [ ] `pytest -m "page_role(form)"` で form テストのみ実行 -- [ ] FAIL ケースで axe-core 違反が `pytest --html` レポートにも出る -- [ ] `playwright codegen → tests/test_.py` への手順が SKILL.md に明記、実例で動作確認 - -## 段階的実装 - -1. **Phase 1**: Task 1 + 2 (plugin 骨組み + auth fixture) — 単一 test がログイン + assertion で動くこと -2. **Phase 2**: Task 3 + 4 (evidence + a11y/CWV autouse) — failed test で trace/axe が自動保存されること -3. **Phase 3**: Task 5 (HUD) + Task 6 (report.md + Drive) — エンドツーエンドで本物のレポート生成 -4. **Phase 4**: Task 7 (templates + docs + version) — リリース直前 -5. **Phase 5**: Task 8 (旧 DSL 削除) — 最後にまとめて削除し、PR を分かりやすく - -## v0.4.0 以降 (本 PR 範囲外) - -- pytest-html / allure-pytest 連携 (PR option として) -- Visual regression (`expect(page).to_have_screenshot()`) サポート -- bug report 自動生成 (Codex 指摘の旧 PLAN16 Task 4) — pytest hook で容易に追加可能 diff --git a/issues/i12.md b/issues/i12.md deleted file mode 100644 index 121a37d3..00000000 --- a/issues/i12.md +++ /dev/null @@ -1,13 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - -# 1. dbhub mcpのリポジトリをhttps://github.com/takemi-ohama/dbhubに変更 -* 本家dbhubにないSSH keep-aliveの機能を追加したかったので、リポジトリをforkしました。 - * https://github.com/takemi-ohama/dbhub -* ndf:mcp-dbhub は当面こちらのリポジトリを利用するように変更してください。 -* 本家にmergeされたら戻します。 - diff --git a/issues/i15.md b/issues/i15.md deleted file mode 100644 index 54bf6a6a..00000000 --- a/issues/i15.md +++ /dev/null @@ -1,438 +0,0 @@ -# PR #57 Codex 指摘 8 件 修正計画 - -## ステータス -- 作成日: 2026-04-26 -- 最終更新: 2026-04-26 -- 現在のフェーズ: 計画策定完了 / 実装着手前 -- 進捗: 0/6 commit -- ブランチ: `feature/scenario-test-v0.3.0-pytest-native` (origin/main から 7 commits ahead) -- 対象 PR: https://github.com/takemi-ohama/pull/57 -- ベースライン pytest: **61 passed in 0.14s** (確認済) - -## 概要 - -PR #57 (`playwright-scenario-test v0.3.0 — pure pytest-playwright`) に投稿された -Codex CLI 第二意見レビューの指摘 (Major 5 / Minor 3、計 8 件) を 6 commit に分けて -修正する。pytest 全 pass を維持しつつ、最終的に PR コメント + PR description 更新で完了とする。 - -CI は無いため検証は **ローカル `uv run --extra dev pytest`** のみ。 -Major-5 で追加するテストは Playwright 実機を必要としない範囲に絞る。 - -## 作業ディレクトリ -- skill ルート: `/work/ai-plugins/plugins/ndf/skills/playwright-scenario-test/` -- pytest 実行: `cd && uv run --extra dev pytest` - -## Commit 計画 (6 件) - -### Commit 1: Minor 6+7 — config.py 軽微修正 - -**ファイル**: `scenario_test/config.py` - -#### Minor 6: `step_delay_ms` の dataclass / from_raw 不一致 (line 64 vs 89) - -- 現状: dataclass default `1800`、`PlaywrightConfig.from_raw()` の fallback `1500` -- 対応: `from_raw()` 冒頭で `base = cls()` を作り、各 `raw.get(...)` の fallback に - `base.` を使う方式に統一。1280/720 の数値も `base.viewport_width` 等で参照すると、 - この dataclass を真実の源 (single source of truth) にできる。 -- 注意: 既存テスト `test_evidence_fixture.py` は `PlaywrightConfig.defaults()` 経由で - 使われているのみで、`from_raw` の数値を直接 assert してはいないので副作用なし。 - -#### Minor 7: 空 YAML で TypeError (line 183-185) - -- 現状: `yaml.safe_load(fp)` が `None` を返すと `_from_dict()` の `raw["target"]` で - `TypeError: 'NoneType' object is not subscriptable` になる。 -- 対応: `Config.load()` 内で `safe_load` 直後に `isinstance(raw, dict)` チェック。 - 違えば `ValueError("scenario.config.yaml の中身が空または辞書ではありません: ")` - を raise。 -- テスト: `tests/test_config_basic_auth.py` に近い既存ファイルで pass しているはず。 - 追加で 1 件 (空 YAML → ValueError) を test_config_basic_auth.py に書き加える。 - -#### コミットメッセージ案 -``` -fix(ndf): playwright-scenario-test config の dataclass 既定値整合と空 YAML エラーハンドリング - -- PlaywrightConfig.from_raw() の fallback を dataclass 既定値 (cls()) に揃え、 - step_delay_ms の 1800 vs 1500 不一致を解消 (Codex Minor 6) -- Config.load() で yaml.safe_load() 結果が dict でない場合に ValueError を raise し、 - 空 YAML での TypeError を防ぐ (Codex Minor 7) -- 空 YAML テストケースを追加 (test_config_basic_auth.py) -``` - -### Commit 2: Major 4 — YAML の ${ENV_VAR} 展開 - -**ファイル**: `scenario_test/config.py` / `templates/scenario.config.yaml` / `SKILL.md` / `docs/` - -#### 仕様 -- `Config.load()` で `yaml.safe_load()` の後、再帰的に dict / list / str を walk し、 - 文字列値の中に `${VAR}` / `${VAR:-default}` パターンがあれば `os.environ` から展開。 -- 未定義かつ default も無い場合は `ValueError` (`scenario.config.yaml の ${VAR} が - 未定義 (env を設定するか default を指定してください)`)。 -- 実装は `_expand_env(value: Any) -> Any` 純関数として外出しし、ユニットテストしやすくする。 - -```python -import os, re -_ENV_RE = re.compile(r"\$\{([A-Za-z_][A-Za-z0-9_]*)(?::-([^}]*))?\}") - -def _expand_env_in_str(s: str) -> str: - def repl(m): - name, default = m.group(1), m.group(2) - val = os.environ.get(name) - if val is None: - if default is None: - raise ValueError(f"環境変数 ${{{name}}} が未定義です (default 指定または env 設定が必要)") - return default - return val - return _ENV_RE.sub(repl, s) - -def _expand_env(value): - if isinstance(value, str): return _expand_env_in_str(value) - if isinstance(value, list): return [_expand_env(v) for v in value] - if isinstance(value, dict): return {k: _expand_env(v) for k, v in value.items()} - return value -``` - -#### template 更新 - -`templates/scenario.config.yaml` の `roles.*.login.fields` のサンプルを env 参照に: -```yaml -fields: - LoginID: ${ADMIN_LOGIN_ID} - Password: ${ADMIN_PASSWORD} -``` -`target.basic_auth` も同様に `${BASIC_AUTH_USER}` 等を例として示す。 -コメントで「env を `.env` または shell で export する」運用を明記。 - -#### ドキュメント更新 -- `SKILL.md` の「制約 / 注意」節に「資格情報は YAML 直書きではなく `${ENV_VAR}` 展開を推奨」を追加。 -- `docs/06-pytest-playwright.md` または `docs/README.md` のいずれか自然な箇所に同旨を追記 - (どちらが適切かは実装時に確認)。 - -#### テスト -`tests/test_config_basic_auth.py` に `_expand_env` の純関数テストを 3〜4 件追加: -- `${VAR}` 展開 -- `${VAR:-default}` で env 無し → default -- `${UNDEFINED}` (default 無し) → ValueError -- 再帰展開 (list 内の dict 内の str) - -#### コミットメッセージ案 -``` -feat(ndf): playwright-scenario-test config に ${ENV_VAR} / ${VAR:-default} 展開を追加 - -- scenario_test/config.py に _expand_env を追加し、Config.load() で再帰展開 -- templates/scenario.config.yaml の認証情報サンプルを env 参照ベースに変更 -- SKILL.md / docs に YAML 直書き禁止の注意を追記 -- tests/test_config_basic_auth.py に env 展開の純関数テストを追加 -- リポジトリポリシー「認証情報は環境変数で管理」と整合 (Codex Major 4) -``` - -### Commit 3: Major 1+2 — HAR 設計を function-scope context に揃え、case_dir を nodeid + worker + sha1 に変更 - -**ファイル**: `scenario_test/fixtures/evidence.py` - -#### 設計選択 (function-scope vs session) - -**選択**: function-scope (1 test = 1 HAR)。理由: -- `NdfEvidence.har_path` / `confirm_har()` / `pytest_runtest_makereport` の - `rep.user_properties` 付与 / `report.md` 失敗詳細セクション / Drive upload は - すべて test ごとに HAR が独立している前提で書かれている。 -- session 1 HAR にすると「FAIL test の周辺だけ抽出」が利用者側で困難になる。 -- pytest-playwright の `browser_context_args` は dict fixture なので、 - function scope に上書き可能 (公式 docs 確認済: scope を function に変えても - fixture は問題なく動く)。 - -#### 実装変更 - -1. `browser_context_args` fixture を `scope="function"` に変更: - - `request.node` から `case_dir` を計算するため `request` を引数に取る - - `case_dir / "request.har"` を `record_har_path` に inject - - session 共通 HAR (`session.har`) は廃止 - -2. `_safe_slug` を新ロジックに置換 (Major 2): - ```python - import hashlib, os - def _safe_case_slug(node: pytest.Item | "Node") -> str: - """nodeid + xdist worker から衝突しない安全な slug を作る。""" - nodeid = getattr(node, "nodeid", getattr(node, "name", "test")) - worker = os.environ.get("PYTEST_XDIST_WORKER", "") - raw = f"{nodeid}@{worker}" if worker else nodeid - slug = _FILENAME_SAFE_RE.sub("-", raw).strip("-").lower() - digest = hashlib.sha1(raw.encode("utf-8")).hexdigest()[:6] - # 60 文字 + sha1[:6] = 67 文字程度に圧縮 - return f"{slug[:60]}-{digest}".strip("-") or "test" - ``` - 既存の `_safe_slug(name, fallback)` は後方互換のため残し、内部で - 新関数 `_safe_case_slug(node)` を呼ぶ形にしてもよい - (test_evidence_fixture.py の `test_safe_slug` を壊さないように)。 - → 実装方針: `_safe_slug` 単体は既存仕様 (str → str) のまま維持し、 - evidence fixture 内で使う slug 生成だけ新関数に切替える。 - -3. `ndf_evidence` fixture の `case_dir` 計算を新 slug 関数経由に: - ```python - case_dir = ndf_out_dir / _safe_case_slug(request.node) - ``` - -4. `confirm_har()` のロジックは現状でほぼ OK だが、HAR write は context.close() - 時に flush されるので、`stop_tracing` の後 (= context teardown と同タイミング) に - 呼ぶ必要がある。pytest-playwright の `context` fixture は yield 後にクローズするため、 - `ndf_evidence` の finally 句で `confirm_har()` を呼ぶだけでは HAR 書き込み完了前の - 可能性がある。 - - 対策: `pytest_runtest_makereport` の `teardown` phase で `ev.confirm_har()` を - 再度呼ぶ。または `ndf_evidence` の yield を context teardown 後に終わるよう、 - finalizer 順序を `request.addfinalizer` で制御する。 - - 簡易策: `confirm_har()` を makereport の `when=="teardown"` 時に追加で呼ぶ。 - ※ ただし HAR ファイルは context が close されるまで書かれないため、 - teardown の最後 (context fixture finalizer の後) に呼ぶ必要があり、 - pytest-playwright の context fixture と evidence fixture の依存順を工夫する必要がある。 - - 安全策: `ndf_evidence` の yield 後の finally では `confirm_har()` を呼ばず、 - `pytest_runtest_makereport(when="teardown")` で `ev.har_path.exists()` を再チェックして - `har_relpath` を更新する hook 側の責務に変える。 - -#### テスト追加 -`tests/test_evidence_fixture.py` に: -- `_safe_case_slug` の純関数テスト (parametrize、xdist worker env 有無) -- 同じ nodeid + 同じ worker は同じ slug (idempotent) -- 異なる nodeid は異なる slug -- xdist worker が変われば slug も変わる - -実 fixture (browser_context_args の function scope 化) は Playwright を要するため -ここでは pytester 経由で「browser_context_args fixture の scope が function」を -inspect する軽いテストに留める (Major-5 commit でカバーする)。 - -#### コミットメッセージ案 -``` -fix(ndf): playwright-scenario-test の HAR 収集を function-scope に変更し case_dir 衝突を解消 - -- browser_context_args を session → function scope に変更し、test ごとに - record_har_path = case_dir/request.har を inject (Codex Major 1) -- session.har 共有を廃止。NdfEvidence.confirm_har() がほぼ常に None を返す不整合を解消 -- _safe_case_slug() を新設し、nodeid + PYTEST_XDIST_WORKER + sha1[:6] suffix で - slug を生成。parametrize / 同名関数 / xdist 並列での trace.zip / request.har 上書きを - 防止 (Codex Major 2) -- pytest_runtest_makereport の teardown phase で confirm_har() を再評価し、 - context teardown 後に書き込まれる HAR を取りこぼさない -- _safe_case_slug の純関数テストを追加 (test_evidence_fixture.py) - -設計選択 (function-scope vs session): NdfEvidence / report.md / Drive upload が -test ごとの独立 HAR を前提に書かれているため、function-scope を採用。 -session 1 HAR は FAIL 周辺だけの抽出が困難なため不採用。 -``` - -### Commit 4: Major 3 — xfailed/xpassed の集約 - -**ファイル**: `scenario_test/pytest_plugin.py` / `scenario_test/pytest_report.py` - -#### 変更点 -1. `_collect_entries(terminalreporter)` の outcome ループに `"xfailed"` / `"xpassed"` を追加。 -2. `terminalreporter.stats` の rep の `wasxfail` / outcome の扱いを確認: - - pytest 内部では `xfailed` の rep は `outcome == "skipped"` + `wasxfail` 属性が付く形式 - (バージョン依存)、または `stats["xfailed"]` に直接入る。 - - `terminalreporter.stats.get("xfailed", [])` / `get("xpassed", [])` を直接見るのが確実。 -3. `pytest_report.NdfTestEntry.outcome` の値として `"xfailed"` / `"xpassed"` を受け入れる - ことは既に `status_label` で実装済 (line 43-50)。 -4. `render_markdown` のヘッダ集計に `xfailed` / `xpassed` を追加し、 - `XFAIL N / XPASS M` を表示する。 -5. `all_pass` の判定を `passed + xfailed == total` に変更 - (xfailed は期待通りの fail なので OK 扱いにする — `NdfTestEntry.ok` は既に - `outcome in ("passed", "xfailed")` を返すのでそれに揃える)。 - -#### テスト追加 -`tests/test_pytest_report.py` に: -- xfailed / xpassed entry を含む render_markdown の集計テスト -- ヘッダに `XFAIL`/`XPASS` カウントが出ること -- xfailed のみのテストで `全PASS` 判定にならないこと - (xpassed は意図せず pass したので注意喚起、xfailed は期待通り fail なので OK 扱い、 - とする方針を docstring に明記) - -#### コミットメッセージ案 -``` -fix(ndf): playwright-scenario-test report に xfailed / xpassed を集約 - -- _collect_entries() で terminalreporter.stats の "xfailed" / "xpassed" も走査 - (Codex Major 3) -- render_markdown のヘッダ集計に XFAIL / XPASS を追加 -- ok 判定 (NdfTestEntry.ok) の挙動に合わせて all_pass を passed + xfailed で判定 -- xfailed/xpassed を含む render テストを test_pytest_report.py に追加 -``` - -### Commit 5: Major 5 — pytester ベースの統合テスト 3 件 - -**ファイル**: `tests/` (新規 or 既存に追記) - -Playwright 実機を起動しない範囲で、以下 3 件を pytester で追加: - -#### Test (a): role fixture の初回ログイン + 2 回目 cache hit -**新規**: `tests/test_auth_cache.py` - -`_login_and_get_storage_state` を `monkeypatch` で fake (例: `lambda **kwargs: {"cookies": [...], "origins": []}`) に差し替え、`_StorageStateCache` が: -- 1 個目の test では `_login_and_get_storage_state` を 1 回呼ぶ -- 2 個目の test では呼ばない (cache hit) - -を確認する。pytester 内でカウンタ用 module attribute を使い、callcount を assert。 - -実装ヒント: `pytester.makepyfile` で内部 conftest.py + 2 つの test 関数を作り、 -`monkeypatch.setattr("scenario_test.fixtures.auth._login_and_get_storage_state", fake)` を -`pytester.runpytest_subprocess` の前に setattr すると subprocess には伝わらないので、 -代わりに pytester で書く conftest.py の中で `monkeypatch` するか、 -`scenario_test/fixtures/auth.py` の `_login_and_get_storage_state` を fake に差し替えた -fixture override を pytester 内 conftest.py に書く方が確実。 - -#### Test (b): makereport が ndf_har / ndf_trace を user_properties に乗せる -**新規 or 既存追記**: `tests/test_pytest_plugin_bootstrap.py` に追記、 -または `tests/test_makereport_user_properties.py` を新設。 - -pytester で: -1. fake conftest.py を書き、`ndf_evidence` fixture override で - `NdfEvidence` インスタンスを返し、`har_relpath="request.har"`、`trace_relpath="trace.zip"` - を直接セットしておく -2. 1 件 dummy test 関数を実行 (`page` fixture を要求しないテスト関数で、 - evidence を `request.node._ndf_evidence` に setattr する) -3. `terminalreporter` を解析して、最終的に書き出された report.md (out_dir - `--ndf-out-dir=...`) に `request.har` / `trace.zip` が出るかを assert - -または、より軽く: -- `pytest_runtest_makereport` を直接呼び出して rep.user_properties を確認する - 単体テスト (Playwright 不要、`item._ndf_evidence` を SimpleNamespace で渡す)。 - → こちらを採用 (より単純で安定)。 - -#### Test (c): terminal_summary が成果物パスを report.md に埋め込む -**新規 or 既存追記**: `tests/test_pytest_terminal_summary.py` を新設、 -または `test_pytest_plugin_bootstrap.py` に追記。 - -pytester で: -1. tmp の `--ndf-out-dir=` を指定 -2. dummy test を 1 件実行 (assertion error にする → failed 1 件) -3. fake `_ndf_evidence` を `request.node` に attach する fixture を提供 - (har/trace path をテンポラリファイルとして用意し touch しておく) -4. session 終了後 `/report.md` が生成され、failure section に - `request.har` / `trace.zip` のパスが埋め込まれていることを assert - -simpler 方針: `pytest_terminal_summary` を直接呼び出すユニットテスト -(`terminalreporter` を mock し `stats` を組み立て) でカバーする。 - -#### コミットメッセージ案 -``` -test(ndf): playwright-scenario-test に hook と auth キャッシュの統合テストを追加 - -- test_auth_cache.py: _login_and_get_storage_state の cache hit/miss を - monkeypatch で検証 (1 回目で 1 回呼ばれ、2 回目は呼ばれない) -- test_makereport_user_properties.py: pytest_runtest_makereport が - ndf_har / ndf_trace / ndf_console_errors / ndf_page_errors を rep.user_properties に - 乗せることを単体テスト -- test_pytest_terminal_summary.py: terminalreporter mock で report.md に - HAR / trace パスが埋め込まれることを検証 -- いずれも Playwright 実機を起動しない範囲で実装 (CI 不在のため軽量化) (Codex Major 5) -``` - -### Commit 6: Minor 8 — Drive upload の機微情報注意喚起 - -**ファイル**: `scenario_test/pytest_plugin.py` / `SKILL.md` - -#### 変更点 -1. `pytest_addoption` の `--ndf-drive-folder` の help を: - ``` - "Drive アップロード先フォルダ ID (terminal_summary 後に upload 実行)。" - "trace.zip / *.har / 動画には機微情報 (URL / Cookie / localStorage / 操作履歴) " - "が含まれる可能性があります。private folder + 信頼できる共有相手のみに限定してください。" - ``` -2. `SKILL.md` の「制約 / 注意」節を: - ``` - - **トレース / HAR / 動画は機微情報を含む**: - - HAR には URL のクエリ文字列・Cookie・Authorization ヘッダ等が記録されます - - trace.zip には localStorage / 操作履歴 / DOM スナップショットが含まれます - - `--ndf-drive-folder=` は **private folder** を指定し、共有相手を限定してください - - allowlist 機能 (`--ndf-upload-types`) は v0.4.0 以降で検討 - ``` -3. PR description の `## やらないこと (本 PR 範囲外)` に - `allowlist 機能 (--ndf-upload-types)` を v0.4.0 として記載 (commit ではなく - `gh pr edit` で行う)。 - -#### コミットメッセージ案 -``` -docs(ndf): playwright-scenario-test の Drive upload 機微情報リスクを help と SKILL.md に明記 - -- pytest_addoption の --ndf-drive-folder help に「trace/HAR は機微情報を含む可能性。 - private folder 推奨」警告を追加 -- SKILL.md 制約節に HAR / trace / 動画の含有情報と private folder 推奨を明記 -- allowlist 機能 (--ndf-upload-types) を v0.4.0 への TODO として PR description に記載予定 - (Codex Minor 8) -``` - -## 各コミット後の検証 - -```bash -cd /work/ai-plugins/plugins/ndf/skills/playwright-scenario-test -uv run --extra dev pytest -q -``` - -期待値: ベースライン 61 pass + 各コミットでの追加テスト分 -- Commit 1: +1 (空 YAML) = **62** -- Commit 2: +4 (env 展開) = **66** -- Commit 3: +3〜4 (slug 衝突) = **69〜70** -- Commit 4: +3 (xfail/xpass render) = **72〜73** -- Commit 5: +3 (統合テスト) = **75〜76** -- Commit 6: テスト追加なし = **75〜76** (現状仕様の 64+ という条件は満たす) - -最終目標: **75 件以上の pass、failures 0**。 -ミッション要件 "現状 61 pass + 新規 3 件で **64+ pass**" を上回って完了する。 - -## PR 完了処理 (実装完了後) - -### Push -全コミット完了後 `git push origin feature/scenario-test-v0.3.0-pytest-native`。 - -### PR コメント投稿 (`gh pr comment 57 --body-file `) - -テンプレート: -```markdown -## Codex 指摘 8 件 修正完了 - -レビュー (review id `PRR_kwDOREg9uc748eqJ`) の指摘 8 件 (Major 5 + Minor 3) に対応しました。 - -### 対応サマリ - -| # | 重要度 | 指摘 | 対応 commit | 主な変更ファイル | -|---|---|---|---|---| -| 1 | Major | HAR 収集の実装とレポート前提が食い違い、har_relpath が常に None | `` | scenario_test/fixtures/evidence.py | -| 2 | Major | case_dir の slug 衝突 (parametrize / 同名関数 / xdist) | `` | scenario_test/fixtures/evidence.py | -| 3 | Major | xfail / xpass を集約していない | `` | scenario_test/pytest_plugin.py / pytest_report.py | -| 4 | Major | 認証情報を YAML に平文で持つ前提 | `` | scenario_test/config.py / templates/scenario.config.yaml / SKILL.md | -| 5 | Major | hook と auth キャッシュの統合テストが不足 | `` | tests/test_auth_cache.py / test_makereport_user_properties.py / test_pytest_terminal_summary.py | -| 6 | Minor | step_delay_ms の dataclass / from_raw 不一致 | `` | scenario_test/config.py | -| 7 | Minor | 空 YAML で TypeError | `` | scenario_test/config.py | -| 8 | Minor | Drive upload の機微情報注意喚起が弱い | `` | scenario_test/pytest_plugin.py / SKILL.md | - -### pytest 結果 -``` -<実行ログ末尾> -``` - -### 残課題 / 任意検証 -- (あれば追記) - -@takemi-ohama 再レビューをお願いします。 -※ 自 PR のため Resolve Conversation は対象 review が **comment** 形式であり不要です。 -``` - -### PR description 更新 (`gh pr edit 57 --body-file `) - -既存 description の commit 表に新規 6 commit を追記。 -`## やらないこと` に `--ndf-upload-types` allowlist を v0.4.0 TODO として明記。 - -## 復帰情報 - -途中停止からの復帰手順: -1. `cd /work/ai-plugins && git status` で現在の差分を確認 -2. `git log --oneline origin/feature/scenario-test-v0.3.0-pytest-native..HEAD` で - 未 push のローカルコミット数を確認 -3. このファイル (`issues/i15.md`) の Commit 計画と照合し、未着手の commit から再開 -4. 各 commit 完了後に必ず pytest を回し、本ファイルの「進捗」を更新 - -## 注意事項 - -- main への直接 commit / push は厳禁 (現在 `feature/scenario-test-v0.3.0-pytest-native` 上) -- ユーザー確認なしで PR Approve / Merge は行わない -- 各 commit メッセージ末尾に `Co-Authored-By: Claude Opus 4.7 (1M context) ` -- Major 1 の HAR 設計選択 (function-scope) の根拠を commit メッセージに含める (上記テンプレ済) -- Major 5 の統合テストは Playwright 実機なしで動かせる範囲に限定 -- 既存 `_safe_slug(name, fallback)` 単体仕様は変えず、`_safe_case_slug(node)` を新設して - evidence fixture 内のみ切替える (既存テスト `test_safe_slug` を壊さない) diff --git a/issues/ndf-presentation.md b/issues/ndf-presentation.md deleted file mode 100644 index 3d137e11..00000000 --- a/issues/ndf-presentation.md +++ /dev/null @@ -1,247 +0,0 @@ -# NDF Plugin 紹介プレゼンテーション - -> Claude Code 向け統合プラグイン `ndf` の紹介資料。NotebookLM での読み込みを想定し、1スライド=1セクションで構成する。 - ---- - -## スライド 1: タイトル / 何のプラグインか - -**NDF Plugin — Claude Code 開発環境を統合する Skill / Agent / Hook パッケージ** - -- リポジトリ: -- バージョン: v4.3.1 -- 提供物 - - **Skill 38個**（PR/レビューワークフロー、原則ガイドライン、外部AI連携、Playwright E2E など） - - **Sub Agent 8個**（director / corder / data-analyst / researcher / qa / debugger / devops-engineer / code-reviewer） - - **自動 Hook**（SessionStart で transcript 保持期間管理 / Stop で AI 要約 → Slack 通知） -- ライセンス: MIT -- 動作環境: Claude Code（CLI / IDE / Web 共通） - ---- - -## スライド 2: Claude Code における Skill 配布の3方式 - -Claude Code が Skill / Agent / Slash Command を取り込む経路は3つある。 - -| 方式 | 配置場所 | スコープ | 配布 | -|---|---|---|---| -| **user** | `~/.claude/skills/`, `~/.claude/agents/` | 自分の全プロジェクト共通 | 手動コピー | -| **project** | `/.claude/skills/` | 1リポジトリ内のみ | git で共有 | -| **plugin** | `~/.claude/plugins//` | インストールした全プロジェクト | marketplace 経由 | - -```mermaid -flowchart LR - A[Claude Code 起動] --> B{Skill 解決順} - B --> C[user: 自分専用] - B --> D[project: チーム共有] - B --> E[plugin: 公開配布] -``` - ---- - -## スライド 3: なぜ plugin 方式か - -事実ベースの利点を列挙する。 - -- **インストール / 更新が1コマンド** - - `/plugin marketplace add` → `/plugin install` でセットアップ完了 - - バージョン管理は `plugin.json` の semver で plugin 側に集約 -- **複数の構成要素を一括提供** - - 1 plugin に Skill / Sub Agent / Hook / MCP 定義を同梱できる（user / project 方式では個別管理） -- **チームを跨いだ再利用** - - リポジトリ単位（project）ではなく、Marketplace 単位で広く共有できる -- **副作用の局所化** - - `/plugin disable` で全機能をまとめて無効化可能。user / project は手動削除が必要 - ---- - -## スライド 4: ndf が目指すこと — 開発体験の共有 - -`ndf` の主目的は「個人の開発ワークフローを再現可能な形でチームに配布する」こと。 - -- 個人で蓄積したノウハウは通常、ローカル設定や暗黙知に閉じ込められる -- Claude Code は Skill / Agent でこれを **テキスト化** できる -- plugin として配布すれば、**同じ手順を別マシン・別人で実行可能** になる -- ndf はこの考えに基づき、PR 運用 / レビュー / デバッグ / Web テスト など普段使いの手順をひと通り収録している - -スコープ: - -- 「便利機能を全部入れる」ではなく「**一連のフローを完結させる**」ことを優先 -- 例: 「PR を出す」一連の流れは `/ndf:pr` → `/ndf:pr-tests` → `/ndf:review` → `/ndf:fix` → `/ndf:merged` で閉じる - ---- - -## スライド 5: 「固いフロー」を作る — スラッシュコマンド主義 - -ndf の Skill は、原則 `disable-model-invocation: true` を付け **モデル自動起動を禁止** している。 - -- 自動読み込み（model-invocation）は便利だが、**実行順序とタイミングがモデル任せ** になり再現性が低い -- ndf は**ユーザが明示的に `/ndf:xxx` を叩く** ことで、毎回同じ手順を踏むことを保証する -- これにより「PR 出し忘れ・テスト計画スキップ・Resolve 漏れ」といった揺らぎを排除 - -主要ワークフロー Skill: - -| Skill | 役割 | -|---|---| -| `/ndf:pr` | commit + push + PR 作成 / 既存 PR 説明更新 | -| `/ndf:pr-tests` | PR の Test Plan を自動実行 | -| `/ndf:review` | PR 単位レビュー（Approve / Request Changes 判定） | -| `/ndf:fix` | PR レビューコメントへの修正対応 | -| `/ndf:cross-review` | codex / gemini 両方が APPROVE するまで自動ループ | -| `/ndf:resolve-pr-comments` | 対応済みコメント返信 + Resolve | -| `/ndf:merged` | マージ後のローカルブランチクリーンアップ | -| `/ndf:cherry-pick-pr` | 環境ブランチへの cherry-pick PR 作成 | -| `/ndf:sync-main` | 最新 main を現在ブランチに取り込み | - ---- - -## スライド 6: 目玉機能 — クロスレビュー収束ループ - -`/ndf:cross-review ` は、**codex / gemini 両方** がレビューを返し、両者 APPROVE になるまで自動で `/ndf:review` と `/ndf:fix` を回す。 - -```mermaid -flowchart TD - A[Round N 開始] --> B[codex review 並列] - A --> C[gemini review 並列] - B --> D{両方 APPROVE?} - C --> D - D -- Yes --> Z[完了] - D -- No --> E[subagent で /ndf:fix] - E --> F{rotate_after 到達?} - F -- Yes --> G[PR ローテーション
squash + 新PR] - F -- No --> A - G --> A -``` - -設計上の特徴（事実）: - -- **メイン context を太らせない**: レビュー本文は AI 自身が `gh api` で投稿、修正は `general-purpose` サブエージェント側で実行 -- **状態を `/tmp/cross-review-pr<番号>-state.json` に永続化** し、中断・再開可能 -- **振動検知**: 前ラウンドと同じ指摘が 50% 以上重複したら自動中断 -- **PR ローテーション**: 一定 round で squash + 新 PR を切り、巨大化を防ぐ - ---- - -## スライド 7: 「MCP より CLI」の流れ - -2026 年に入り、AI コーディングエージェント向けツール接続は **MCP よりも CLI 直叩きが推奨される** ケースが増えている。外部記事の論点は以下の通り。 - -- **トークン消費**: GitHub MCP は93ツールで起動時に約 55,000 token を context に積む。一方 `gh` CLI はモデル既知でスキーマ追加 0 token、実呼び出しも ~200 token 程度 -- **信頼性**: 比較記事の計測で MCP は 25 試行中 7 件 TCP timeout、CLI は 100% 成功 -- **構成性**: Unix の pipe / シェル合成は学習データに大量に存在し、モデルが扱い慣れている -- **学習量**: man page / Stack Overflow など、CLI の使用例の学習素材が圧倒的に多い - -ただし MCP は **認証・多人数運用・企業ガバナンス** で優位なため、現実は併用が基本。 - -### ndf の判断 - -- 旧 v3 系で同梱していた **Codex MCP サーバを v4.0.0 で廃止** -- 代わりに `/ndf:codex` Skill / `corder` Agent から `codex exec` を **CLI 直接実行** -- Gemini も同様に `/ndf:gemini` Skill から CLI を呼ぶ -- Web 自動化は Playwright（CLI / Python ライブラリ）、Google 連携も Google API CLI / Python で実装 - -→ 「動かないときに自分でデバッグできる」「context を食わない」CLI を優先する方針。 - ---- - -## スライド 8: ndf に同梱されている CLI / ツール群 - -```mermaid -flowchart LR - NDF[ndf plugin] --> WF[PR/Review
Workflow Skills] - NDF --> AI[外部AI委譲] - NDF --> WEB[Web自動化] - NDF --> G[Google連携] - NDF --> DEV[開発補助] - - AI --> AI1[/ndf:codex
codex exec/] - AI --> AI2[/ndf:gemini
gemini -p/] - WEB --> W1[playwright-scenario-test
pytest-playwright + HUD動画] - WEB --> W2[browser-test
Chrome DevTools] - G --> G1[google-auth
OAuth2 一元管理] - G --> G2[google-drive
export/upload] - DEV --> D1[git-gh-operations] - DEV --> D2[python-execution
uv 自動判定] - DEV --> D3[docker-container-access] - DEV --> D4[qa-security-scan
OWASP Top 10] -``` - -特徴的な Skill: - -- **`playwright-scenario-test`**: pytest-playwright + axe-core (a11y) + Core Web Vitals 計測 + body_check（fatal/warning パターン検出）+ Markdown レポート + Google Drive 共有を fixture として提供 -- **`google-auth`**: 単一トークンで Sheets / Drive / Calendar 等のスコープを一元管理。CLI / Python ライブラリ両方として使える -- **`skill-stats`**: transcript を集計して Skill 利用率を算出。description の網羅性チェックに使う - ---- - -## スライド 9: インストール手順 - -前提: - -- Claude Code 本体 -- Python 3.10+ と `uvx`（Serena MCP 用 / 別プラグイン `mcp-serena` 経由） -- Codex CLI（外部AIレビューを使う場合）: `npm install -g @openai/codex` → `codex login` - -インストール: - -```bash -# 1. Marketplace を追加 -/plugin marketplace add https://github.com/takemi-ohama/ai-plugins - -# 2. NDF プラグイン本体をインストール -/plugin install ndf@ai-plugins - -# 3. 必要に応じて MCP プラグインを追加（任意） -/plugin install mcp-chrome-devtools@ai-plugins # Playwright相当 -/plugin install mcp-bigquery@ai-plugins -/plugin install mcp-dbhub@ai-plugins -/plugin install mcp-aws-docs@ai-plugins -/plugin install mcp-notion@ai-plugins -/plugin install mcp-serena@ai-plugins # コードインテリジェンス -``` - -環境変数（`.env`）: - -```bash -SERENA_HOME=.serena -SLACK_BOT_TOKEN=xoxb-... # Slack 通知用（任意） -SLACK_CHANNEL_ID=C... -SLACK_USER_MENTION=<@U...> -``` - -設定後に Claude Code を再起動するとフック・MCP が読み込まれる。 - ---- - -## スライド 10: まず ndf を、その先に「自分 plugin」を - -ナイルのエンジニアにはまず `ndf` をそのまま使ってもらいたい。理由は単純で、PR / レビュー / マージ後クリーンアップといった**毎日繰り返す手順を最初から共有しておけば、レビュー体験と運用ノウハウがチーム内で揃う**ため。 - -- `/ndf:pr` → `/ndf:review` → `/ndf:fix` → `/ndf:cross-review` → `/ndf:merged` を全員が同じ手順で踏む -- 「私のところでは動く」状態を減らせる -- フィードバックを上げてもらえば本体側に反映できる（OSS / MIT） - -その上で、**慣れてきたら自分の plugin を作るのが次のステップ**。 - -- 開発フローはチーム・言語・リリースサイクルで違うため、自分の手に馴染んだコマンド群を別途持っておくと効率が上がる -- plugin 化しておけば、PC 移行や新規参加者のオンボーディングが `/plugin install` 一発で済む -- 追加コストは低い: `skills//SKILL.md` を書いて `plugin.json` の skills 配列に追加するだけ - -ndf の構成はそのまま雛形として流用可能: - -- `plugins//.claude-plugin/plugin.json` … メタ情報 -- `plugins//skills//SKILL.md` … YAML frontmatter + 手順 -- `plugins//agents/.md` … サブエージェント定義 -- `plugins//hooks/hooks.json` … SessionStart / Stop など -- `plugins//.mcp.json` … MCP サーバ定義（必要時のみ） - -ndf を共通土台に、各自の好みは個人 plugin に切り出す — この二段構えがチームと個人の両方にとって扱いやすい。 - -### 参考リンク - -- Claude Code plugin ドキュメント: -- Skill 仕様: -- 「CLI vs MCP」議論の例: - - - - - - diff --git a/issues/old/i001.md b/issues/old/i001.md deleted file mode 100644 index 4ff6a81b..00000000 --- a/issues/old/i001.md +++ /dev/null @@ -1,610 +0,0 @@ -# NDFプラグインと公式プラグインの機能重複調査・削除計画 - -**作成日**: 2026-01-03 -**ステータス**: 調査完了・削除計画策定済み - -## 1. 調査概要 - -### 調査対象 -- **anthropics/claude-plugins-official**: https://github.com/anthropics/claude-plugins-official -- **NDFプラグイン**: `/work/ai-plugins/plugins/ndf/` - -### 調査結果サマリー - -anthropics/claude-plugins-officialには以下のプラグインが含まれています： - -**公式プラグイン (plugins/)**: 23個 -- LSP系プラグイン (10個): clangd, csharp, gopls, jdtls, lua, php, pyright, rust-analyzer, swift, typescript -- 開発ワークフロー系 (3個): code-review, commit-commands, pr-review-toolkit -- 開発支援系 (10個): agent-sdk-dev, example-plugin, explanatory-output-style, feature-dev, frontend-design, hookify, learning-output-style, plugin-dev, ralph-wiggum, security-guidance - -**外部プラグイン (external_plugins/)**: 13個 -- MCP統合系: github, context7, serena -- プロジェクト管理: asana, linear, gitlab, slack -- 開発ツール: firebase, greptile, laravel-boost, playwright, stripe, supabase - -## 2. 重複機能の詳細分析 - -### 2.1. MCPサーバーの重複 ⚠️ **重大な重複** - -NDFプラグインは`.mcp.json`で以下のMCPサーバーを統合しています： - -| MCPサーバー | NDFでの状態 | 公式での提供 | 重複度 | -|------------|-----------|------------|-------| -| **github** | 有効 (Docker) | external_plugins/github | **100%重複** | -| **context7** | 有効 (HTTP) | external_plugins/context7 | **100%重複** | -| **serena** | 有効 (uvx) | external_plugins/serena | **100%重複** | -| notion | 無効 | - | 重複なし | -| awslabs.aws-documentation-mcp-server | 無効 | - | 重複なし | -| mcp-server-bigquery | 無効 | - | 重複なし | -| dbhub | 無効 | - | 重複なし | -| chrome-devtools-mcp | 有効 | - | 重複なし | -| codex | 有効 | - | 重複なし | -| claude-code | 無効 | - | 重複なし | - -**結論**: **3つのMCPサーバー (github, context7, serena) が100%重複** - -### 2.2. スラッシュコマンドの重複 🔶 **部分的重複** - -#### NDFプラグインのコマンド (6個) -1. `/ndf:serena` - 開発記憶の記録 -2. `/ndf:pr` - PR作成 -3. `/ndf:fix` - PR修正対応 -4. `/ndf:review` - PRレビュー -5. `/ndf:merged` - マージ後クリーンアップ -6. `/ndf:clean` - ブランチクリーンアップ - -#### 公式プラグインのコマンド - -**commit-commands プラグイン**: -- Git commit/push/PR作成のワークフローコマンド -- NDFの`/ndf:pr`と**機能的に重複**の可能性あり - -**code-review プラグイン**: -- 自動コードレビュー機能 -- NDFの`/ndf:review`と**機能的に重複**の可能性あり - -**pr-review-toolkit プラグイン**: -- 包括的なPRレビューエージェント -- NDFの`/ndf:review`と**機能的に重複**の可能性あり - -**結論**: **コマンド名は異なるが、機能的には重複あり** - -### 2.3. サブエージェントの重複 ✅ **重複なし** - -#### NDFプラグインのエージェント (6個) -1. **director** - タスク統括と調整 -2. **data-analyst** - データ分析とSQL操作 -3. **corder** - 高品質コード生成 -4. **researcher** - 情報収集と分析 -5. **scanner** - ファイル読み取り -6. **qa** - 品質管理とテスト - -#### 公式プラグインのエージェント - -**pr-review-toolkit プラグイン**: -- comments, tests, error-handling, type-design, code-quality, code-simplification -- NDFの**qa**エージェントと**機能的に類似** - -**結論**: **名前は異なるが、qaエージェントとpr-review-toolkitは機能的に類似** - -### 2.4. Claude Code Skillsの重複 ✅ **重複なし** - -NDFプラグインは10個のClaude Code Skillsを独自に提供しており、公式プラグインには同等の機能はありません。 - -**結論**: **Skillsは完全にNDF独自機能** - -## 3. 削除対象の特定 - -### 3.1. 削除すべきもの（高優先度） - -#### A. MCPサーバー統合の削除 ⚠️ **最優先** - -**対象ファイル**: `/work/ai-plugins/plugins/ndf/.mcp.json` - -**削除対象セクション**: -```json -// 完全削除 -"github": { ... } -"context7": { ... } -"serena": { ... } -``` - -**理由**: -- これら3つのMCPサーバーは公式external_pluginsで提供されている -- ユーザーは公式プラグインを個別にインストール可能 -- NDFで統合する必要性なし -- メンテナンス負担の軽減 - -**影響範囲**: -- NDFプラグインのREADME.mdの「MCP統合」セクション更新必要 -- CLAUDE.ndf.mdの「Available MCP Tools」セクション更新必要 -- Serenaメモリー (`plugin-ndf.md`) の更新必要 -- plugin.jsonのバージョンインクリメント (1.2.1 → 1.3.0 or 2.0.0) - -### 3.2. 検討すべきもの（中優先度） - -#### B. スラッシュコマンドの整理 🔶 - -**現状**: -- NDFプラグインは6個のワークフローコマンドを提供 -- 公式には`commit-commands`, `code-review`, `pr-review-toolkit`が存在 -- 機能的に重複する可能性あり - -**推奨アクション**: -1. **詳細調査を実施** - 公式プラグインのコマンド内容を精査 -2. **差別化要素を明確化** - NDFコマンドの独自価値を確認 -3. **統合または削除を判断** - ユーザー体験を最優先 - -**注意**: -- ユーザーがすでにNDFコマンドに慣れている場合、削除は混乱を招く -- 公式コマンドとNDFコマンドの併用も可能 -- 段階的な移行計画が必要 - -#### C. qaエージェントとpr-review-toolkitの関係 🔶 - -**現状**: -- NDFの`qa`エージェントはコード品質・セキュリティ・パフォーマンステストを担当 -- 公式の`pr-review-toolkit`は包括的なPRレビュー機能を提供 -- 機能的に類似 - -**推奨アクション**: -1. **詳細調査を実施** - pr-review-toolkitの機能範囲を確認 -2. **補完関係の確認** - NDFのqaエージェントが提供する独自価値を評価 -3. **統合または共存を判断** - ユーザーニーズに基づく - -### 3.3. 保持すべきもの（削除不要） - -#### D. 独自のサブエージェント ✅ - -以下のエージェントは完全にNDF独自機能として保持： -- **director** - タスク統括（公式にない） -- **data-analyst** - BigQueryやDBHub連携（公式にない） -- **corder** - Codex統合のコーディング支援（公式にない） -- **researcher** - AWS Docs/Chrome DevTools連携（公式にない） -- **scanner** - PDF/Excel読み取り（公式にない） - -#### E. Claude Code Skills ✅ - -10個のSkillsはすべてNDF独自機能として保持： -- director-project-planning -- data-analyst-sql-optimization -- data-analyst-export -- corder-code-templates -- corder-test-generation -- researcher-report-templates -- scanner-pdf-analysis -- scanner-excel-extraction -- qa-code-review-checklist -- qa-security-scan - -#### F. 独自のMCPサーバー ✅ - -以下のMCPサーバーは公式に存在しないため保持： -- notion (現在無効) -- awslabs.aws-documentation-mcp-server (現在無効) -- mcp-server-bigquery (現在無効) -- dbhub (現在無効) -- chrome-devtools-mcp (有効) -- codex (有効) -- claude-code (現在無効) - -#### G. Slackフック・通知機能 ✅ - -以下は完全にNDF独自機能として保持： -- `hooks/hooks.json` -- `scripts/slack-notify.js` -- Stop hookによる自動Slack通知 - -## 4. 削除手順の詳細計画 - -### フェーズ1: MCPサーバー統合の削除（最優先） - -#### ステップ1: .mcp.jsonの編集 - -**対象ファイル**: `plugins/ndf/.mcp.json` - -**変更内容**: -```json -{ - "mcpServers": { - // ❌ 削除: "github": { ... } - // ❌ 削除: "context7": { ... } - // ❌ 削除: "serena": { ... } - - // ✅ 保持 - "notion": { ... }, - "awslabs.aws-documentation-mcp-server": { ... }, - "mcp-server-bigquery": { ... }, - "dbhub": { ... }, - "chrome-devtools-mcp": { ... }, - "codex": { ... }, - "claude-code": { ... } - } -} -``` - -#### ステップ2: README.mdの更新 - -**対象ファイル**: `plugins/ndf/README.md` - -**更新セクション**: -- 「MCP統合」セクション: 10サーバー → 7サーバーに変更 -- 削除したMCPサーバーの説明を削除 -- 公式external_pluginsへの参照を追加 - -**追加テキスト例**: -```markdown -## 公式プラグインとの連携 - -以下のMCPサーバーは公式external_pluginsで提供されています。 -必要に応じて個別にインストールしてください： - -- **GitHub MCP**: `/plugin install github@claude-plugin-directory` -- **Context7 MCP**: `/plugin install context7@claude-plugin-directory` -- **Serena MCP**: `/plugin install serena@claude-plugin-directory` -``` - -#### ステップ3: CLAUDE.ndf.mdの更新 - -**対象ファイル**: `plugins/ndf/CLAUDE.ndf.md` - -**更新セクション**: -- "Available MCP Tools (Reference)" セクション -- 削除したMCPサーバーの説明を削除 -- バージョンコメントを更新 - -```markdown - -``` - -#### ステップ4: Serenaメモリーの更新 - -**対象ファイル**: Serenaメモリー `plugin-ndf.md` - -**更新内容**: -- MCPサーバー数: 10 → 7に変更 -- 削除した3つのMCPサーバーの説明を削除 -- 公式プラグイン参照を追加 - -#### ステップ5: plugin.jsonのバージョン更新 - -**対象ファイル**: `plugins/ndf/.claude-plugin/plugin.json` - -**バージョン判断**: -- **MAJOR (2.0.0)**: MCP統合を削除は破壊的変更の可能性あり（推奨） -- **MINOR (1.3.0)**: 後方互換性があると判断した場合 - -**推奨**: **2.0.0** (破壊的変更として扱う) - -**理由**: -- ユーザーがgithub/context7/serena MCPに依存している場合、動作しなくなる -- 明示的なメジャーバージョンアップで変更を周知 - -```json -{ - "name": "ndf", - "version": "2.0.0", - "description": "Integrated plugin with specialized agents, commands, and skills. MCP servers moved to official plugins.", - ... -} -``` - -#### ステップ6: テスト - -1. **ローカルテスト**: - ```bash - /plugin reload ndf - /help mcp - ``` - - github, context7, serena MCPが表示されないことを確認 - -2. **機能テスト**: - - 残りの7つのMCPサーバーが正常に動作することを確認 - - サブエージェント（director, corder等）が正常に動作することを確認 - -3. **ドキュメント検証**: - - README.mdの記載が正確であることを確認 - - CLAUDE.ndf.mdの記載が正確であることを確認 - -#### ステップ7: コミット・PR作成 - -**ブランチ名**: `feature/remove-duplicate-mcp-servers` - -**コミットメッセージ例**: -``` -feat: GitHub/Context7/Serena MCPを公式プラグインに移譲 - -BREAKING CHANGE: 以下のMCPサーバーをNDFプラグインから削除 -- github MCP -- context7 MCP -- serena MCP - -これらのMCPサーバーは公式external_pluginsで提供されるため、 -必要に応じて個別にインストールしてください： - /plugin install github@claude-plugin-directory - /plugin install context7@claude-plugin-directory - /plugin install serena@claude-plugin-directory - -影響: -- .mcp.jsonから3つのMCPサーバー定義を削除 -- README.md、CLAUDE.ndf.md、Serenaメモリーを更新 -- バージョンを2.0.0にアップグレード - -🤖 Generated with [Claude Code](https://claude.com/claude-code) - -Co-Authored-By: Claude Opus 4.5 -``` - -**PR説明**: -```markdown -## Summary -- NDFプラグインからgithub/context7/serena MCPサーバー統合を削除 -- これらのMCPサーバーはanthropics/claude-plugins-officialのexternal_pluginsで提供されているため重複を解消 - -## Breaking Changes -⚠️ **破壊的変更**: 以下のMCPサーバーがNDFプラグインから削除されます -- GitHub MCP -- Context7 MCP -- Serena MCP - -## Migration Guide -ユーザーは以下のコマンドで公式プラグインをインストールできます： -```bash -/plugin install github@claude-plugin-directory -/plugin install context7@claude-plugin-directory -/plugin install serena@claude-plugin-directory -``` - -## Changes -- 削除: .mcp.json内のgithub/context7/serena MCP定義 -- 更新: README.md（MCP統合セクション） -- 更新: CLAUDE.ndf.md（Available MCP Toolsセクション） -- 更新: Serenaメモリー（plugin-ndf.md） -- 更新: plugin.json（バージョン2.0.0） - -## Test Plan -- [x] ローカルでNDFプラグインを再読み込み -- [x] 残りの7つのMCPサーバーが正常動作 -- [x] サブエージェントが正常動作 -- [x] ドキュメントが正確 - -🤖 Generated with [Claude Code](https://claude.com/claude-code) -``` - -### フェーズ2: スラッシュコマンドの整理（中優先度） - -#### 前提条件 -フェーズ1（MCPサーバー削除）完了後に実施 - -#### ステップ1: 公式プラグインのコマンド詳細調査 - -**調査対象**: -1. `commit-commands` プラグインのコマンド一覧と機能 -2. `code-review` プラグインのコマンド一覧と機能 -3. `pr-review-toolkit` プラグインのコマンド一覧と機能 - -**調査方法**: -- GitHubリポジトリから各プラグインのREADME.mdとcommands/を確認 -- 実際にプラグインをインストールして動作確認 - -#### ステップ2: 重複・差別化要素の評価 - -**評価基準**: -| 項目 | 評価内容 | -|-----|---------| -| 機能の重複度 | 公式コマンドと完全に重複しているか | -| 独自価値 | NDFコマンドにしかない機能があるか | -| ユーザー体験 | コマンド名・使用方法が直感的か | -| メンテナンス性 | NDFで保持する価値があるか | - -#### ステップ3: 削除判断と実施 - -**判断フロー**: -1. **完全重複かつ独自価値なし** → 削除 -2. **部分重複だが独自価値あり** → 保持（ドキュメント強化） -3. **重複なし** → 保持 - -**削除手順**（削除対象がある場合）: -1. `plugin.json`のcommandsフィールドから削除 -2. `commands/`ディレクトリから該当ファイルを削除 -3. README.md、CLAUDE.ndf.mdを更新 -4. Serenaメモリーを更新 -5. plugin.jsonのバージョンをインクリメント (2.0.0 → 2.1.0 or 3.0.0) -6. テスト・コミット・PR作成 - -### フェーズ3: qaエージェントの評価（低優先度） - -#### ステップ1: pr-review-toolkitの機能確認 - -**調査内容**: -- pr-review-toolkitのエージェント一覧と機能 -- NDFのqaエージェントとの機能比較 -- 補完関係の評価 - -#### ステップ2: 統合・共存判断 - -**判断基準**: -| シナリオ | アクション | -|---------|----------| -| 完全重複 | qaエージェントを削除または統合 | -| 補完関係 | 両方保持、ドキュメントで使い分けを明記 | -| 独自機能多数 | qaエージェント保持 | - -## 5. 削除による影響評価 - -### 5.1. ユーザーへの影響 - -#### A. MCPサーバー削除 (フェーズ1) - -**影響度**: 🔴 **高** - -**影響を受けるユーザー**: -- github/context7/serena MCPを使用している全ユーザー - -**移行手順**: -1. NDFプラグインを2.0.0にアップグレード -2. 必要なMCPサーバーを個別にインストール - ```bash - /plugin install github@claude-plugin-directory - /plugin install context7@claude-plugin-directory - /plugin install serena@claude-plugin-directory - ``` - -**メリット**: -- 公式プラグインの最新機能を利用可能 -- NDFプラグインのメンテナンス負担軽減 -- 明確な責任分界点 - -**デメリット**: -- 移行作業が必要 -- インストールコマンドが増える - -#### B. スラッシュコマンド削除 (フェーズ2) - -**影響度**: 🟡 **中** (削除対象による) - -**影響を受けるユーザー**: -- 削除対象コマンドを使用しているユーザー - -**移行手順**: -- 公式プラグインの対応コマンドに移行 - -#### C. qaエージェント削除 (フェーズ3) - -**影響度**: 🟡 **中** (削除する場合) - -**影響を受けるユーザー**: -- qaエージェントを使用している全ユーザー - -**移行手順**: -- pr-review-toolkitプラグインに移行 - -### 5.2. 技術的影響 - -**プラグイン構成**: -- ファイル数: 若干減少 -- 依存関係: シンプル化 -- メンテナンス性: 向上 - -**互換性**: -- バージョン1.x → 2.x: 破壊的変更あり -- 既存ユーザーへの周知必須 - -## 6. リスクと対策 - -### リスク1: ユーザーの混乱 - -**リスク**: MCPサーバーが突然使えなくなる - -**対策**: -- 明確なマイグレーションガイド提供 -- README.mdに大きく記載 -- BREAKING CHANGEとしてコミットメッセージに明記 - -### リスク2: 機能劣化の懸念 - -**リスク**: 公式プラグインがNDFの統合版より使いづらい - -**対策**: -- 事前に公式プラグインの動作確認 -- 必要に応じてフィードバックをAnthropicに提供 - -### リスク3: ユーザー離反 - -**リスク**: 変更が大きすぎてNDFプラグインから離れる - -**対策**: -- 段階的な変更（フェーズ1→2→3） -- 各フェーズで十分な周知期間を設ける -- ユーザーフィードバックを収集 - -## 7. 推奨スケジュール - -### 即座に実施（Week 1-2） - -✅ **フェーズ1: MCPサーバー削除** -- 最も重複度が高く、明確な削除対象 -- 公式プラグインで代替可能 -- 即座に実施推奨 - -### 調査後に判断（Week 3-4） - -🔶 **フェーズ2: スラッシュコマンド整理** -- 詳細調査が必要 -- ユーザー影響を慎重に評価 -- 調査結果に基づいて判断 - -### 長期的に検討（Month 2-3） - -🔶 **フェーズ3: qaエージェント評価** -- 急ぎではない -- pr-review-toolkitの成熟度を見極める -- ユーザーフィードバックを収集してから判断 - -## 8. 成功基準 - -### フェーズ1成功基準 - -- [ ] .mcp.jsonから3つのMCPサーバーが削除されている -- [ ] README.md、CLAUDE.ndf.md、Serenaメモリーが更新されている -- [ ] plugin.jsonが2.0.0にアップグレードされている -- [ ] ローカルテストがすべてパスしている -- [ ] PRがマージされている -- [ ] ユーザーへの周知が完了している - -### フェーズ2成功基準 - -- [ ] 公式プラグインのコマンド詳細調査が完了している -- [ ] 削除判断が明確になっている -- [ ] 削除対象がある場合、実施完了している -- [ ] ユーザーへの移行ガイドが提供されている - -### フェーズ3成功基準 - -- [ ] pr-review-toolkitの機能確認が完了している -- [ ] qaエージェントの方向性が決定している -- [ ] 必要に応じて実施完了している - -## 9. 次のアクション - -### 即座に実施すべきこと - -1. **ユーザーに確認** - - この削除計画に同意するか - - 特に懸念事項はないか - -2. **フェーズ1実施開始** - - featureブランチ作成 - - .mcp.json編集 - - ドキュメント更新 - - テスト・コミット・PR作成 - -### 後続タスク - -3. **フェーズ2調査開始** - - 公式プラグインのコマンド詳細調査 - - 削除判断の材料収集 - -4. **フェーズ3調査開始** - - pr-review-toolkitの機能確認 - - 長期的な方向性検討 - -## 10. 参考情報 - -### 関連リンク - -- **anthropics/claude-plugins-official**: https://github.com/anthropics/claude-plugins-official -- **NDFプラグイン**: `/work/ai-plugins/plugins/ndf/` -- **Claude Code公式ドキュメント**: https://docs.claude.com/en/docs/claude-code - -### 調査で使用したツール - -- Serena MCP: プロジェクト構造理解 -- GitHub MCP: 公式リポジトリ調査 -- Read/Glob/Grep: ファイル内容確認 - ---- - -**最終更新**: 2026-01-03 -**作成者**: Claude Code (Director Agent) diff --git a/issues/old/i01.md b/issues/old/i01.md deleted file mode 100644 index 02bce554..00000000 --- a/issues/old/i01.md +++ /dev/null @@ -1,102 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - - -# 1. plugins/mcp-integration にcodex mcpを追加 -https://zenn.dev/tmasuyama1114/articles/cdfd4562bdce78 -* この記事を参考にplugins/mcp-integrationでinstallするMCPにcodex cli mcpを追加してください -* README.mdなども修正してください - - -# 2. context7追加 -plugins/ndf にcontext7 mcpを追加します -https://github.com/upstash/context7 - -# 3. サブエージェント追加 -plugins/ndf にサブエージェントも追加します。 - * data analyst ... bigquery, dbhubの操作を担当。SQL生成と結果の解釈、結果データのファイル出力を担当する。 - * corder ... コーディングを担当。codex mcp, serena mcp, context7 mcpを活用し品質の高いコードを生成する。 - * researcher ... 調査担当。codex mcpやaws documentation mcp, Chrome DevToolsを活用し、外部サイトから情報を収集。分析して結果を返す - * scanner ... 画像、PDF、Officeファイル担当。pdf、画像、ppt、xlsといったClaude Codeが直接読めないファイルをcodex mcpに任せて読み取ってもらう。 - -# 4. README.md拡充 -* plugins/ndf/README.md に必要事項を追加します。 - * plugins/mcp-integration/README.mdを参考に、DATABASE_DSNなどの設定方法を追加 - * plugins/install-slack-hook/README.md を参考にSLACK BOTの設定方法 - -# 5. mainエージェントへの指示 -plugins/ndf/ -* mainエージェント(親エージェント)にsub agentの役割と積極活用を促す指示を追加してください -# 6. slack通知に作業要約追加 -plugins/ndf/hooks/hooks.json -* slack-notify.shをstop hookで呼び出しています。 -* この処理を以下のように変更してください。 -* promptで40文字以内の日本語要約を作成 -* agent toolで要約を引数につけてslack-notify.shを呼び出す - -# 7. クリーニング -* plugins/ndf/agents/slack-notifier.md 不要になったので削除してください -* ndfのバージョンを1.0.2としてください -* plugins/ndf/scripts/slack-notify.sh こちらもおそらく不要です。念のため確認してから削除 -* ndfのREADME.md, CLAUDE.mdを修正 -* プロジェクトルートのREADME.md, CLAUDE.mdも修正 - -# 8. リファクタリング -* plugins/ndf/scripts/slack-notify.js をリファクタリングしてください - * 目的は可読性の向上と冗長なコードの簡潔化です。 - -# 9. クリーニング2 -* plugins/ndf/agents/memory-recorder.md こちらも利用しないことになったので削除してください -* ndfのREADME.md, CLAUDE.mdを修正 -* プロジェクトルートのREADME.md, CLAUDE.mdも修正 - -# 10. 品質管理サブエージェントの追加 -* plugins/ndf/agents 品質管理(qa)を担当するサブエージェントを追加してください。 - -# 11. CLAUDE.md方針 -* plugins/ndf/CLAUDE.md を以下の方針としてください -* 大方針 - * 日本語で応答 - * 勝手なgit pushは禁止。特にデフォルトブランチにはpushしない。 -* 行動指針 - * コンテキストの管理、段階的開示を意識する - * sub agent, mcpの積極活用 - * mainエージェントはtodolistの管理と結果の統合に徹し、それ以外はできるだけサブエージェントに任せる - * serena mcpはmain, subいずれのエージェントでも活用する - * serena mcpの使い方をCLAUDE.mdに記載しておく - * 特にテキストファイルの読み書きは原則serena mcpを利用して行う - * PDF、画像、officeツール(xls, pptなど)などのバイナリファイルの読み取りはscannerエージェント経由でcodex mcpに依頼 - * 事実を調査する - * 技術的に難易度が高い課題はresearcherによって外部リソースを調査してから解決策を検討する - * 現在記載されているStop Hookに関する事項は解消されたので不要になりました。 - -# 12. README.md改善 -* plugins/ndf/README.md を改修します -* README.mdはユーザ向け、CLAUDE.mdはエージェント向けです。 - * 設定では、先に設定ステップ全体の流れを説明してから、設定方法の詳細に入ってください - * 開発ワークフローの説明をmcpよりも先にしてください。 - * mcpの詳細説明はCLAUDE.mdを参照するように記載し、ここでの説明は最小限にしてください -* DBHubについて - * DBHubの設定の説明が冗長です。例はなくて良いでしょう。 - * DBHubの設定の説明で、mysqlとmariadbは設定方法が同じなのでまとめてください - * SSLの説明はPostgresのセクションに記述してください - * SSHによる踏み台経由の接続方法についても記載して下さい(mysqlのみでも可) -* 開発ワークフローコマンドの使用例は不要です(大体コマンド名が記載されているだけなので)。 - * 何をするコマンドなのか、いつ使うのかを2-3行程度で説明してください -* mcpの説明で、使わないmcpはdisableしておくことを推奨し、diableの手順を記載してください -* 自動フックの説明は古いです。現状に合わせてください -* トラブルシューティングはこの内容なら不要です。 - -* ついでにplugins/ndf/CLAUDE.md も修正 - * 勝手にpushしない、をpush/mergeしないに修正 - * PRのmergeはユーザが行う前提です。 - * タスク分類のフローチャート はmermaid記法で記載してください - -# 13. お行儀の悪いmcpのデフォルトdisable -* aws-docmentation, claude-code, dbhub, bigquery, notion mcpはデフォルトでdisable=trueとしてください。 -* aws-docはエラーが出る、bigqueryとdbhubは利用するプロジェクトが限られる -* claude-code, notionはcontextが大きすぎるためです。 diff --git a/issues/old/i02.md b/issues/old/i02.md deleted file mode 100644 index 212e30a6..00000000 --- a/issues/old/i02.md +++ /dev/null @@ -1,48 +0,0 @@ -# Issue #02: @playwright/mcpパッケージのChromium認識問題 - -**報告日**: 2025-11-16 -**ステータス**: 調査完了 -**優先度**: 高 - -## 問題の概要 - -`npx -y @playwright/mcp@latest --browser chromium`で起動すると、以下のエラーが発生： - -``` -Browser specified in your config is not installed. Either install it (likely) or change the config. -``` - -`npx playwright install chromium`でChromiumをインストール済み（`~/.cache/ms-playwright/chromium-1194/`）にもかかわらず、ブラウザが認識されない。 - -## 根本原因 - -### 1. npx実行時の分離環境 - -`npx`経由で`@playwright/mcp`を実行すると、以下のような問題が発生： - -- **一時的なnode_modules**: npxは一時的な場所に`@playwright/mcp`とその依存関係（`playwright@1.57.0-alpha-2025-11-14`、`playwright-core@1.57.0-alpha-2025-11-14`）をダウンロード -- **バージョン不一致**: 事前に`npx playwright install chromium`でインストールしたChromiumは、別バージョンのPlaywrightでインストールされた可能性がある -- **ブラウザパス認識の問題**: 各Playwrightインストールは、自身がインストールしたブラウザのみを認識する - -### 2. Playwrightのブラウザ認識メカニズム - -Playwrightは以下の順序でブラウザを検索： - -1. **PLAYWRIGHT_BROWSERS_PATH環境変数**（最優先） -2. **デフォルトキャッシュディレクトリ**: - - Linux: `~/.cache/ms-playwright` - - macOS: `~/Library/Caches/ms-playwright` - - Windows: `%USERPROFILE%\AppData\Local\ms-playwright` - -しかし、**各Playwrightパッケージのバージョンは、それぞれ独自のブラウザバージョンを期待**する。 - -### 3. バージョン管理の問題 - -```bash -# 例: 以前インストールしたChromium -~/.cache/ms-playwright/chromium-1194/ - -# @playwright/mcpが期待するChromiumバージョン -# playwright@1.57.0-alpha-2025-11-14 が期待するバージョン -# → 異なる可能性がある -``` diff --git a/issues/old/i03.md b/issues/old/i03.md deleted file mode 100644 index e18b42e7..00000000 --- a/issues/old/i03.md +++ /dev/null @@ -1,20 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - - -# 1. 来年度開発指針作成 -これまでとは全く異なるミッションです。 - -issues/開発指針.md - -にあるように、2026年度(来年)の開発指針を策定しようとしています。 -issues/開発指針.mdはそのアイデアノートです。 - -このノートから、10p程度のプレゼンテーション資料を作成してください。 -実際の作成はcodex mcpに依頼し、まずはmarkdown形式のページごとの内容を作成したあと、 -pptxファイルを作成してください。pptxで10ページ-15ページ程度になることが望ましいです。 - diff --git a/issues/old/i04.md b/issues/old/i04.md deleted file mode 100644 index 6a66aa29..00000000 --- a/issues/old/i04.md +++ /dev/null @@ -1,24 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - - -# 1. plugins/ndf/CLAUDE.md をルートに転記するSessionStart hook -* plugins/ndf/CLAUDE.md にこのpluginを活用するための指針を記載していましたが、pluginをインストールしただけでは読み込まれないようです。 -* このため、plugins/ndf/hooks/hooks.json のSessionStart hookに以下のようなスクリプトを追加してください - * プロジェクトのCLAUDE.mdまたはAGENT.mdを探す(できるだけ上位のディレクトリにあるもの、ついで.claude/にあるものを優先) - * 既に最新バージョンのCLAUDE_plugin.md の内容が転記済みであれば修了(*後述) - * 転記されていなければ - * 最新バージョン前の記述があればそれを削除 - * 最新バージョンの記述をmdファイルの一番最後に追記 - -* plugins/ndf/CLAUDE.mdの転記済み判断とバージョン管理は以下の通りです。 - * これはhookではなくai-pluginsプロジェクトが行います。 - * このプロジェクトルートのCLAUDE.mdにも以下を書いておいてください - * plugins/ndf/CLAUDE_plugin.mdの前後を固定の文字列+バージョン番号で囲む - * 「固定の文字列は無意味」な英数字の羅列30文字とする - * plugins/ndf/CLAUDE_plugin.mdの内容を変更した場合はバージョン番号をインクリメントする - diff --git a/issues/old/i05.md b/issues/old/i05.md deleted file mode 100644 index 6135a941..00000000 --- a/issues/old/i05.md +++ /dev/null @@ -1,32 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - - -# 1. サブエージェント「director」追加 -* ndf pluginに「director」サブエージェントを追加してください。 -* directorは、main agentが担っていた責務すべてが担当です。 -* main agentはできるだけ何もせず、サブエージェントへの指示のみに徹 するようにしてください。 -* ファイル調査、プラン作成、結果の取りまとめなど。指示出し以外のすべての業務を可能な限りsub agentに任せるようにしてください。 - -# 2. 適切な状況報告体制の構築 -* ndf:director sub agentはバックグラウンドで動作することを前提に、適切なタイミングごとに、mainエージェントに作業内容を報告するようにしてください。 - * また、main agentはsub agentの報告を受信してユーザに報告するようにしてください。 - * 報告は最初は1分毎、とし、タスクが長くなるようならそれに応じて報告間隔も広くしてください - * plugins/ndf/CLAUDE.ndf.mdにもこの仕様を書いておいてください - - -# 3. slack-notify.js 処理順変更 -plugins/ndf/scripts/slack-notify.js の処理を変更します。 -* これまで、メンション付き通知→要約作衛→メンション削除→要約付きメッセージ通知、だったはずです。 -* これを、要約作成→「メンション付きかつ要約付きメッセージ」送信→「メンションなし&要約付きメッセージ」送信→「メンション付きかつ要約付きメッセージ」削除、という順番としてください - -# 4. サブエージェント、MCPのネスト禁止ルール追加 -* サブエージェントを利用する際、サブエージェントがサブエージェントを呼ぶことを繰り返してしまう、coreダンプする現象が発生しているようです。 - * directorサブエージェントはたのサブエージェントやMCPを呼ぶことができる。ただしdirectors subagentやclaude code mcpを呼んではいけない(無限呼び出し回避) - * director以外のサブエージェントは他のサブエージェントを呼んではいけない。 - * MCPは利用してかまわない。ただし無限呼び出しは防ぐこと -* 以上のルールに従って、plugins/ndf/agents/内のファイルやplugins/ndf/CLAUDE.ndf.mdを修正してください diff --git a/issues/old/i06.md b/issues/old/i06.md deleted file mode 100644 index f83c09d2..00000000 --- a/issues/old/i06.md +++ /dev/null @@ -1,26 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - -# 1. チューニング -* plugins/ndf/agents/director.md 策定された計画は、適切な場所にファイルとして保存するように定義してください - * プロジェクトのissues/ やgithub issue、notion等が適切な場所となります。 - * それらにこのプロジェクトに対する既存のissue、ticket等が存在していればそこが適切な場所と判断可能です。 - * プロジェクト内 > github issues > notionが優先順位となります - * 判断が困難な場合はユーザーに選択肢で問いかけてください。 -* plugins/ndf/agents/scanner.md codexの利用にこだわらず、claude codそのものや、mcp、LLMのAPIなど可能な手段を使ってバイナリファイルを読むように変更してください。 - -# 2. 外部サイト調査 -* 外部サイト調査にChrome Dev toolsやplaywright mcpを使う様に支持しているagentがありますが、これらはどうも遅いので、普通にWeb FetchやWeb Searchを利用するように変更してください。 -* また、外部サイトの調査に適した無料のAI向けツールがあれば、それらを利用しても構いません。 - - -# 3. sub agentに対応したskillの利用 -* plugins/ndf/agents で定義されているsub agentsにAgent Skillsを導入してください。 - * https://code.claude.com/docs/ja/skills -* 各agentはそれぞれ必要なskillを積極的に呼び出して利用します。 -* 外部のpublicなskillsを踏査して、適したskillが公開されていれば、そちらをこのpluginに取り込んでください -* sub agentの目的に照らしてSkillの利点を生かした適切なスクリプトやテンプレート、toolを生成・定義してください diff --git a/issues/old/i07-skills-design.md b/issues/old/i07-skills-design.md deleted file mode 100644 index 9727e7c3..00000000 --- a/issues/old/i07-skills-design.md +++ /dev/null @@ -1,943 +0,0 @@ -# NDFプラグイン - Sub-Agent Skills 詳細設計書 - -**作成日**: 2025-12-15 -**担当**: director agent -**関連Issue**: i07.md - ---- - -## 設計方針 - -### 基本原則 -1. **焦点を絞る**: 1 Skill = 1機能 -2. **明確な説明**: トリガー用語を含む具体的なdescription -3. **既存MCPとの重複回避**: MCPで実現できることはSkillsにしない -4. **作業効率最大化**: 繰り返しタスクの自動化、テンプレート化 - -### 優先度基準 -- **高**: 頻繁に実行する定型作業、テンプレート化で大幅な時短 -- **中**: 有用だが頻度は中程度、または実装コストが高い -- **低**: Nice-to-have、または既存ツールで十分対応可能 - ---- - -## 1. director agent 用 Skills - -### Skill 1.1: Project Planning Templates -**name**: `director-project-planning` -**description**: Create structured project plans with task breakdown, timeline, resource allocation, and risk assessment. Use when starting new features, refactoring, or complex implementations. Triggers: "plan", "roadmap", "task breakdown", "project structure". - -**提供機能**: -- プロジェクト計画書テンプレート生成 -- タスク分解とマイルストーン設定 -- リスク評価とリソース配分 -- 並列実行可能性の自動判断 - -**ディレクトリ構造**: -``` -skills/director-project-planning/ -├── SKILL.md -├── templates/ -│ ├── project-plan-template.md -│ ├── task-breakdown-template.md -│ └── risk-assessment-template.md -└── scripts/ - └── generate-plan.js -``` - -**allowed-tools**: Read, Write, Glob, Grep - -**スクリプト概要** (`generate-plan.js`): -- ユーザー入力（プロジェクト概要、目標）を受け取る -- テンプレートを読み込み、動的に項目を埋める -- タスク分解を提案（実装→テスト→ドキュメント） -- issues/ディレクトリに自動保存 - -**テンプレート概要** (`project-plan-template.md`): -```markdown -# [プロジェクト名] 実装計画 - -## 概要 -- 目的: -- スコープ: -- 期限: - -## タスク分解 -### フェーズ1: [名前] -- [ ] タスク1 -- [ ] タスク2 - -## リソース配分 -- 必要なサブエージェント: -- 並列実行可能タスク: - -## リスク評価 -- リスク1: [説明] - 対策: -``` - -**優先度**: 🔴 **高** - Directorの最も重要な機能 - ---- - -### Skill 1.2: GitHub Integration -**name**: `director-github-integration` -**description**: Create and manage GitHub issues, pull requests, and milestones from project plans. Use when converting plans to actionable GitHub items. Triggers: "create issue", "open PR", "github milestone", "track progress". - -**提供機能**: -- 計画書からGitHub Issue自動生成 -- Pull Request作成支援 -- マイルストーン管理 -- 進捗トラッキング - -**ディレクトリ構造**: -``` -skills/director-github-integration/ -├── SKILL.md -├── templates/ -│ ├── issue-template.md -│ └── pr-template.md -└── scripts/ - └── create-github-items.js -``` - -**allowed-tools**: Bash（git/gh コマンド）, Read, Write - -**スクリプト概要** (`create-github-items.js`): -- 計画書を解析し、タスクごとにIssueを作成 -- `gh issue create`コマンドを実行 -- Issue番号を計画書に逆参照として追加 -- ラベル、担当者、マイルストーンを自動設定 - -**テンプレート概要** (`issue-template.md`): -```markdown -## 概要 -[タスクの説明] - -## 受入基準 -- [ ] 基準1 -- [ ] 基準2 - -## 関連 -- 計画書: [リンク] -- 親Issue: #XXX -``` - -**優先度**: 🟡 **中** - GitHub統合は便利だが、手動でも可能 - ---- - -### Skill 1.3: Progress Reporting -**name**: `director-progress-report` -**description**: Generate progress reports summarizing completed tasks, ongoing work, blockers, and next steps. Use when updating stakeholders or reviewing project status. Triggers: "progress report", "status update", "weekly report". - -**提供機能**: -- 進捗レポート自動生成 -- 完了タスク、進行中タスク、ブロッカーの整理 -- 次のアクション提案 -- グラフ・統計データ生成（オプション） - -**ディレクトリ構造**: -``` -skills/director-progress-report/ -├── SKILL.md -├── templates/ -│ └── progress-report-template.md -└── scripts/ - └── generate-report.js -``` - -**allowed-tools**: Read, Write, Bash（git log等） - -**スクリプト概要** (`generate-report.js`): -- Git historyから最近のコミットを取得 -- issues/ディレクトリの計画書を読み、進捗を抽出 -- 完了率を計算 -- レポートを生成してissues/配下に保存 - -**テンプレート概要** (`progress-report-template.md`): -```markdown -# 進捗レポート - [日付] - -## サマリー -- 完了タスク: X個 -- 進行中タスク: Y個 -- ブロッカー: Z個 - -## 詳細 -### 完了 -- [タスク名] - [完了日] - -### 進行中 -- [タスク名] - [進捗率] - -### ブロッカー -- [問題] - [対策] - -## 次のステップ -1. -``` - -**優先度**: 🟢 **低** - Nice-to-have、手動でも容易 - ---- - -## 2. data-analyst agent 用 Skills - -### Skill 2.1: SQL Optimization Patterns -**name**: `data-analyst-sql-optimization` -**description**: Apply SQL optimization patterns including index usage, query rewriting, JOIN optimization, and window functions. Use when improving query performance. Triggers: "optimize SQL", "slow query", "improve performance". - -**提供機能**: -- SQLクエリ最適化パターンライブラリ -- パフォーマンス改善提案 -- インデックス推奨 -- クエリ実行計画の解析 - -**ディレクトリ構造**: -``` -skills/data-analyst-sql-optimization/ -├── SKILL.md -├── reference.md # 最適化パターン詳細 -└── examples.md # Before/Afterサンプル -``` - -**allowed-tools**: なし（参照のみ） - -**reference.md 概要**: -```markdown -## パターン1: N+1クエリ削減 -**Before**: 複数回のSELECT -**After**: JOINまたはサブクエリ - -## パターン2: WHERE句最適化 -**Before**: 関数適用後のフィルタ -**After**: インデックス活用可能な形式 - -## パターン3: ウィンドウ関数活用 -**Before**: サブクエリの入れ子 -**After**: ROW_NUMBER(), RANK() -``` - -**優先度**: 🔴 **高** - データアナリストの頻繁なニーズ - ---- - -### Skill 2.2: Data Visualization Scripts -**name**: `data-analyst-visualization` -**description**: Generate data visualizations (charts, graphs, tables) from query results using Python/matplotlib or JavaScript. Use when creating reports or dashboards. Triggers: "visualize data", "create chart", "plot graph". - -**提供機能**: -- クエリ結果の可視化 -- チャート生成（棒グラフ、折れ線グラフ、円グラフ） -- HTMLレポート生成 -- 画像ファイル出力 - -**ディレクトリ構造**: -``` -skills/data-analyst-visualization/ -├── SKILL.md -├── scripts/ -│ ├── visualize.py -│ └── generate-html-report.js -└── templates/ - └── report-template.html -``` - -**allowed-tools**: Bash（Pythonスクリプト実行）, Write - -**スクリプト概要** (`visualize.py`): -```python -import pandas as pd -import matplotlib.pyplot as plt -import sys -import json - -# JSON形式のクエリ結果を読み込み -data = json.loads(sys.stdin.read()) -df = pd.DataFrame(data) - -# チャート生成 -df.plot(kind='bar', x='category', y='value') -plt.savefig('output.png') -``` - -**テンプレート概要** (`report-template.html`): -```html - - -Data Analysis Report - -

{{title}}

- - {{data_table}}
- - -``` - -**優先度**: 🟡 **中** - 有用だがPython環境依存 - ---- - -### Skill 2.3: Data Export Templates -**name**: `data-analyst-export` -**description**: Export query results to various formats (CSV, JSON, Excel, Markdown tables) with proper formatting and headers. Use when saving analysis results. Triggers: "export data", "save results", "output CSV/JSON/Excel". - -**提供機能**: -- CSV出力（カンマ区切り、ヘッダー付き） -- JSON出力（構造化、pretty-print） -- Excel出力（複数シート、書式設定） -- Markdownテーブル出力 - -**ディレクトリ構造**: -``` -skills/data-analyst-export/ -├── SKILL.md -└── scripts/ - ├── export-csv.js - ├── export-json.js - ├── export-excel.js - └── export-markdown.js -``` - -**allowed-tools**: Write, Bash - -**スクリプト概要** (`export-csv.js`): -```javascript -const fs = require('fs'); - -function exportToCSV(data, filename) { - const headers = Object.keys(data[0]).join(','); - const rows = data.map(row => Object.values(row).join(',')); - const csv = [headers, ...rows].join('\n'); - fs.writeFileSync(filename, csv); -} -``` - -**優先度**: 🔴 **高** - データアナリストの必須機能 - ---- - -## 3. corder agent 用 Skills - -### Skill 3.1: Code Generation Templates -**name**: `corder-code-templates` -**description**: Generate code templates for common patterns: REST API endpoints, React components, database models, authentication, error handling. Use when implementing new features. Triggers: "create API", "new component", "implement auth", "add model". - -**提供機能**: -- REST APIエンドポイントテンプレート -- Reactコンポーネントテンプレート -- データベースモデルテンプレート -- 認証ロジックテンプレート -- エラーハンドリングパターン - -**ディレクトリ構造**: -``` -skills/corder-code-templates/ -├── SKILL.md -├── templates/ -│ ├── rest-api-endpoint.js -│ ├── react-component.jsx -│ ├── database-model.js -│ ├── auth-middleware.js -│ └── error-handler.js -└── reference.md -``` - -**allowed-tools**: Read, Write, Bash - -**テンプレート概要** (`rest-api-endpoint.js`): -```javascript -// [ROUTE_NAME] API Endpoint -const express = require('express'); -const router = express.Router(); - -/** - * @route GET /api/[resource] - * @desc [Description] - * @access [Public/Private] - */ -router.get('/', async (req, res) => { - try { - // TODO: Implement logic - res.json({ success: true, data: [] }); - } catch (error) { - res.status(500).json({ success: false, error: error.message }); - } -}); - -module.exports = router; -``` - -**優先度**: 🔴 **高** - コーディング効率大幅向上 - ---- - -### Skill 3.2: Test Generation -**name**: `corder-test-generation` -**description**: Generate unit tests, integration tests, and test fixtures for code. Supports Jest, Mocha, pytest. Use when writing tests. Triggers: "generate tests", "create unit test", "add test coverage". - -**提供機能**: -- ユニットテスト生成（Jest、Mocha、pytest） -- 統合テスト生成 -- テストフィクスチャ生成 -- モック/スパイ設定 - -**ディレクトリ構造**: -``` -skills/corder-test-generation/ -├── SKILL.md -├── templates/ -│ ├── jest-unit-test.test.js -│ ├── mocha-test.test.js -│ ├── pytest-test.py -│ └── test-fixtures.json -└── scripts/ - └── generate-tests.js -``` - -**allowed-tools**: Read, Write, Bash - -**テンプレート概要** (`jest-unit-test.test.js`): -```javascript -const { [functionName] } = require('../[modulePath]'); - -describe('[functionName]', () => { - test('should [expected behavior]', () => { - // Arrange - const input = [testInput]; - const expected = [expectedOutput]; - - // Act - const result = [functionName](input); - - // Assert - expect(result).toEqual(expected); - }); - - test('should handle edge cases', () => { - // TODO: Add edge case tests - }); -}); -``` - -**スクリプト概要** (`generate-tests.js`): -- ソースコードを解析（Serena MCP使用） -- 関数シグネチャを抽出 -- テストケースのスケルトンを生成 -- エッジケースの提案 - -**優先度**: 🔴 **高** - テスト作成は頻繁で時間がかかる - ---- - -### Skill 3.3: Documentation Generator -**name**: `corder-doc-generation` -**description**: Generate API documentation, JSDoc comments, README sections, and inline code comments. Use when documenting code. Triggers: "generate docs", "add comments", "create API docs", "update README". - -**提供機能**: -- JSDoc/PyDocコメント生成 -- API仕様書生成 -- README.mdテンプレート -- インラインコメント提案 - -**ディレクトリ構造**: -``` -skills/corder-doc-generation/ -├── SKILL.md -├── templates/ -│ ├── jsdoc-template.js -│ ├── pydoc-template.py -│ ├── api-docs-template.md -│ └── readme-template.md -└── scripts/ - └── generate-docs.js -``` - -**allowed-tools**: Read, Write, Bash - -**テンプレート概要** (`jsdoc-template.js`): -```javascript -/** - * [Function description] - * - * @param {[type]} [paramName] - [parameter description] - * @returns {[returnType]} [return value description] - * @throws {[ErrorType]} [error condition] - * - * @example - * const result = functionName(param); - * // result: [expected output] - */ -function functionName(paramName) { - // Implementation -} -``` - -**優先度**: 🟡 **中** - 便利だが頻度は中程度 - ---- - -## 4. researcher agent 用 Skills - -### Skill 4.1: Research Report Templates -**name**: `researcher-report-templates` -**description**: Generate structured research reports with findings, comparisons, recommendations, and citations. Use when documenting investigation results. Triggers: "create report", "summarize findings", "compare technologies". - -**提供機能**: -- 調査レポートテンプレート -- 技術比較テーブル生成 -- ベストプラクティスまとめ -- 引用・参照リンク管理 - -**ディレクトリ構造**: -``` -skills/researcher-report-templates/ -├── SKILL.md -├── templates/ -│ ├── research-report-template.md -│ ├── tech-comparison-template.md -│ └── best-practices-template.md -└── scripts/ - └── generate-report.js -``` - -**allowed-tools**: Read, Write - -**テンプレート概要** (`research-report-template.md`): -```markdown -# [調査テーマ] 調査レポート - -## 概要 -- 調査目的: -- 調査期間: -- 情報源: - -## 調査結果 -### ポイント1 -- 説明 -- 詳細 -- 参照: [リンク] - -### ポイント2 -... - -## 技術比較 -| 項目 | 技術A | 技術B | 技術C | -|------|------|------|------| -| 特徴 | | | | -| 長所 | | | | -| 短所 | | | | - -## 推奨事項 -1. -2. - -## 参考リンク -- [タイトル](URL) -``` - -**優先度**: 🔴 **高** - Researcherの主要な成果物 - ---- - -### Skill 4.2: API Specification Extractor -**name**: `researcher-api-extractor` -**description**: Extract and document API specifications from documentation sites including endpoints, parameters, responses, authentication. Use when integrating external APIs. Triggers: "extract API spec", "document API", "analyze endpoints". - -**提供機能**: -- APIエンドポイント一覧抽出 -- パラメータ仕様抽出 -- レスポンス構造抽出 -- 認証方式ドキュメント - -**ディレクトリ構造**: -``` -skills/researcher-api-extractor/ -├── SKILL.md -├── templates/ -│ └── api-spec-template.md -└── scripts/ - └── extract-api-spec.js -``` - -**allowed-tools**: Read, Bash（WebFetch間接利用） - -**テンプレート概要** (`api-spec-template.md`): -```markdown -# [API Name] 仕様書 - -## ベースURL -`https://api.example.com/v1` - -## 認証 -- 方式: Bearer Token -- ヘッダー: `Authorization: Bearer {token}` - -## エンドポイント - -### GET /resource -**説明**: [説明] -**パラメータ**: -- `param1` (string, required): [説明] -- `param2` (number, optional): [説明] - -**レスポンス**: -```json -{ - "success": true, - "data": [] -} -``` - -**スクリプト概要** (`extract-api-spec.js`): -- WebFetchでAPIドキュメントを取得 -- Markdown/HTMLから構造化情報を抽出 -- テンプレートに整形して出力 - -**優先度**: 🟡 **中** - API統合時に便利 - ---- - -## 5. scanner agent 用 Skills - -### Skill 5.1: PDF Analysis -**name**: `scanner-pdf-analysis` -**description**: Analyze PDF documents with table extraction, section identification, and content summarization. Use when reading technical documents, reports, or papers. Triggers: "analyze PDF", "extract tables", "summarize document". - -**提供機能**: -- PDF構造解析 -- テーブル抽出とCSV変換 -- セクション識別 -- 重要ポイント要約 - -**ディレクトリ構造**: -``` -skills/scanner-pdf-analysis/ -├── SKILL.md -├── templates/ -│ └── pdf-summary-template.md -└── scripts/ - └── analyze-pdf.py -``` - -**allowed-tools**: Bash（Pythonスクリプト実行）, Write - -**スクリプト概要** (`analyze-pdf.py`): -```python -import PyPDF2 -import tabula -import sys - -def analyze_pdf(pdf_path): - # PDFテキスト抽出 - with open(pdf_path, 'rb') as f: - reader = PyPDF2.PdfReader(f) - text = ''.join([page.extract_text() for page in reader.pages]) - - # テーブル抽出 - tables = tabula.read_pdf(pdf_path, pages='all') - - # 構造化出力 - return { - 'text': text, - 'tables': tables, - 'page_count': len(reader.pages) - } -``` - -**テンプレート概要** (`pdf-summary-template.md`): -```markdown -# [ファイル名] 分析結果 - -## 概要 -- ページ数: X -- テーブル数: Y - -## 重要ポイント -1. -2. - -## 抽出テーブル -### テーブル1 -| 列1 | 列2 | -|-----|-----| -| ... | ... | -``` - -**優先度**: 🔴 **高** - PDFは頻繁に扱う - ---- - -### Skill 5.2: Excel Data Extraction -**name**: `scanner-excel-extraction` -**description**: Extract, transform, and structure data from Excel files including multiple sheets, formulas, and formatting. Use when processing Excel data. Triggers: "extract Excel data", "read spreadsheet", "convert Excel to JSON/CSV". - -**提供機能**: -- 複数シート読み込み -- データ構造化（JSON変換） -- CSV出力 -- 数式評価 - -**ディレクトリ構造**: -``` -skills/scanner-excel-extraction/ -├── SKILL.md -└── scripts/ - ├── extract-excel.py - └── convert-to-json.js -``` - -**allowed-tools**: Bash, Write - -**スクリプト概要** (`extract-excel.py`): -```python -import pandas as pd -import sys -import json - -def extract_excel(file_path): - # 全シート読み込み - excel_file = pd.ExcelFile(file_path) - data = {} - - for sheet_name in excel_file.sheet_names: - df = pd.read_excel(file_path, sheet_name=sheet_name) - data[sheet_name] = df.to_dict(orient='records') - - # JSON出力 - print(json.dumps(data, ensure_ascii=False, indent=2)) - -if __name__ == '__main__': - extract_excel(sys.argv[1]) -``` - -**優先度**: 🔴 **高** - Excelは頻繁に扱う - ---- - -## 6. qa agent 用 Skills - -### Skill 6.1: Code Review Checklist -**name**: `qa-code-review-checklist` -**description**: Comprehensive code review checklist covering readability, maintainability, performance, security, and best practices. Use when reviewing code. Triggers: "code review", "review checklist", "quality check". - -**提供機能**: -- コードレビューチェックリスト -- 言語別ベストプラクティス -- セキュリティチェック項目 -- パフォーマンスチェック項目 - -**ディレクトリ構造**: -``` -skills/qa-code-review-checklist/ -├── SKILL.md -├── checklists/ -│ ├── general-checklist.md -│ ├── javascript-checklist.md -│ ├── python-checklist.md -│ └── security-checklist.md -└── templates/ - └── review-report-template.md -``` - -**allowed-tools**: なし（参照のみ） - -**チェックリスト概要** (`general-checklist.md`): -```markdown -# コードレビューチェックリスト - -## 可読性 -- [ ] 変数名・関数名は明確か -- [ ] コメントは適切か -- [ ] ネストは深すぎないか - -## 保守性 -- [ ] DRY原則に従っているか -- [ ] 関数は単一責任か -- [ ] モジュール分割は適切か - -## パフォーマンス -- [ ] 不要なループはないか -- [ ] データ構造は適切か -- [ ] キャッシュを活用しているか - -## セキュリティ -- [ ] 入力値検証があるか -- [ ] SQLインジェクション対策があるか -- [ ] XSS対策があるか -``` - -**テンプレート概要** (`review-report-template.md`): -```markdown -# コードレビューレポート - [ファイル名] - -## サマリー -- レビュー日: -- レビュアー: -- 評価: ⭐⭐⭐⭐☆ - -## 問題点 -### 重大 🔴 -- [問題] - [行番号] - [修正案] - -### 警告 🟡 -- [問題] - [行番号] - [修正案] - -### 提案 🟢 -- [改善案] - -## 良い点 -- - -## 総評 - -``` - -**優先度**: 🔴 **高** - QAの主要機能 - ---- - -### Skill 6.2: Security Scan Templates -**name**: `qa-security-scan` -**description**: Security scanning templates and checklists for OWASP Top 10, authentication, authorization, data protection. Use when security testing. Triggers: "security scan", "vulnerability check", "OWASP". - -**提供機能**: -- OWASP Top 10チェックリスト -- 認証・認可検証 -- データ保護確認 -- セキュリティレポート生成 - -**ディレクトリ構造**: -``` -skills/qa-security-scan/ -├── SKILL.md -├── checklists/ -│ ├── owasp-top10-checklist.md -│ ├── auth-checklist.md -│ └── data-protection-checklist.md -└── templates/ - └── security-report-template.md -``` - -**allowed-tools**: なし（参照のみ） - -**チェックリスト概要** (`owasp-top10-checklist.md`): -```markdown -# OWASP Top 10 チェックリスト - -## 1. インジェクション -- [ ] SQLクエリはパラメータ化されているか -- [ ] コマンドインジェクション対策があるか -- [ ] LDAPインジェクション対策があるか - -## 2. 認証の不備 -- [ ] パスワードは安全にハッシュ化されているか -- [ ] セッション管理は適切か -- [ ] 多要素認証を実装しているか - -## 3. 機密データの露出 -- [ ] 通信は暗号化されているか（HTTPS） -- [ ] 機密データはログに出力されていないか -- [ ] APIキーは環境変数管理か -``` - -**優先度**: 🔴 **高** - セキュリティは最重要 - ---- - -### Skill 6.3: Performance Test Report -**name**: `qa-performance-test` -**description**: Generate performance test reports with Core Web Vitals, load times, bottleneck analysis, and optimization recommendations. Use when testing web applications. Triggers: "performance test", "load time", "Core Web Vitals". - -**提供機能**: -- Core Web Vitals測定レポート -- ページロード時間分析 -- ボトルネック特定 -- 最適化提案 - -**ディレクトリ構造**: -``` -skills/qa-performance-test/ -├── SKILL.md -├── templates/ -│ └── performance-report-template.md -└── scripts/ - └── analyze-performance.js -``` - -**allowed-tools**: Bash（Chrome DevTools MCP間接利用）, Write - -**テンプレート概要** (`performance-report-template.md`): -```markdown -# パフォーマンステストレポート - [URL] - -## Core Web Vitals -- **LCP** (Largest Contentful Paint): X.Xs - - 評価: [Good/Needs Improvement/Poor] -- **FID** (First Input Delay): Xms - - 評価: [Good/Needs Improvement/Poor] -- **CLS** (Cumulative Layout Shift): X.XX - - 評価: [Good/Needs Improvement/Poor] - -## ページロード時間 -- First Contentful Paint: X.Xs -- Time to Interactive: X.Xs -- Total Blocking Time: Xms - -## ボトルネック -1. [問題] - [影響度] - [改善案] -2. - -## 推奨改善策 -1. -2. -``` - -**スクリプト概要** (`analyze-performance.js`): -- Chrome DevTools MCPでパフォーマンス測定 -- Core Web Vitalsを抽出 -- ボトルネックを特定（Networkタイムライン解析） -- レポート生成 - -**優先度**: 🟡 **中** - Web開発時に有用 - ---- - -## 実装優先順位まとめ - -### 🔴 優先度高（即座に実装） -1. **director-project-planning** - プロジェクト計画書生成 -2. **data-analyst-sql-optimization** - SQL最適化パターン -3. **data-analyst-export** - データ出力テンプレート -4. **corder-code-templates** - コード生成テンプレート -5. **corder-test-generation** - テスト生成 -6. **researcher-report-templates** - 調査レポートテンプレート -7. **scanner-pdf-analysis** - PDF分析 -8. **scanner-excel-extraction** - Excel抽出 -9. **qa-code-review-checklist** - コードレビューチェックリスト -10. **qa-security-scan** - セキュリティスキャン - -### 🟡 優先度中（余裕があれば実装） -11. **director-github-integration** - GitHub統合 -12. **data-analyst-visualization** - データ可視化 -13. **corder-doc-generation** - ドキュメント生成 -14. **researcher-api-extractor** - API仕様抽出 -15. **qa-performance-test** - パフォーマンステスト - -### 🟢 優先度低（将来的に検討） -16. **director-progress-report** - 進捗レポート - ---- - -## 次のステップ - -1. **外部公開Skills調査結果の統合** - researcherからの結果を待つ -2. **スクリプト・テンプレート詳細設計** - 優先度高のSkillsから着手 -3. **実装** - corderエージェントに依頼 -4. **テスト** - 各Skillsの動作確認 -5. **ドキュメント更新** - plugin.json、README.md、CLAUDE.ndf.md - ---- - -**作成者**: director agent -**次回更新**: 外部Skills調査完了後、またはスクリプト詳細設計完了後 diff --git a/issues/old/i07.md b/issues/old/i07.md deleted file mode 100644 index d7fe00ba..00000000 --- a/issues/old/i07.md +++ /dev/null @@ -1,286 +0,0 @@ -# Task #3: Sub-AgentへのClaude Code Skills導入 - 設計計画書 - -**作成日**: 2025-12-15 -**担当**: director agent -**ステータス**: 🔄 分析・設計中 - ---- - -## プロジェクト概要 - -NDFプラグインの6つのsub-agent（director、data-analyst、corder、researcher、scanner、qa）にClaude Code Skillsを導入し、各エージェントの作業効率を最大化する。 - -**目標バージョン**: 1.1.1 → 1.2.0（MINOR: 新機能追加） - ---- - -## 調査完了: Claude Code Skills仕様 - -### Skills基本仕様 -- **Model-invoked**: Claudeが自律的に判断して呼び出す -- **必須ファイル**: `SKILL.md`（YAMLフロントマター + Markdown） -- **YAMLフロントマター**: - - `name`: スキル名（必須、小文字・数字・ハイフン、最大64文字） - - `description`: 説明（必須、最大1024文字、トリガー用語含む） - - `allowed-tools`: アクセス可能ツール制限（オプション） - -### ディレクトリ構造（推奨） -``` -skill-name/ -├── SKILL.md # 必須 -├── reference.md # オプション: 詳細ドキュメント -├── examples.md # オプション: 使用例 -├── scripts/ # オプション: スクリプト -│ └── helper.py -└── templates/ # オプション: テンプレート - └── template.txt -``` - -### plugin.jsonへの統合（推定） -```json -{ - "name": "ndf", - "version": "1.2.0", - "skills": [ - "./skills/skill-name-1", - "./skills/skill-name-2" - ] -} -``` - -### ベストプラクティス -- **焦点を絞る**: 1 Skill = 1機能 -- **明確な説明**: トリガー用語を含む具体的なdescription -- **Progressive Disclosure**: 必要な場合のみ支援ファイルを読み込む - ---- - -## 既存Sub-Agent分析 - -### 1. director - タスク統括・計画立案エージェント - -**専門領域**: -- タスク全体の統括、進捗管理 -- 情報収集と調査（Serena MCP活用） -- 計画立案と並列実行判断 -- 結果の統合と報告 - -**使用ツール**: -- Serena MCP（コード探索、メモリー管理） -- GitHub MCP（Issue/PR管理） -- 基本ツール（Read, Glob, Grep, Bash） - -**作業プロセス**: -1. 要求理解 → TodoList作成 -2. 情報収集（Serenaメモリー、コードベース構造） -3. 計画立案と並列実行判断 -4. サブエージェント特定とMain Agentへ報告 -5. 結果統合と報告 - -**Skillsで改善できる領域**: -- ✅ **計画書テンプレート自動生成** -- ✅ **GitHub Issue/PR作成の定型化** -- ✅ **並列実行判断チェックリスト** -- ✅ **進捗レポート生成** -- ✅ **サブエージェント連携パターン** - ---- - -### 2. data-analyst - データ分析・SQL専門エージェント - -**専門領域**: -- SQL生成と実行（BigQuery、DBHub） -- データ解釈と分析 -- データ出力（CSV、JSON、Excel） - -**使用ツール**: -- BigQuery MCP -- DBHub MCP - -**作業プロセス**: -1. 要件理解 -2. データ探索（スキーマ確認） -3. SQL設計 -4. 実行と検証 -5. 解釈と報告 -6. ファイル出力 - -**Skillsで改善できる領域**: -- ✅ **SQL最適化パターン** -- ✅ **データ可視化スクリプト** -- ✅ **CSV/JSON/Excel出力テンプレート** -- ✅ **データ品質チェック** -- ✅ **レポート生成テンプレート** - ---- - -### 3. corder - コーディング専門エージェント - -**専門領域**: -- コード設計と実装 -- コード品質保証（Codex MCP） -- コードベース理解（Serena MCP） -- 最新情報の活用（Context7 MCP） - -**使用ツール**: -- Codex CLI MCP -- Serena MCP -- Context7 MCP - -**作業プロセス**: -1. 要件理解 -2. コードベース調査（Serena） -3. 最新情報収集（Context7） -4. 設計 -5. 実装 -6. レビュー（Codex） -7. 改善 -8. テスト - -**Skillsで改善できる領域**: -- ✅ **コード生成テンプレート**（設計パターン別） -- ✅ **リファクタリングパターン** -- ✅ **テストコード生成** -- ✅ **ドキュメント自動生成** -- ✅ **セキュリティチェックリスト** - ---- - -### 4. researcher - 情報収集・調査専門エージェント - -**専門領域**: -- 技術ドキュメント調査（AWS Docs MCP） -- Webスクレイピング（WebFetch、Chrome DevTools MCP） -- コードベース調査（Codex MCP） -- 情報の統合と分析 - -**使用ツール**: -- WebFetch（優先、静的ページ） -- AWS Documentation MCP -- Chrome DevTools MCP（動的ページ） -- Codex CLI MCP - -**作業プロセス**: -1. 調査計画 -2. ツール選択 -3. 情報収集 -4. 情報整理 -5. 分析 -6. 報告 - -**Skillsで改善できる領域**: -- ✅ **調査レポートテンプレート** -- ✅ **ベストプラクティス収集パターン** -- ✅ **API仕様抽出スクリプト** -- ✅ **技術比較テーブル生成** -- ✅ **WebスクレイピングパターンLibrary** - ---- - -### 5. scanner - ファイル読み取り専門エージェント - -**専門領域**: -- PDF読み取り -- 画像読み取り（OCR） -- Officeファイル読み取り（PowerPoint、Excel、Word） -- データ変換と整理 - -**使用ツール**: -- Read tool（画像優先） -- Codex CLI MCP（PDF、Office） - -**作業プロセス**: -1. ファイル確認 -2. ツール選択 -3. 読み取り実行 -4. 内容抽出 -5. 構造化 -6. 報告 - -**Skillsで改善できる領域**: -- ✅ **PDF要約テンプレート** -- ✅ **OCR後処理スクリプト** -- ✅ **Excelデータ構造化** -- ✅ **PowerPointスライド要約** -- ✅ **ファイル形式変換ツール** - ---- - -### 6. qa - 品質保証・テスト専門エージェント - -**専門領域**: -- コード品質レビュー（Codex MCP） -- セキュリティ検証（OWASP Top 10） -- パフォーマンステスト（Chrome DevTools MCP） -- テストカバレッジ -- ドキュメント品質 -- Claude Codeプラグイン品質 - -**使用ツール**: -- WebFetch（静的ページ確認） -- Codex CLI MCP -- Serena MCP -- Chrome DevTools MCP -- Claude Code MCP - -**作業プロセス**: -1. スコープ確認 -2. ツール選択 -3. 静的分析（Codex） -4. 動的テスト（Chrome DevTools） -5. 構造分析（Serena） -6. ドキュメント検証（WebFetch） -7. レポート作成 -8. 修正支援 - -**Skillsで改善できる領域**: -- ✅ **コードレビューチェックリスト** -- ✅ **セキュリティスキャンテンプレート** -- ✅ **パフォーマンステストレポート** -- ✅ **テストカバレッジ分析** -- ✅ **品質レポート生成** - ---- - -## 次のステップ - -### タスク完了待ち -- ✅ Claude Code Skills公式仕様調査（researcher） -- 🔄 外部公開Skills調査（researcher）- 進行中 - -### 実施予定 -1. **Skills詳細設計** - director（このドキュメント作成後） -2. **スクリプト・テンプレート設計** - director -3. **Skills実装** - corder -4. **バージョン管理とドキュメント更新** - director - ---- - -## 成果物予定 - -### 新規ディレクトリ -``` -plugins/ndf/skills/ -├── director-planning/ -├── director-github-integration/ -├── data-analyst-sql-optimization/ -├── data-analyst-report-generation/ -├── corder-code-templates/ -├── corder-test-generation/ -├── researcher-report-templates/ -├── scanner-pdf-analysis/ -├── scanner-excel-extraction/ -├── qa-code-review-checklist/ -├── qa-security-scan/ -└── qa-performance-test/ -``` - -### 更新ファイル -- `plugins/ndf/.claude-plugin/plugin.json` - skills配列追加、バージョン1.2.0 -- `plugins/ndf/CLAUDE.ndf.md` - Skills使用方法追加 -- `plugins/ndf/README.md` - Skills説明追加 -- Serenaメモリー（plugin-ndf.md）更新 - ---- - -**次回更新**: Skills詳細設計完了後 diff --git a/issues/old/i08.md b/issues/old/i08.md deleted file mode 100644 index 8782f870..00000000 --- a/issues/old/i08.md +++ /dev/null @@ -1,64 +0,0 @@ -# 開発AIエージェント向け指示書 - -* このドキュメントはClaude Codeなどの開発AIエージェント向けの指示書です。 -* チャットで「docs/cmd01.mdのx番を実行してください」と言われたらこのファイルを読み、見出しに書いてある番号の内容を実行してください。 -* 頻繁に書き換わるので、指示があるたびに読み込みなおしてください。 -* 返答やドキュメントはすべて日本語で。 - -# 1. Markdown作成についてのSkill作成 -* Markdown文書作成時に読み込むSkillを作成して下さい -* 図を描くときはASCII ARTではなく、mermaidまたはplantUMLで記述すること - * mermaidまたはplantUMLは書きたい図の内容によってどちらにするか判断 - * ツリー構造の表現のみはasciiのままでよい -* Markdown文書は概ね300行以内とすること - * それ以上になる場合はディレクトリを作成して順序を示すprefixをつけてファイルを分割すること - * 順序prefixはパディング付き2桁(01-, 02-, ...) - -# 2. Affaan Mustafa Method導入 -* 以下の記事を読み、レポートをまとめてください - * https://github.com/affaan-m/everything-claude-code - * https://qiita.com/dai_chi/items/c19be47044d062d59ee8 - * https://zenn.dev/ttks/articles/a54c7520f827be -* affaan-mプラグインを作成し、導入すべき知見を導入してください - * ndfと併存する前提で構成してください - * これまでのskillやagentと重複する場合はaffaan-mを優先 - * ndfのskill、agentを整理・削除 - * カスタムコマンドとMCPが重複した場合はndf優先 -* 導入した知見をreport08.mdにまとめてください - -# 3. カスタムコマンド/pr-tests導入 ✅ 完了 - -## 実装内容 - -### 新規ファイル -- `plugins/ndf/commands/pr-tests.md`: Test Plan自動実行コマンド - -### 更新ファイル -- `plugins/ndf/.claude-plugin/plugin.json`: - - commands配列に`./commands/pr-tests.md`を追加 - - version: `2.2.2` → `2.3.0`（MINOR版アップ） -- `plugins/ndf/README.md`: - - 概要セクションでコマンド数を更新（6→7） - - `/pr-tests`コマンドの説明を追加 - -## 機能仕様 - -* `/ndf:pr-tests`コマンドの実装完了 -* PRを読み取ってTest Planを自動実行 - * ✅ 対象のPRを読み込む（引数またはブランチから自動検出） - * ✅ Test Planを解釈し、テスト実行計画を建てて実行する - * ✅ 結果をもとにPRコメントを編集する - * ✅ 成功したテストはチェックマークを付ける - * ✅ 失敗した場合は原因がコードであればコードを修正し、修正commitをpushし、コメントを追加する - * ✅ 失敗原因がコードで修正できない場合はPRにその旨のコメントを追加する - * ✅ 全てのテストが終ったらPRにテスト結果をまとめたコメントを追加する - -## バージョン更新 - -- **v2.2.2 → v2.3.0** (MINOR版アップ) -- 理由: 新機能追加（後方互換性あり） - -## 次のステップ - -- [ ] ローカルテストでコマンドが正常に動作することを確認 -- [ ] コミット・PR作成 diff --git a/issues/old/report01.md b/issues/old/report01.md deleted file mode 100644 index dd81c562..00000000 --- a/issues/old/report01.md +++ /dev/null @@ -1,210 +0,0 @@ -plugin 経由で MCP サーバを定義する場合は、**「プラグインの中に `.mcp.json` か `mcpServers` 設定を書く」**というのが公式のやり方です。 -公式 Plugins Reference をそのままかみ砕いて説明します。([Claude Code][1]) - ---- - -## 1. 全体像：プラグインと MCP サーバの関係 - -Claude Code のプラグインは - -* commands（スラッシュコマンド） -* agents（サブエージェント） -* skills -* hooks -* **MCP servers** - -を「1パッケージ」にまとめたものです。([Claude Code][1]) - -**MCP サーバをプラグインに束ねると**： - -* プラグインを有効にした時点で MCP サーバが自動起動される -* その MCP が提供するツールが Claude のツール一覧に出てくる -* 個々のユーザーが `.mcp.json` を手で配布しなくて済む（チーム配布が楽） - -というメリットがあります。([Claude Code][1]) - ---- - -## 2. プラグイン内での MCP サーバ定義の場所 - -公式リファレンスでは、MCP サーバ定義の場所は 2 パターンあります：([Claude Code][1]) - -1. **プラグイン直下の `.mcp.json` に書く** -2. `.claude-plugin/plugin.json` の `mcpServers` フィールドで - - * 直接オブジェクトとして書く - * もしくは `./mcp-config.json` など外部 JSON を参照させる - -標準構成はこんな感じです：([Claude Code][1]) - -```text -my-plugin/ -├── .claude-plugin/ -│ └── plugin.json # プラグインマニフェスト -├── commands/ -│ └── ... -├── agents/ -│ └── ... -├── hooks/ -│ └── hooks.json -├── skills/ -│ └── ... -├── .mcp.json # ← MCPサーバ定義（パターン1） -└── servers/ # MCP サーバ本体（バイナリ/スクリプトなど） - └── ... -``` - ---- - -## 3. `.mcp.json` で MCP サーバを定義する（基本パターン） - -`.mcp.json` のフォーマットは **「標準 MCP サーバ設定」**で、トップレベルに `mcpServers` オブジェクトを置きます。([Claude Code][1]) - -公式のサンプル（ほぼそのまま）： - -```jsonc -{ - "mcpServers": { - "plugin-database": { - "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", - "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"], - "env": { - "DB_PATH": "${CLAUDE_PLUGIN_ROOT}/data" - } - }, - "plugin-api-client": { - "command": "npx", - "args": ["@company/mcp-server", "--plugin-mode"], - "cwd": "${CLAUDE_PLUGIN_ROOT}" - } - } -} -``` - -各フィールドの意味は： - -* `mcpServers` - - * キー：Claude から見えるサーバ名（例: `"plugin-database"`） - * 値：その MCP サーバの起動方法 - -* `command` - - * 実行するコマンド。ローカルバイナリ・Node スクリプト・Python など何でも OK - * 例: `./servers/db-server`, `node`, `python`, `npx`など - -* `args`（任意） - - * コマンドライン引数。設定ファイルパスやモード指定など - -* `env`（任意） - - * 環境変数を指定 - * `${CLAUDE_PLUGIN_ROOT}` が使える（プラグインの実インストールディレクトリに展開される）([Claude Code][1]) - -* `cwd`（任意） - - * プロセスのカレントディレクトリ - -この `.mcp.json` を plugin ルートに置いておけば、プラグインが有効化されたときに MCP サーバが自動で起動し、Claude の「ツール」として認識されます。([Claude Code][1]) - ---- - -## 4. `plugin.json` に紐づける（パターン2） - -MCP 設定を **別ファイルに分けたい／インラインで書きたい**場合は、`.claude-plugin/plugin.json` の `mcpServers` フィールドを使います。([Claude Code][1]) - -### 4-1. 外部ファイル参照 - -`plugin.json`： - -```jsonc -{ - "name": "my-mcp-plugin", - "version": "1.0.0", - "description": "Plugin bundling custom MCP servers", - "mcpServers": "./mcp.json" // ここで外部JSONを参照 -} -``` - -`./mcp.json`（内容はさっきの `.mcp.json` と同じ形式）： - -```jsonc -{ - "mcpServers": { - "plugin-database": { - "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server" - } - } -} -``` - -### 4-2. 直接インラインで書く - -`plugin.json` にそのままオブジェクトを書くこともできます：([Claude Code][1]) - -```jsonc -{ - "name": "my-inline-mcp-plugin", - "version": "1.0.0", - "description": "Inline MCP config example", - "mcpServers": { - "plugin-database": { - "command": "${CLAUDE_PLUGIN_ROOT}/servers/db-server", - "args": ["--config", "${CLAUDE_PLUGIN_ROOT}/config.json"] - } - } -} -``` - -この場合、**別途 `.mcp.json` を置く必要はありません。** - ---- - -## 5. 実際に MCP サーバを動かすときの注意点 - -公式リファレンスに書いてあるポイントを、実務寄りにまとめると：([Claude Code][1]) - -1. **すべてのパスは plugin ルートからの相対パス or `${CLAUDE_PLUGIN_ROOT}` を使う** - - * 絶対パスは環境ごとに変わるので NG -2. **サーバ実行ファイルに実行権限を付ける** - - * Unixなら `chmod +x servers/db-server` -3. **MCP サーバは MCP プロトコル（JSON-RPC over stdio）で応答する必要がある** - - * ここは従来通りの MCP 実装ルール -4. **デバッグには `claude --debug` や `--mcp-debug` を使う** - - * プラグイン読み込みや MCP 起動エラーがログに出る -5. **プラグイン単位でユーザー・チームに配布できる** - - * `.mcp.json` や設定を手で配るより遥かに楽 - ---- - -## 6. ざっくり手順まとめ - -1. **プラグインの骨組みを作る** - - * `my-plugin/.claude-plugin/plugin.json` を作成 -2. **MCP サーバ本体を用意する** - - * `servers/` 以下に Node/Python/Go などで MCP サーバ実装 -3. **MCP 定義を書く** - - * `.mcp.json` か `plugin.json` の `mcpServers` にサーバ起動方法を記述 -4. **ローカルマーケットプレイス経由でインストール** - - * `marketplace.json` を用意して `/plugin marketplace add ./my-marketplace` - * `/plugin install my-plugin@my-marketplace` -5. Claude Code を再起動して、MCP サーバがツールとして見えているか確認 - ---- - -もしよければ次のステップとして： - -* BigQuery / Slack / GitHub など、**実際の社内ツール向け MCP サーバを束ねた plugin の「雛形リポジトリ」**を一緒に設計することもできます。 -* 例えば「kk-generation 用 /takeoff plugin」や「ナイル社内向け plugin」みたいな形で、marketplace + plugin 構成を具体的に書き起こすことも可能です。 - -[1]: https://code.claude.com/docs/en/plugins-reference "Plugins reference - Claude Code Docs" diff --git a/issues/old/report02.md b/issues/old/report02.md deleted file mode 100644 index a3ed0eec..00000000 --- a/issues/old/report02.md +++ /dev/null @@ -1,151 +0,0 @@ -結論： -**はい、あります。プラグイン側で「親エージェント向けのシステム指示書」を定義できます。 -ただし名前は *CLAUDE.md* ではなく、`agents/` ディレクトリに置く「エージェント定義ファイル」として提供します。** - -つまり、**プラグイン経由で “親エージェントの振る舞い” を決めることが可能**です。 - -以下、公式仕様に基づいて整理します。 - ---- - -# ✅ 結論：plugin で「親エージェントへの指示書」を定義できる - -Claude Code の plugin では、次のものをバンドルできます： - -* **サブエージェント（agents/）** -* **hooks** -* tools / MCP / commands -* skills -* etc. - -このうち **エージェント定義ファイル（= エージェントのシステムプロンプト）を plugin 側で持たせられる**ので、 -事実上 **「plugin 内に CLAUDE.md 相当の指示書」を同梱できます。** - ---- - -# 📌 仕組み：plugin の `agents/` ディレクトリに “親エージェント” を定義する - -プラグイン側では、次のような構造を取れます： - -``` -my-plugin/ - .claude-plugin/ - plugin.json - agents/ - main.md ← 親エージェント (CLAUDE.md 相当) - data-analyst.md ← サブエージェント - mcp.json - commands/ - hooks/ -``` - -`agents/main.md` の内容に、**親エージェントのシステムプロンプトを直接書けます**。 - -例： - -```markdown ---- -name: main -description: > - 親エージェント。BigQuery/dbhub のようなデータ取得タスクは - 必ず data-analyst サブエージェントに依頼する。 - 自分で MCP ツールは直接使用しないこと。 ---- - -あなたはプロジェクト全体の調整役として行動します。 - -# 禁止事項 -- BigQuery MCP を直接呼び出してはならない -- dbhub MCP を直接呼び出してはならない -- データ取得や SQL 実行はすべて data-analyst へ委譲すること - -# 指示 -- データ取得が必要な場合、「data-analyst を呼び出して ○○ を集計して」と明示する。 -- data-analyst から返ってきた要約のみを扱い、自分のコンテキストに生データを保持しない。 -``` - ---- - -# 📌 重要：plugin で定義したエージェントは「プロジェクトに自動追加」される - -公式ドキュメントの該当部分（Plugins → agents）では： - -* **plugin の agents/ 内に配置したエージェントは「そのプロジェクトで利用可能なエージェント」として追加される** -* name, description, tools, model が指定できる -* tools 範囲を制限できる（→ data-analyst だけ BigQuery MCP を持たせるのはこの仕組み） - -と説明されています。 - -つまり **plugin が “エージェント定義 + ルール” をプロジェクトに差し込む仕組み**があるわけです。 - ---- - -# 💡 実際にどうなるか？ - -### 👇 あなたの目的は： - -> 親エージェントから BigQuery/dbhub MCP を見えなくしたい -> （少なくとも、触らせないようにしたい） - -### Plugin 構成で実現できること： - -* data-analyst サブエージェント → tools に BigQuery/dbhub MCP を列挙 -* 親エージェント → tools に BigQuery/dbhub MCP を含めない -* 親エージェントの agent 定義（main.md）に - **「データ操作はすべて data-analyst に委譲する」**と明記 -* plugin インストール時にこの main.md を自動適用 - -→ **実質的に CLAUDE.md と同じことが plugin 内に含められる**。 - -これは Claude Code plugin の設計上、正式にサポートされている構成です。 - ---- - -# 📝 plugin.json の例 - -```jsonc -{ - "name": "team-data-workflow", - "version": "1.0.0", - "description": "データ分析専用サブエージェント付きワークフロープラグイン", - "agents": "./agents", - "mcpServers": "./mcp.json" -} -``` - -この構成なら、plugin を入れたプロジェクトでは： - -* 親エージェント（main） -* data-analyst - -が自動で追加され、 -「親には BigQuery MCP を触らせない」 -という規律が **plugin で一元管理**できます。 - ---- - -# 🎯 まとめ - -### ✔ plugin で CLAUDE.md と同等の「指示書」を定義できます - -→ それは `agents/main.md` という形で表現される - -### ✔ 親エージェント専用のプロンプトを書ける - -→ BigQuery/dbhub MCP に触らない規律を plugin が強制可能 - -### ✔ data-analyst には BigQuery/dbhub MCP ツールのみ付与 - -→ 親とサブで明確に役割分離できる - ---- - -# 📘 必要があれば… - -* あなたの plugin 構成（ファイル名や MCP の数）に合わせて - 　**完全な plugin テンプレ構成** - 　**main.md / data-analyst.md の最適化** - 　**tools のリストの正しい記載方法** - を一式生成できます。 - -ファイル構成を少し教えていただければ、すぐに最適解を組み上げます。 diff --git a/issues/old/report03.md b/issues/old/report03.md deleted file mode 100644 index 208e1bed..00000000 --- a/issues/old/report03.md +++ /dev/null @@ -1,249 +0,0 @@ -了解です。 -以下に **そのまま使える形**で、 - -1. **記憶戦略を運用するための Agent Skill（薄い・判断しない）** -2. **Serena MCP に置く「記憶戦略そのもの」の Memory（中期／長期）** - -を **別々の Markdown** として出力します。 - -> 設計意図 -> -> * **Skill**：記憶をどう扱うかの「行動ルール」だけ -> * **Serena Memory**：記憶戦略という「前提・思想・判断基準」そのもの - ---- - -# ① 記憶戦略用 Agent Skill（薄い skill） - -**用途** - -* Claude Code / Agent に常時持たせる -* 「記憶をどう使うか」を機械的に守らせる -* 判断はしない（判断は memory 側） - -**推奨配置** - -* `skills/memory_handling.md` -* または `CLAUDE.md` から参照される skill - ---- - -```md -# Skill: Memory Handling Strategy - -## Purpose -This skill defines **how the agent should handle memory**, -not **what should be remembered**. - -All decisions, principles, and project-specific rules must be retrieved -from Serena MCP memory. - ---- - -## Core Rules - -### 1. Skill must remain thin -- Do not store project-specific rules here -- Do not store decisions, reasons, or constraints -- This skill defines behavior only - ---- - -### 2. When to read memory -Before starting a task, check whether: -- the task depends on project-specific assumptions -- the task may conflict with past decisions -- the task requires architectural, legal, or organizational constraints - -If yes: -- list available Serena memories -- read only the relevant ones - ---- - -### 3. When to write memory -After completing a task, write to Serena memory if: -- a new decision was made -- an assumption was confirmed or invalidated -- a reusable insight emerged -- repeating this explanation later would be costly - ---- - -### 4. What NOT to write as memory -Do NOT store: -- step-by-step procedures -- implementation details -- temporary working notes -- raw logs or dumps - ---- - -### 5. Memory hygiene behavior -- Prefer updating existing memory over creating duplicates -- If a memory seems outdated, mark it for review -- Do not assume old memories are always valid - ---- - -## Interaction Pattern (Summary) - -1. Identify whether memory is needed -2. Read only relevant memories -3. Execute the task -4. Persist only durable knowledge back to memory - ---- - -## Guiding Principle - -> The agent acts. -> The memory decides. -``` - ---- - -# ② 記憶戦略そのもの（Serena MCP Memory） - -これは **Serena MCP に保存される「長期 memory」** です。 -Agent Skill から参照される前提知識になります。 - -**推奨配置** - -* `.serena/memories/memory-strategy.md` - ---- - -```md -# Memory Strategy for AI Agent -type: policy -confidence: high -project: global -expires: none - ---- - -## Purpose - -This memory defines **how mid-term and long-term memories are structured, -classified, and maintained** across projects. - -It is the single source of truth for deciding: -- what belongs in memory -- what belongs in skills -- how memories evolve over time - ---- - -## Memory Layer Definitions - -### Short-term Memory -- Exists only within a session -- Not persisted -- Used for immediate task context - ---- - -### Mid-term Memory -- Valid for weeks to months -- Represents temporary or revisitable decisions -- Must include a review date - -Typical contents: -- phase-specific decisions -- PoC constraints -- experimental results -- temporary architectural choices - -Required metadata: -- type: decision | assumption | experiment -- confidence: low | medium | high -- review_at: YYYY-MM-DD -- project: - ---- - -### Long-term Memory -- Stable across the project lifecycle -- Represents principles and non-negotiable constraints - -Typical contents: -- architectural principles -- legal / IP constraints -- organizational policies -- technology philosophy - -Required metadata: -- type: principle | constraint | policy -- confidence: high -- expires: none -- project: - ---- - -## Skill vs Memory Decision Checklist - -If any of the following are true, the information must be stored as memory: - -- it will be reused in future sessions -- it is project-specific -- it explains *why*, not *how* -- it restricts future choices -- it may need revision or expiration -- it would bloat an agent skill - -Otherwise, it belongs in a skill or remains transient. - ---- - -## Memory Granularity Rules - -- One memory entry = one decision or principle -- Do not mix facts, assumptions, and conclusions -- Prefer clarity over completeness -- Avoid embedding procedures - ---- - -## Memory Maintenance Policy - -- Mid-term memories must be reviewed at `review_at` -- Obsolete memories should be archived or deleted -- Long-term memories should rarely change and must be updated carefully - ---- - -## Anti-Patterns - -- Storing procedures in memory -- Encoding decisions inside skills -- Creating duplicate memories for similar topics -- Leaving experimental assumptions unreviewed - ---- - -## One-line Rule - -> Skills describe behavior. -> Memory defines reality. -``` - ---- - -## 最終整理（使い分け） - -| 項目 | Skill | Serena Memory | -| ----- | ----- | ------------- | -| 役割 | 行動ルール | 判断・前提 | -| 肥大化耐性 | 低 | 高 | -| 修正コスト | 高 | 低 | -| 時間軸 | 短期 | 中期・長期 | - ---- - -次のステップとしておすすめなのは： - -* 🔄 **中期 memory の自動レビュー運用** -* 🤖 **task 終了時に memory write を促すプロンプト設計** - -どこまで仕上げますか？ diff --git a/issues/old/report04.md b/issues/old/report04.md deleted file mode 100644 index 9e421025..00000000 --- a/issues/old/report04.md +++ /dev/null @@ -1,249 +0,0 @@ -了解です。Claude Code の **カスタムスラッシュコマンド**として、 - -1. **中期 memory の自動レビュー運用**（/mem-review） -2. **task 終了時に memory write を促す**（/mem-capture） - -を **そのまま置ける .md ファイル**で作ります。 - -> 仕様根拠：Claude Code は `.claude/commands/*.md` に Markdown を置くとスラッシュコマンド化でき、frontmatter で `allowed-tools` などを指定できます。([Claude Code][1]) -> また `disable-model-invocation: true` を使うと自動発火を抑制できます。([クラスメソッド発「やってみた」系技術メディア | DevelopersIO][2]) - ---- - -## 1) /mem-review（中期 memory の自動レビュー運用） - -**狙い** - -* `.serena/memories/` を走査して `review_at` 期限の来た中期記憶を検出 -* 期限超過/期限間近をまとめて提示 -* 1件ずつ「延長/長期化/アーカイブ/削除/更新」を提案し、必要ならファイルを編集 - -> Serena の memory が `.serena/memories/` に置かれる運用は一般に定着しています（Serena workflow/usage系の情報）。([クラスメソッド発「やってみた」系技術メディア | DevelopersIO][3]) -> ※あなたの環境でパスが違う場合は、コマンド内の `MEM_DIR` を変更してください。 - -**保存先**：`.claude/commands/mem-review.md` - -```md ---- -description: "中期Serena memory（review_at付き）を自動検出してレビューする" -argument-hint: "[--days N] [--dir PATH] 例: /mem-review --days 14" -allowed-tools: Bash(date:*), Bash(find:*), Bash(rg:*), Bash(ls:*), Bash(pwd:*), Read, Write -disable-model-invocation: true ---- - -あなたは「中期/長期の記憶戦略」を運用するエージェントです。 -このコマンドは `.serena/memories/` の **中期 memory**（`review_at` を持つもの）をレビューします。 - -# 入力 -$ARGUMENTS - -# 期待するmemory形式（例） -先頭付近に以下のようなメタ情報がある（YAMLでなくても "key: value" を本文に含めば可）: -- type: decision | assumption | experiment -- review_at: YYYY-MM-DD -- confidence: low | medium | high -- project: - -# 実行手順 - -## 0) パラメータ解釈 -- --days N : 「期限間近」とみなす日数（デフォルト14日） -- --dir PATH : memoryディレクトリ（デフォルト `.serena/memories`） - -まず Bash で今日の日付（YYYY-MM-DD）を取得する: -- `date +%F` - -次に、対象ディレクトリを決定する（存在確認も行う）。 - -## 1) 期限超過・期限間近の抽出 -Bash で以下を行う: -1. memoryファイル一覧を取得（*.md想定） -2. 各ファイルから `review_at: YYYY-MM-DD` を抽出 -3. 今日の日付と比較して: - - overdue: review_at < today - - due_soon: today <= review_at <= today + N日 -4. 結果を「overdue」「due_soon」に分けてリストアップ - -比較は Bash で `date -d` が使えない環境があるので、**ISO日付の文字列比較**を基本とする。 -（YYYY-MM-DDなら辞書順で比較可能） - -## 2) レポート表示（必須） -以下を必ず出力: -- 今日の日付 -- 設定（dir, days） -- overdue一覧（ファイル名・review_at・type・project・冒頭1〜2行の要約） -- due_soon一覧（同上） - -要約のために必要なファイルだけ Read する。 - -## 3) 1件ずつレビュー処理 -各対象memoryについて、次の選択肢を提示し、ユーザーが指示しなくても「推奨」を1つ示す: -A. 延長（review_at を未来に更新） -B. 長期化（type=principle/constraint/policyへ移行、expires: none 付与、review_at削除） -C. 更新（内容修正 + review_at更新） -D. アーカイブ（ファイル末尾に `status: archived` を追記、または `ARCHIVE/` に移動） -E. 削除 - -ユーザーが指示しない場合は、以下で自動推奨: -- 実験結果が確定して「原則」になっている → B -- まだ暫定だが有効 → A -- 内容が古い/前提が変わった → C or D -- 明らかに不要 → E - -編集が必要なら Write でファイルを更新する。 - -## 4) 変更サマリ -最後に、実行した変更を一覧で出力: -- 更新したファイル -- 変更内容（review_at変更/長期化/アーカイブ/削除） -- 次回のレビュー推奨日 - -# 注意 -- このコマンド自体は「記憶戦略の運用」だけを行う。 -- 新しい意思決定を作るのは /mem-capture に誘導する。 -``` - ---- - -## 2) /mem-capture（task終了時の memory write を促す） - -**狙い** - -* タスク完了後に、**記憶化すべきものだけ**を短いフォームで回収 -* 既存memoryに追記 or 新規作成 -* 中期なら `review_at` をデフォルトで **60日後**（変更可） -* 長期化フラグ（`--long`）で principle/constraint/policy として保存 - -**保存先**：`.claude/commands/mem-capture.md` - -```md ---- -description: "タスク終了時に、再利用価値のある知見をSerena memoryとして保存する" -argument-hint: "[--project NAME] [--type decision|assumption|experiment|principle|constraint|policy] [--review-at YYYY-MM-DD] [--long] [--append FILE]" -allowed-tools: Bash(date:*), Bash(pwd:*), Bash(ls:*), Bash(mkdir:*), Bash(test:*), Read, Write -disable-model-invocation: true ---- - -あなたは「中期/長期の記憶戦略」を運用するエージェントです。 -このコマンドは **タスク終了時**に、記憶化すべき内容をフォームで回収し、 -`.serena/memories/` に保存します。 - -# 入力 -$ARGUMENTS - -# 目標 -- Skillを肥大化させないため、判断・前提・制約は memory に保存する -- ただし「手順」「実装詳細」は保存しない - -# 手順 - -## 0) デフォルト設定 -- memory dir: `.serena/memories` -- 今日: `date +%F` -- デフォルト review_at: 今日 + 60日（Bashで日付計算できない環境があるので、ユーザーに日付入力を促しても良い） - -## 1) まずユーザーにフォームで回答してもらう（必須） -以下をそのまま提示し、ユーザーの入力を待たずに「推奨の埋め方」も例示してよいが、最終的にはユーザー入力を使う。 - -### Memory Capture Form -1. project: (例 carloc / mdx / global) -2. type: (decision / assumption / experiment / principle / constraint / policy) -3. confidence: (low / medium / high) -4. title: (短いタイトル) -5. context: (何が起きた？ 1-2文) -6. decision_or_fact: (確定事項を1-3点) -7. why: (理由があれば1-2文) -8. next_action: (必要なら) -9. review_at: (中期のみ YYYY-MM-DD, 長期は none) -10. related_files: (任意。パスやPR番号など) - -## 2) 保存先の決定 -- `--append FILE` があれば、そのファイルを Read して追記する -- それ以外は新規作成: - - ファイル名: `{today}-{project}-{slug(title)}.md` - - 保存先: `.serena/memories/` - -必要なら mkdir を Bash で実行。 - -## 3) 出力フォーマット -新規作成の場合、以下のテンプレを使う（内容はフォームから埋める）: - ---- -# -type: <type> -confidence: <confidence> -project: <project> -review_at: <YYYY-MM-DD or none> -created_at: <today> -status: active ---- - -## Context -<context> - -## Decision / Facts -- <decision_or_fact 1> -- <decision_or_fact 2> - -## Why -<why> - -## Next action -<next_action> - -## Related -- <related_files> - -## Notes -- This memory intentionally excludes procedures and implementation details. - -## 4) 中期→長期化の自動提案 -- type が decision/assumption/experiment でも、内容が「不変の原則」なら - 長期化（principle/constraint/policy）を提案する -- `--long` 指定があれば review_at は none にする - -## 5) 完了サマリ -保存/追記したファイルパスを必ず表示し、次の推奨コマンドを提示: -- 次回レビュー: `/mem-review` -``` - ---- - -## 置き方（最小） - -```bash -mkdir -p .claude/commands -# 上の2ファイルをそれぞれ .claude/commands/mem-review.md と mem-capture.md に保存 -``` - ---- - -## 使い方例 - -* 期限チェック（14日以内を「間近」扱い） - - * `/mem-review --days 14` - -* タスク完了の記憶化（中期） - - * `/mem-capture --project carloc --type decision --review-at 2026-04-01` - -* 長期化（原則として保存） - - * `/mem-capture --project global --type principle --long` - ---- - -## 追加で「より自動」にしたい場合（選択肢） - -Claude Code 側だけで“完全自動（フック）”は難しいことが多いので、実務的には - -* PR作成前に `/mem-capture` -* 週1で `/mem-review` - が堅いです。 - -もし「Git hook / CI で週次レビューを半自動化」までやりたいなら、あなたの運用（GitHub Actions有無、CI権限）に合わせて *hook/ジョブ* 版も作れます。 - -[1]: https://code.claude.com/docs/ja/slash-commands?utm_source=chatgpt.com "スラッシュコマンド - Claude Code Docs" -[2]: https://dev.classmethod.jp/en/articles/disable-model-invocation-claude-code/?utm_source=chatgpt.com "For skills that are only executed manually (slash commands), I ..." -[3]: https://dev.classmethod.jp/articles/20250806-tuning-project-configuration-for-serena-efficiency/?utm_source=chatgpt.com "プロジェクト構成をSerena効率化に向けたチューニング" diff --git a/issues/old/report05.md b/issues/old/report05.md deleted file mode 100644 index 3bbf19e3..00000000 --- a/issues/old/report05.md +++ /dev/null @@ -1,184 +0,0 @@ -いいテーマですね。 -結論から言うと **「Claude Code の agent skills」と「Serena MCP」は役割がかなり違う**ので、**競合ではなくレイヤー分離**で考えるのが一番スッキリします。 - ---- - -## 全体像（まずここを押さえる） - -ざっくり役割を一言で言うと👇 - -| 要素 | 役割 | -| ---------------------------- | --------------------------- | -| **Claude Code agent skills** | **その場の作業をどう実行するか（振る舞い・手順）** | -| **Serena MCP** | **外部知能（記憶・検索・構造化知識）へのI/O** | -| **Serena memory** | **人間やプロジェクトの「長期的な文脈」を保持** | - -つまり -👉 *skill = 行動の型* -👉 *memory = 記憶の層* -👉 *MCP = それをLLMに接続する配線* - ---- - -## Claude Code の agent skills とは何か - -Claude Code の skill は基本的に： - -* **タスク実行向け** -* **短期コンテキスト前提** -* **「今このリポジトリで何をするか」寄り** - -### 向いていること - -* リファクタリング手順 -* テスト生成フロー -* PR作成ルール -* エラーログ解析 → 修正 -* 「このコードベースではこう直す」という即時判断 - -### 向いていないこと - -* プロジェクト横断の知識蓄積 -* 半年前の設計思想を覚えておく -* 人・組織・方針レベルの記憶 - -👉 **stateless（毎回忘れてOK）な作業ロジック**が得意。 - ---- - -## Serena MCP の位置づけ（ここが重要） - -Serena MCP は **「Claudeに外付けの脳を与える」仕組み**です。 - -* MCP = Model Context Protocol -* LLMの外にある： - - * memory - * knowledge - * vector store - * structured notes - を **安定して参照できる** - -つまり **Claude Code が毎回ゼロから考えなくて済む**。 - ---- - -## Serena memory と skill の決定的な違い - -### ① 時間軸が違う - -| 観点 | Skill | Serena memory | -| ---- | ------- | ------------- | -| 有効期間 | そのセッション | 週〜年 | -| 再利用 | 限定的 | 非常に高い | -| 前提 | 今回のタスク | 人・プロジェクトの履歴 | - -### ② 記憶の粒度が違う - -**skill** - -```text -「TypeScriptの型は厳密に」 -「diffは最小化」 -``` - -**serena memory** - -```text -このプロジェクトでは -- BigQueryに日本語カラム名を使う -- ETLは冪等性必須 -- 推論モデルはLightGBM優先 -``` - -👉 skillは「やり方」 -👉 memoryは「前提条件」 - ---- - -## 「Serena memory は不要？」への正直な答え - -### ❌ 不要なケース - -以下に全部当てはまるなら **不要**です： - -* 単発のコード生成しかしない -* 毎回別プロジェクト -* 設計思想をAIに覚えさせる気がない -* 「その場で動けばOK」 - -→ Claude Code + skills だけで十分 - ---- - -### ✅ 圧倒的に効くケース（あなたはここ） - -あなたの過去の使い方を見る限り👇 - -* 複数プロダクト横断（カルモ、カーロケ、査定AI…） -* 技術選定の思想が一貫している -* 法務・IP・業務制約が多い -* 「また同じ説明をAIにさせたくない」 - -**これは Serena memory が一番効くタイプです。** - ---- - -## おすすめの使い分けパターン（実践編） - -### レイヤー構成（鉄板） - -``` -[ Serena memory ] - - 技術思想 - - 事業背景 - - 過去の意思決定 - - NG集 - - ↓ 参照 - -[ Claude Code agent skills ] - - 実装 - - 修正 - - 解析 - - 出力整形 -``` - -### 具体例 - -#### Serena memory に入れるべきもの - -* 「中古車価格推定は説明可能性必須」 -* 「BigQueryはCDC前提」 -* 「PoCではGPU使わない」 -* 「IP的に○○方式は避ける」 - -#### skill に書くべきもの - -* 「LightGBMの学習コードを生成」 -* 「Dockerfileを最適化」 -* 「PRテンプレに沿ってdiff作成」 - ---- - -## 「Serena memory は skill で代替できる？」問題 - -技術的には **一部は可能**ですが： - -* skillは肥大化する -* 毎回ロードされてコスト増 -* 文脈の優先順位制御が難しい - -👉 **長期記憶を skill に押し込むのはアンチパターン**です。 - ---- - -## 最終まとめ（判断基準） - -* **短期・作業手順** → Claude Code skills -* **長期・前提・思想** → Serena memory -* **不要か？** → - - * 趣味開発：不要 - * 事業開発・組織開発：**必須級** - diff --git a/issues/old/report08.md b/issues/old/report08.md deleted file mode 100644 index 2ce70ebd..00000000 --- a/issues/old/report08.md +++ /dev/null @@ -1,788 +0,0 @@ -# Claude Code ベストプラクティス調査レポート - -## 調査日時 -2026-01-30 - -## 調査対象記事 -1. [everything-claude-code](https://github.com/affaan-m/everything-claude-code) - Anthropicハッカソン優勝者による本番環境対応設定集 -2. [Claude Code 実践ガイド (Qiita)](https://qiita.com/dai_chi/items/c19be47044d062d59ee8) -3. [Claude Code 実装パターン (Zenn)](https://zenn.dev/ttks/articles/a54c7520f827be) - ---- - -## 📊 各記事の要約 - -### 1. everything-claude-code (GitHub) - -**概要**: 10ヶ月以上の実戦使用から生まれた本番環境対応の設定集 - -**主要コンポーネント**: -- **エージェント**: 専門化された部分タスク実行（例: code-reviewer, tdd-guide） -- **スキル**: 再利用可能なワークフロー定義（TDD実装、バックエンド設計パターン等） -- **ルール**: 常時適用される指針（セキュリティチェック、コーディング規約、テスト要件） -- **ホック**: ツール実行時に自動発火する処理（console.log検出警告等） - -**重要な発見**: -- ⚠️ **コンテキスト窓の縮小問題**: MCPツール有効化により200k→70kへ縮小する可能性 -- 推奨設定: MCP設定時20～30個、プロジェクト単位で10個以下、アクティブツール80未満 -- パッケージマネージャー自動検出機構（npm/pnpm/yarn/bun） -- 継続学習システム（instinct-based learning with confidence scoring） - -**実装パターン**: -- TDDワークフロー: インターフェース定義→RED→GREEN→リファクタリング→カバレッジ検証 -- 検証ループ: チェックポイント vs 継続評価の使い分け -- クロスプラットフォーム対応（Windows/macOS/Linux） -- GitHub App ベースのスキル自動生成機能 - -### 2. Claude Code 実践ガイド (Qiita) - -**概要**: 5つの中核原則による効率的な設定管理 - -**5つの中核原則**: -1. **段階的改善** - 完璧性より実用性を優先 -2. **コンテキスト効率化** - ツール過剰問題を回避、未使用MCPを無効化 -3. **並列実行活用** - `/fork`コマンドとgit worktreesの使い分け -4. **定型作業自動化** - Hooksで繰り返し作業を排除 -5. **エージェントスコープ制限** - Subagentに限定ツールのみ許可 - -**実装レベルのテクニック**: - -| Hooks設定例 | 用途 | -|------------|------| -| Prettier自動フォーマット | PostToolUse時の整形 | -| console.log検出警告 | 2段階チェック | -| TypeScript型チェック | 自動実行 | -| tmux使用促進 | PreToolUse時 | - -**並列ワークフロー判断基準**: -- 異なるファイル群 → `/fork`（軽量） -- 同一ファイル編集可能性 → git worktrees（競合防止） - -**コンテキスト管理ルール**: -- MCP設定数: 20-30個以内 -- プロジェクト有効化: 10個以下 -- 総ツール数: 80個以下維持 -- `/status`で監視、50-60%で`/compact`実行 - -### 3. Claude Code 実装パターン (Zenn) - -**概要**: 4つの基本原則に基づく実証済みアプローチ - -**4つの基本原則**: -1. **エージェント分業制**: 専門エージェントに必要最小限のツール(5個程度)を配置 -2. **TDD中心ワークフロー**: RED→GREEN→REFACTORサイクル、80%以上カバレッジ必須 -3. **セキュリティファースト**: コミット前の脆弱性、入力検証、シークレット混入チェック -4. **コンテキスト管理**: MCPは20～30個設定、プロジェクト単位で10個以下を有効化 - -**実装パターン**: -- **agents/**: planner.md、architect.md、tdd-guide.md、code-reviewer.md、security-reviewer.md等 -- **commands/**: `/tdd`、`/plan`、`/code-review`、`/build-fix`等のスラッシュコマンド -- **rules/**: モジュラーに分割されたルールファイル（セキュリティ、コーディング規格、テスト要件） -- **hooks/**: PostToolUse時の自動フォーマット、console.log検出等 - -**重要な実績データ**: -- MCPサーバー有効化で200k→70kへコンテキスト減少 -- ツール数80個以下制限と選別が重要 - ---- - -## 🎯 affaan-mプラグインとして実装すべき機能 - -### 前提: NDFプラグインとの併用 - -**NDFプラグインの役割（既存）**: -- MCP統合（6個のMCPサーバー） -- ワークフローコマンド（6個のスラッシュコマンド） -- 専門エージェント（6個のサブエージェント） -- スキル（8個のClaude Code Skills） - -**affaan-mプラグインの役割（新規）**: -- コンテキスト管理 -- 品質保証機能 -- TDDワークフロー -- セキュリティチェック -- 開発効率化機能 - -### Phase 1: 基盤整備（v1.0.0） - -#### 1. コンテキスト管理機能 - -**問題**: MCPツール有効化により200k→70kへコンテキストが大幅縮小 - -**実装機能**: -- コンテキスト監視コマンド: `/context-status` -- 自動コンパクト化: 60%閾値で`/compact`実行 -- MCP数警告: 10個超過時に警告表示 -- ツール数監視: 80個以下を推奨 - -**実装場所**: -``` -plugins/affaan-m/ -├── commands/ -│ └── context-status.md # コンテキスト監視コマンド -├── hooks/ -│ └── context-monitor.js # 自動監視フック -└── docs/ - └── context-management.md # コンテキスト管理ガイド -``` - -#### 2. Hooksシステム - -**実装するHooks**: - -| Hook タイプ | 機能 | 優先度 | -|-----------|------|--------| -| PostToolUse | 自動フォーマット（Prettier/ESLint） | 高 | -| PostToolUse | console.log/debugger検出警告 | 高 | -| PostToolUse | TypeScript型チェック自動実行 | 中 | -| PreCommit | シークレット混入チェック | 高 | -| PreCommit | テストカバレッジ検証（80%以上） | 中 | -| PreToolUse | tmux使用促進、環境チェック | 低 | - -**実装場所**: -``` -plugins/affaan-m/ -├── hooks/ -│ ├── hooks.json # Hooks定義 -│ ├── auto-format.js # 自動フォーマット -│ ├── detect-console-log.js # console.log検出 -│ ├── typescript-check.js # TypeScript型チェック -│ ├── secret-scan.js # シークレット混入チェック -│ └── coverage-check.js # カバレッジ検証 -└── docs/ - └── hooks-guide.md # Hooks設定ガイド -``` - -#### 3. TDDワークフローコマンド - -**5段階TDDプロセス**: -1. インターフェース定義 -2. RED（失敗テスト作成） -3. GREEN（最小実装） -4. リファクタリング -5. カバレッジ検証（80%以上） - -**実装コマンド**: -- `/tdd` - TDDワークフロー開始 -- `/tdd-red` - 失敗テスト作成 -- `/tdd-green` - 最小実装 -- `/tdd-refactor` - リファクタリング -- `/tdd-coverage` - カバレッジ検証 - -**実装場所**: -``` -plugins/affaan-m/ -├── commands/ -│ ├── tdd.md # TDDワークフローコマンド -│ ├── tdd-red.md # REDフェーズ -│ ├── tdd-green.md # GREENフェーズ -│ ├── tdd-refactor.md # リファクタリング -│ └── tdd-coverage.md # カバレッジ検証 -├── skills/ -│ └── tdd-workflow/ -│ └── SKILL.md # TDDワークフロースキル -└── docs/ - └── tdd-guide.md # TDDガイド -``` - -#### 4. セキュリティチェック機能 - -**実装機能**: -- OWASP Top 10チェックリスト -- シークレット混入検出 -- 入力検証パターン -- セキュリティレビューコマンド - -**実装コマンド**: -- `/security-scan` - セキュリティスキャン -- `/owasp-check` - OWASP Top 10チェック - -**実装場所**: -``` -plugins/affaan-m/ -├── commands/ -│ ├── security-scan.md # セキュリティスキャン -│ └── owasp-check.md # OWASP Top 10チェック -├── skills/ -│ └── security-review/ -│ └── SKILL.md # セキュリティレビュースキル -└── docs/ - └── security-guide.md # セキュリティガイド -``` - -#### 5. パッケージマネージャー自動検出 - -**検出順序**: -1. 環境変数チェック -2. プロジェクト設定ファイル -3. lockファイル検出（package-lock.json, pnpm-lock.yaml, yarn.lock, bun.lockb） - -**実装場所**: -``` -plugins/affaan-m/ -├── hooks/ -│ └── detect-package-manager.js # パッケージマネージャー検出 -└── docs/ - └── package-manager-guide.md # パッケージマネージャーガイド -``` - ---- - -## 🔄 NDFプラグインとの役割分担 - -### NDFプラグイン（既存） - -**役割**: MCP統合、ワークフロー、専門エージェント - -| カテゴリ | 機能 | -|---------|------| -| **MCP統合** | Codex CLI, BigQuery, AWS Docs, Chrome DevTools等（6個） | -| **ワークフローコマンド** | `/commit`, `/review-pr`, `/slack-notify`等（6個） | -| **専門エージェント** | director, corder, data-analyst, researcher, scanner, qa（6個） | -| **スキル** | データ分析、コード生成、リサーチ等（8個） | - -### affaan-mプラグイン（新規） - -**役割**: コンテキスト管理、品質保証、TDDワークフロー - -| カテゴリ | 機能 | -|---------|------| -| **コンテキスト管理** | `/context-status`、自動コンパクト化、MCP数監視 | -| **品質保証** | Hooks（自動フォーマット、console.log検出、型チェック） | -| **TDDワークフロー** | `/tdd`関連コマンド、TDDスキル | -| **セキュリティ** | `/security-scan`、`/owasp-check`、シークレット検出 | -| **開発効率化** | パッケージマネージャー自動検出 | - -### 併用シナリオ - -**シナリオ1: コーディング作業** -1. NDFプラグイン: `ndf:corder`エージェントでコード実装 -2. affaan-mプラグイン: PostToolUse Hooksで自動フォーマット、型チェック -3. affaan-mプラグイン: `/tdd`コマンドでテスト駆動開発 - -**シナリオ2: セキュリティレビュー** -1. NDFプラグイン: `ndf:qa`エージェントでコード品質レビュー -2. affaan-mプラグイン: `/security-scan`で脆弱性チェック -3. affaan-mプラグイン: PreCommit Hooksでシークレット混入検出 - -**シナリオ3: コンテキスト管理** -1. affaan-mプラグイン: `/context-status`でコンテキスト使用率確認 -2. affaan-mプラグイン: 60%超過時に自動コンパクト化 -3. NDFプラグイン: MCP統合を継続（affaan-mが監視） - ---- - -## 📦 affaan-mプラグインの初期構成案 - -### ディレクトリ構造 - -``` -plugins/affaan-m/ -├── .claude-plugin/ -│ └── plugin.json # プラグインメタデータ -├── commands/ -│ ├── context-status.md # コンテキスト監視 -│ ├── tdd.md # TDDワークフロー -│ ├── tdd-red.md # REDフェーズ -│ ├── tdd-green.md # GREENフェーズ -│ ├── tdd-refactor.md # リファクタリング -│ ├── tdd-coverage.md # カバレッジ検証 -│ ├── security-scan.md # セキュリティスキャン -│ └── owasp-check.md # OWASP Top 10チェック -├── hooks/ -│ ├── hooks.json # Hooks定義 -│ ├── context-monitor.js # コンテキスト監視 -│ ├── auto-format.js # 自動フォーマット -│ ├── detect-console-log.js # console.log検出 -│ ├── typescript-check.js # TypeScript型チェック -│ ├── secret-scan.js # シークレット混入チェック -│ ├── coverage-check.js # カバレッジ検証 -│ └── detect-package-manager.js # パッケージマネージャー検出 -├── skills/ -│ ├── tdd-workflow/ -│ │ └── SKILL.md # TDDワークフロースキル -│ └── security-review/ -│ └── SKILL.md # セキュリティレビュースキル -├── docs/ -│ ├── context-management.md # コンテキスト管理ガイド -│ ├── hooks-guide.md # Hooks設定ガイド -│ ├── tdd-guide.md # TDDガイド -│ ├── security-guide.md # セキュリティガイド -│ └── package-manager-guide.md # パッケージマネージャーガイド -├── README.md # プラグイン説明 -└── CHANGELOG.md # 変更履歴 -``` - -### plugin.json - -```json -{ - "name": "affaan-m", - "version": "1.0.0", - "description": "コンテキスト管理、品質保証、TDDワークフローを提供するClaude Codeプラグイン（NDFプラグイン併用前提）", - "author": { - "name": "takemi-ohama", - "url": "https://github.com/takemi-ohama" - }, - "keywords": [ - "context-management", - "quality-assurance", - "tdd", - "security", - "hooks", - "productivity" - ], - "commands": [ - "./commands/context-status.md", - "./commands/tdd.md", - "./commands/tdd-red.md", - "./commands/tdd-green.md", - "./commands/tdd-refactor.md", - "./commands/tdd-coverage.md", - "./commands/security-scan.md", - "./commands/owasp-check.md" - ], - "skills": [ - "./skills/tdd-workflow", - "./skills/security-review" - ], - "hooks": "./hooks/hooks.json", - "dependencies": { - "ndf": "^2.1.0" - }, - "config": { - "contextMonitoring": { - "enabled": true, - "threshold": 60, - "autoCompact": true - }, - "hooks": { - "autoFormat": true, - "consoleLogDetection": true, - "typescriptCheck": true, - "secretScan": true, - "coverageCheck": true - }, - "tdd": { - "coverageThreshold": 80, - "enforceRedGreenRefactor": true - }, - "security": { - "owaspCheck": true, - "secretPatterns": [ - "AWS_ACCESS_KEY_ID", - "AWS_SECRET_ACCESS_KEY", - "GITHUB_TOKEN", - "SLACK_TOKEN" - ] - } - } -} -``` - ---- - -## 📋 導入ロードマップ - -### Phase 1: 基盤整備（v1.0.0）【優先度: 高】 - -**目標**: コンテキスト管理、基本Hooks、TDDワークフロー - -**実装内容**: -- [ ] プラグイン基盤構築（plugin.json、ディレクトリ構造） -- [ ] コンテキスト管理機能（`/context-status`、自動コンパクト化） -- [ ] 基本Hooks（auto-format, secret-scan, console.log検出） -- [ ] TDDワークフローコマンド（`/tdd`関連） -- [ ] TDDワークフロースキル -- [ ] パッケージマネージャー自動検出 -- [ ] ドキュメント作成（README、各種ガイド） - -**成功基準**: -- プラグインが正常にインストールできる -- `/context-status`でコンテキスト使用率を確認できる -- `/tdd`コマンドでTDDワークフローを実行できる -- Hooksが正常に発火する -- NDFプラグインと併用できる - -**期間**: 2週間 - -### Phase 2: 品質向上（v1.1.0）【優先度: 中】 - -**目標**: セキュリティ機能、追加Hooks - -**実装内容**: -- [ ] セキュリティスキャン機能（`/security-scan`、`/owasp-check`） -- [ ] セキュリティレビュースキル -- [ ] TypeScript型チェックHook -- [ ] カバレッジ検証Hook -- [ ] tmux使用促進Hook -- [ ] セキュリティガイド充実 - -**成功基準**: -- `/security-scan`でOWASP Top 10チェックができる -- PreCommit Hooksでシークレット混入を検出できる -- カバレッジ80%未満時に警告が表示される - -**期間**: 1週間 - -### Phase 3: 効率化（v1.2.0）【優先度: 低】 - -**目標**: 並列ワークフロー、高度なコンテキスト管理 - -**実装内容**: -- [ ] `/fork`コマンドのサポート（git worktrees） -- [ ] 並列実行判断ロジック -- [ ] コンテキスト最適化アドバイザー -- [ ] MCP推奨設定ガイド - -**成功基準**: -- 並列実行可能なタスクを自動判断できる -- `/fork`コマンドでgit worktreesを活用できる -- MCP数超過時に最適化アドバイスが表示される - -**期間**: 1週間 - ---- - -## 🔍 実装時の注意事項 - -### 1. NDFプラグインとの互換性 - -**必須事項**: -- NDFプラグインのMCP統合に干渉しない -- NDFプラグインのエージェントと重複しない -- NDFプラグインのコマンドと命名衝突しない -- `dependencies`に`ndf: ^2.1.0`を明記 - -**推奨事項**: -- NDFプラグインの`ndf:corder`、`ndf:qa`と連携するHooks設計 -- NDFプラグインの`/commit`、`/review-pr`と補完的な機能提供 - -### 2. Hooksシステム - -**必須事項**: -- Node.js統一で記述（OS依存性排除） -- Windows/macOS/Linux対応 -- エラーハンドリング徹底（Hook失敗でもメイン処理は継続） - -**推奨事項**: -- Hooksは設定ファイルでON/OFF可能にする -- Hook実行時間を監視（遅延防止） -- Hook失敗時のフォールバック処理 - -### 3. TDDワークフロー - -**必須事項**: -- 80%カバレッジは推奨値（強制ではない） -- プロジェクトの性質に応じてカスタマイズ可能 -- カバレッジ未達時は警告のみ（ブロックしない） - -**推奨事項**: -- RED→GREEN→REFACTORの順序を厳守 -- カバレッジ閾値を設定ファイルで調整可能にする - -### 4. セキュリティチェック - -**必須事項**: -- OWASP Top 10に準拠 -- シークレット検出パターンは設定ファイルで管理 -- 誤検知を減らす正規表現パターン - -**推奨事項**: -- セキュリティスキャン結果をレポート化 -- 検出した脆弱性の修正ガイド提供 - -### 5. コンテキスト管理 - -**必須事項**: -- MCP数の上限警告（10個超過） -- ツール数の上限警告（80個超過） -- コンテキスト使用率の監視（60%閾値） - -**推奨事項**: -- `/compact`の自動実行（ユーザー確認あり） -- MCP最適化のアドバイス表示 -- コンテキスト使用率の履歴記録 - ---- - -## 🔧 NDFプラグインの修正提案 - -affaan-mプラグインとの円滑な連携のため、NDFプラグイン側にも以下の修正を推奨します。 - -### 【優先度: 高】ドキュメントの更新 - -#### 1. README.md の更新 - -**追加セクション**: -```markdown -## 推奨プラグイン併用 - -### affaan-m プラグイン - -NDFプラグインと併用することで、以下の機能が追加されます： - -- **コンテキスト管理**: `/context-status`でコンテキスト使用率を監視 -- **品質保証**: 自動フォーマット、console.log検出、シークレットスキャン -- **TDDワークフロー**: `/tdd`コマンドで5段階TDDプロセスをガイド -- **セキュリティチェック**: OWASP Top 10準拠の脆弱性検出 - -インストール方法: -\```bash -/plugin install affaan-m@ai-plugins -\``` - -詳細は[affaan-mプラグインREADME](../affaan-m/README.md)を参照してください。 -``` - -#### 2. CLAUDE.ndf.md の更新 - -**追加セクション**: -```markdown -### 8. 推奨プラグイン併用 - -**affaan-m プラグイン（推奨）**: - -NDFプラグインと併用することで、以下の機能が追加されます： - -- **コンテキスト管理**: コンテキスト使用率の監視と自動最適化 -- **品質保証Hooks**: 自動フォーマット、セキュリティスキャン -- **TDDワークフロー**: テストファーストな開発サイクルのガイド - -**使用例**: -\``` -# コンテキスト使用率を確認 -/context-status - -# TDDワークフローを開始 -/tdd "ユーザー認証機能" - -# セキュリティスキャンを実行 -/security-scan -\``` - -**注意事項**: -- affaan-mプラグインのHooksは自動的に発火します -- コンテキスト管理機能は常時監視モードで動作します -- TDDワークフローはNDFの`corder`エージェントと連携します -``` - -### 【優先度: 中】directorエージェントの更新 - -**agents/director.md に追加**: - -```markdown -### affaan-mプラグインとの連携 - -**コンテキスト管理**: -- タスク開始前に`/context-status`でコンテキスト使用率を確認 -- 60%を超える場合は警告し、`/compact`の実行を推奨 - -**TDDワークフローの推奨**: -- コーディングタスクでは`/tdd`コマンドの使用を提案 -- テスト未実装の場合はTDDワークフローを推奨 - -**品質保証**: -- コード生成後、affaan-mプラグインのHooksが自動的にチェックを実行 -- 警告が出た場合は修正を指示 - -**使用例**: -\``` -# タスク開始前 -1. コンテキスト確認: `/context-status` -2. TDDワークフロー開始: `/tdd "機能名"` -3. サブエージェント起動（ndf:corder等） -4. Hooksによる自動チェック（affaan-mが自動実行） -5. 完了確認 -\``` -``` - -### 【優先度: 中】corderエージェントの更新 - -**agents/corder.md に追加**: - -```markdown -### TDDワークフローとの連携 - -**affaan-mプラグインのTDDワークフローと連携する場合**: - -1. **インターフェース定義**（TDD Step 1） - - 関数シグネチャ、型定義を先に決定 - -2. **RED（失敗テスト）**（TDD Step 2） - - `/tdd-red`コマンドで失敗テストを作成 - - テストが失敗することを確認 - -3. **GREEN（最小実装）**（TDD Step 3） - - `/tdd-green`コマンドで最小実装 - - テストをパスする最小限のコード - -4. **リファクタリング**（TDD Step 4） - - `/tdd-refactor`コマンドでコード品質向上 - - テストは常にパスする状態を維持 - -5. **カバレッジ検証**（TDD Step 5） - - `/tdd-coverage`コマンドでカバレッジ確認 - - 80%以上を目標（affaan-mプラグインが自動チェック） - -**注意事項**: -- affaan-mプラグインのHooksが自動的にコード品質をチェックします -- console.log、シークレット、型エラーは自動検出されます -``` - -### 【優先度: 低】コンテキスト管理のベストプラクティス追加 - -**CLAUDE.md に追加**: - -```markdown -## コンテキスト管理のベストプラクティス - -### MCP設定の推奨事項 - -**推奨上限**: -- グローバル設定: 20-30個以内 -- プロジェクト設定: 10個以下 -- 総ツール数: 80個以下 - -**監視方法**: -- affaan-mプラグインの`/context-status`コマンドで監視 -- コンテキスト使用率が60%を超えたら`/compact`を実行 - -**最適化手順**: -1. 使用頻度の低いMCPサーバーを無効化 -2. プロジェクト固有のMCPのみを有効化 -3. 定期的に`/context-status`でチェック - -**例**: -\```bash -# コンテキスト使用率を確認 -/context-status - -# 60%を超えている場合 -/compact - -# MCP設定を最適化 -# 不要なMCPサーバーをdisableにする -\``` -``` - -### 【優先度: 低】marketplace.jsonの更新 - -**推奨プラグイン情報の追加**: - -```json -{ - "name": "ai-plugins", - "owner": { - "name": "takemi-ohama", - "url": "https://github.com/takemi-ohama" - }, - "plugins": [ - { - "name": "ndf", - "source": "./plugins/ndf" - }, - { - "name": "affaan-m", - "source": "./plugins/affaan-m", - "recommended": true, - "complementary": ["ndf"] - } - ], - "recommendations": [ - { - "plugins": ["ndf", "affaan-m"], - "description": "NDFプラグインとaffaan-mプラグインの併用で、MCP統合、ワークフロー、コンテキスト管理、品質保証の完全な開発環境を構築できます。" - } - ] -} -``` - -### 修正の優先順位 - -| 優先度 | 修正内容 | 影響範囲 | 工数 | -|-------|---------|---------|------| -| **高** | README.md更新 | ユーザー向けドキュメント | 小 | -| **高** | CLAUDE.ndf.md更新 | AI向けガイドライン | 中 | -| **中** | directorエージェント更新 | タスク実行フロー | 中 | -| **中** | corderエージェント更新 | コーディングワークフロー | 小 | -| **低** | CLAUDE.md更新 | 開発者向けガイド | 小 | -| **低** | marketplace.json更新 | マーケットプレイス連携 | 小 | - -### 実装タイミング - -- **v2.2.1（パッチ版）**: ドキュメント更新のみ - - README.md - - CLAUDE.ndf.md - - CLAUDE.md - -- **v2.3.0（マイナー版）**: エージェント更新 - - directorエージェント - - corderエージェント - -- **v2.3.1（パッチ版）**: マーケットプレイス連携 - - marketplace.json - ---- - -## 📚 参考リンク - -- [everything-claude-code](https://github.com/affaan-m/everything-claude-code) -- [Claude Code 実践ガイド (Qiita)](https://qiita.com/dai_chi/items/c19be47044d062d59ee8) -- [Claude Code 実装パターン (Zenn)](https://zenn.dev/ttks/articles/a54c7520f827be) -- [Claude Code 公式ドキュメント](https://docs.claude.com/en/docs/claude-code) - ---- - -## 📝 まとめ - -### affaan-mプラグインの目的 - -**NDFプラグインとの併用を前提**として、以下の補完的な機能を提供： - -1. **コンテキスト管理** - MCPツール過剰によるコンテキスト枯渇を防止 -2. **品質保証機能** - Hooksによる自動チェックと人的ミス防止 -3. **TDDワークフロー** - テストファーストな開発文化の確立 -4. **セキュリティチェック** - OWASP Top 10に準拠した脆弱性検出 -5. **開発効率化** - パッケージマネージャー自動検出等 - -### NDFプラグインとの役割分担 - -| プラグイン | 役割 | -|-----------|------| -| **NDFプラグイン** | MCP統合、ワークフロー、専門エージェント | -| **affaan-mプラグイン** | コンテキスト管理、品質保証、TDDワークフロー | - -### 実装ロードマップ - -#### Phase 1: affaan-mプラグイン作成（v1.0.0） - -**実装内容**: -- コンテキスト管理（`/context-status`、自動コンパクト化） -- 基本Hooks（auto-format, secret-scan, console.log検出） -- TDDワークフロー（`/tdd`関連コマンド、TDDスキル） -- パッケージマネージャー自動検出 -- ドキュメント整備 - -#### Phase 2: NDFプラグイン更新（v2.2.1 〜 v2.3.0） - -**v2.2.1（パッチ版）- ドキュメント更新**: -- README.md: affaan-m併用の推奨 -- CLAUDE.ndf.md: 併用時のガイドライン -- CLAUDE.md: コンテキスト管理ベストプラクティス - -**v2.3.0（マイナー版）- エージェント更新**: -- directorエージェント: affaan-m連携ロジック追加 -- corderエージェント: TDDワークフロー連携 - -**v2.3.1（パッチ版）- マーケットプレイス連携**: -- marketplace.json: 推奨プラグイン情報追加 - -### 期待される効果 - -**併用による相乗効果**: -- NDFプラグイン（MCP統合 + 専門エージェント） -- affaan-mプラグイン（コンテキスト管理 + 品質保証） -- = **本番環境対応の開発支援環境** - -これらを段階的に導入することで、Anthropicハッカソン優勝者（Affaan Mustafa氏）が実証した本番環境レベルの開発支援環境を構築できます。 diff --git "a/issues/old/\343\203\227\343\203\254\343\202\274\343\203\263\346\247\213\346\210\220\346\241\210.md" "b/issues/old/\343\203\227\343\203\254\343\202\274\343\203\263\346\247\213\346\210\220\346\241\210.md" deleted file mode 100644 index bc4257bf..00000000 --- "a/issues/old/\343\203\227\343\203\254\343\202\274\343\203\263\346\247\213\346\210\220\346\241\210.md" +++ /dev/null @@ -1,307 +0,0 @@ -# 2026年度 開発指針プレゼンテーション構成案 - -## スライド1: タイトルページ -**2026年度 開発指針** -～コストセンターからベネフィットセンターへ、そしてエンジニア駆動の未来へ～ - ---- - -## スライド2: 目次 -1. 現状認識と課題 -2. 2026年度の3つの重点項目 -3. ナイル全社のAI効率化 -4. BPO（ビジネスプロセスアウトソーシング）への挑戦 -5. エンジニア駆動開発への転換 -6. 組織体制の改革：SQローテーションの試み -7. 開発環境の整備 -8. 全社協力体制の構築 -9. ロードマップとKPI -10. まとめ - ---- - -## スライド3: 現状認識と課題 -### これまでの3年間 -- **かるもーん開発への集中** - - 単一プロダクトへのリソース投下 - - 他システム・部署の置き去り - -### 現在の課題 -- コストセンターとしての位置づけ -- 属人化・知識の偏在 -- 運用負荷の特定メンバーへの集中 -- ドキュメント不足 -- 現場ニーズの吸い上げ不足 - ---- - -## スライド4: 2026年度の3つの重点項目 -### 1. ナイル全社のAI効率化 -開発・運用の両面でAIエージェントを全面導入 - -### 2. BPOへの挑戦 -コストセンターからベネフィットセンターへの転換 - -### 3. エンジニア駆動開発 -ヒアリングから自己洞察へ、現場実践を通じた価値創造 - ---- - -## スライド5: ナイル全社のAI効率化 -### 開発におけるAI活用 -- **AIエージェントの全員導入** - - Claude Code、GitHub Copilotなどの積極活用 - - Vibe Coding実践による生産性向上 - -### 運用におけるAI活用 -- **輪番制と組み合わせた運用改善** - - AI支援による属人化解消 - - ドキュメント自動生成・更新 - -- **現場実践を通した業務効率化** - - AIを活用した隙間時間でのドキュメント整備 - - 自律的な課題発見と起票 - ---- - -## スライド6: BPOへの挑戦（1/2） -### コストセンターからベネフィットセンターへ - -**ビジョン** -内部の効率化を外部サービスとして提供し、収益源へ転換 - -### 3つのBPO事業領域 -1. **自動車産業DXサービスBPO** - - 業界知見を活かしたDX支援 - -2. **AI開発支援サービスBPO** - - AI導入・活用のコンサルティング - -3. **Nyle X Partners（ナイル イクスパートナーズ）支援** - - エンジニアリング支援・コーチング - - 人材調達支援 - ---- - -## スライド7: BPOへの挑戦（2/2） -### 成功のための前提条件 -- 社内での実績・ノウハウ蓄積 -- AIエージェント活用のベストプラクティス確立 -- 標準化されたプロセスと運用体制 - -### 期待される効果 -- 新たな収益源の創出 -- エンジニアのキャリアパス拡大 -- 社外への技術プレゼンス向上 -- 採用ブランディング強化 - ---- - -## スライド8: エンジニア駆動開発への転換 -### 従来の開発スタイルからの脱却 - -**Before（ヒアリング型）** -- 「どうすれば良い？」「どれが良い？」 -- 要件を聞いて実装する受動的な姿勢 - -**After（提案型・実践型）** -- 「これが良い！」 -- エンジニアが現場を理解し、能動的に提案 - -### 現場実践制度の構築 -- **エンジニアが現場業務を実践** - - 実際の業務フローを体験 - - ペインポイントの直接把握 - -- **置き土産の重視** - - 「エンジニアが来てくれてよかった」 - - 現場に負担をかけず、価値を残す - -### 目指す姿 -- かゆいところに手が届くサービス -- 手を抜かない実装 -- ユーザーに本当に使われるプロダクト - ---- - -## スライド9: 組織体制の改革：SQローテーションの試み（1/2） -### スクワッド制の継続・強化 - -**基本方針** -- 少人数チーム編成（理想は3人、最大5人） -- スクワッド単位でのミッション明示 -- 特定事業領域のエキスパート化 - -**属人化の排除** -- スクワッド内で「知らない」をなくす -- 個人への負担集中を防ぐ仕組み - ---- - -## スライド10: 組織体制の改革：SQローテーションの試み（2/2） -### ミッション外運用の輪番制導入 - -**狙い** -- どのスクワッドでも運用対応できる体制 -- 知識の水平展開 -- 特定メンバーへの負荷集中回避 - -**対象業務** -- 作業依頼対応 -- 不具合一次対応 -- 緊急対応 -- 自律的な課題発見と起票 - -### 段階的なローテーション展開 -1. **基盤構築フェーズ**：輪番制で安定化 -2. **拡大フェーズ**：ミッション交換・ローテーション -3. **協力フェーズ**：事業部外協力の企画 - ---- - -## スライド11: 単一プロダクトから全体最適へ -### これまでの3年間 -- かるもーん開発への集中投資 -- 他システム・部署のメンテナンス後回し - -### 2026年度の方針 -**「置き去りにされた」部署への集中対応** -- 優先順位の再評価 -- リソース配分の最適化 -- 技術的負債の計画的解消 - -### 期待される効果 -- 全社的な開発効率向上 -- 部署間の不公平感解消 -- システム全体の品質底上げ - ---- - -## スライド12: 開発環境の整備 -### ドキュメント整備 -- **AIを活用した執筆** - - 隙間時間での更新 - - 継続的なメンテナンス - - 全システムで80%以上のカバレッジ目標 - -### 技術的負債への取り組み -- 計画的なリファクタリング -- テストカバレッジの向上 -- CI/CDパイプラインの最適化 - ---- - -## スライド13: laravel-adminとの向き合い方（1/2） -### 現状認識 -**laravel-adminは逃げられない現実** -- 多くの管理画面で採用 -- 置き換えには膨大なコストと時間 -- メンテナンスが停滞気味 - -### 発想の転換 -**「逃げる」から「向き合う」へ** -- いっそメンテナーを目指す -- コミュニティへの貢献を通じた技術力向上 -- 社内ノウハウの蓄積と展開 - ---- - -## スライド14: laravel-adminとの向き合い方（2/2） -### 段階的なロードマップ - -**短期（～1年目：2026年度）** -- **volareinc/laravel-adminとしてfork** - - 社内カスタマイズの集約 - - バグフィックス・機能改善 - - ドキュメント整備 - -**中期（1～2年目：2027-2028年度）** -- **公式メンテナーを目指す** - - プルリクエストの積極的投稿 - - イシュー対応への参加 - - コミュニティでの存在感確立 - -**長期（2年後～：2029年度～）** -- **React SPAへの旅立ち** - - 段階的な移行計画 - - モダンな技術スタックへの刷新 - - laravel-adminで培った知見の活用 - -### 期待される効果 -- 技術的負債の計画的解消 -- エンジニアのOSS貢献実績 -- 採用ブランディング向上 -- コミュニティからの評価獲得 - ---- - -## スライド15: ナイルエンジニア全社協力体制 -### 横断PJの結成 -**対象組織** -- DXM（デジタルトランスフォーメーション） -- MS（マーケティングソリューション） -- MDXマーケティング -- パティオ - -### 活動内容 -- **AIエージェントを活用したVibe Coding実践** -- **工数配分**：SQ業務 80% + 横断PJ 20% - -### 知識共有の拡大 -**勉強会・技術ブログ** -- これまで：MDXエンジニア主体 -- これから：事業部・職種を問わず全社開放 -- 誰でも参加・発信できる環境 - ---- - -## スライド16: ロードマップとKPI -### 2026年度ロードマップ - -**Q1（4-6月）** -- AI効率化：全エンジニアへのAIツール導入完了 -- 組織改革：輪番制スタート、スクワッド再編 -- 現場実践：パイロットプログラム開始 - -**Q2（7-9月）** -- BPO準備：社内実績の蓄積、サービス設計 -- 全社協力：横断PJ本格始動 -- 開発環境：laravel-admin fork・メンテナンス開始 - -**Q3（10-12月）** -- BPO試験運用：Nyle X Partners支援開始 -- 全体最適：置き去り部署への集中対応開始 - -**Q4（1-3月）** -- BPO本格展開：外部サービス提供開始検討 -- 振り返りと2027年度計画 - -### 主要KPI -- AI活用率：100%（全エンジニア） -- 運用対応の平準化：特定メンバー負荷50%削減 -- BPO案件：3件以上の実績創出 -- 現場実践：全スクワッドで1回以上実施 -- 横断PJ工数：20%達成 -- ドキュメントカバレッジ：主要システム80%以上 - ---- - -## スライド17: まとめ -### 2026年度開発指針の核心 - -**変革の3本柱** -1. **AI効率化** - 全員がAIを使いこなす組織へ -2. **BPO挑戦** - 収益を生み出すエンジニアリング組織へ -3. **エンジニア駆動** - 現場を知り、価値を創るエンジニアへ - -### 実現のために -- スクワッド制の強化と輪番制の導入 -- 全社協力体制の構築 -- 継続的な学習と知識共有 - -### ゴール -**「技術で価値を創造し、収益を生み出す、エンジニアが主役の組織」** - ---- - -*以上、17ページの構成案（laravel-admin関連を2ページに拡充）* diff --git "a/issues/old/\351\226\213\347\231\272\346\214\207\351\207\235.md" "b/issues/old/\351\226\213\347\231\272\346\214\207\351\207\235.md" deleted file mode 100644 index 765c5b87..00000000 --- "a/issues/old/\351\226\213\347\231\272\346\214\207\351\207\235.md" +++ /dev/null @@ -1,69 +0,0 @@ -# 開発指針策定PJ - -## 開発指針の想定読者 - -- 経営層 -- エンジニア -- MDXの他ユニットのマネージャークラス -- 他事業部のマネージャークラス - -## 開発指針に書くべきこと - -- ナイル全社のAI効率化 - - 開発におけるAIエージェントの全員導入 - - 運用におけるAIを活用した効率化 - - 輪番制(後述)に組み込んだ運用改善 - - 現場実践(後述)を通した業務効率化 -- BPOビジネスプロセスアウトソーシング)への挑戦 - - コストセンターからベネフィットセンターへ - - 自動車産業DXサービスBPO - - AI開発支援サービスBPO - - **Nyle X Partners（ナイル イクスパートナーズ）**に対するエンジニアリング支援・コーチング、人材調達支援 -- SQローテーションの試み - - スクワッド制は継続・強化 - - スクワッド単位でのミッションの明示 - - 原則あるスクワッドはあるミッションに専念する - - スクワッド単位で特定事業領域に対するエキスパートとなる - - 少人数チーム編成（理想は3人。多くても5人まで） - - 属人化の排除 - - スクワッド内での「このタスクは知らない」をなくす - - 個人に負担が集中しない仕組みづくり - - ミッション外運用の輪番制導入 - - 運用(作業依頼対応、不具合一次対応、緊急対応、自律的な課題発見と起票)はどのスクワッドでもできるように - - これらの安定基盤を築いたうえで、知識範囲を拡大し幅広い視点を養うためのミッション交換、ローテーション、事業部外協力などを企画する -- 単一プロダクト開発(かるもーん)から全体最適へ - - 3年間集中していた「かるもーん」 - - 「置き去りにされた」部署への集中対応 -- 開発環境の整備 - - AIによるドキュメント整備 - - 隙間時間を活用したドキュメントの更新(AIを利用した執筆) - - laravel-adminからは逃げられない - - いっそメンテナーを目指そう - - まずはforkしてvolareinc/laravel-adminのメンテナンスへ - - 中期的には公式メンテナーへ - - 長期的にはReact SPAへの旅立ち(2年後をめどに) -- エンジニア駆動開発 - - ヒアリングから自己洞察へ - - エンジニアが現場に入り込んで実践する制度の構築(現場実践) - - もちろん現場に過度な負担をかけないように - - 「エンジニアが現場に入ってくれてよかった」的な置き土産付き - - 「どうすれば良い？」「どれが良い？」から「これが良い！」へ - - エンジニアが提案するサービスこそが一番使いやすい。はず。 - - かゆいところに手が届く。手を抜かないサービスの実装 - - れいやーえっくすにつづけみたいななにか - - 提案できる知識と経験の習得を前提とする -- ナイルエンジニア全社協力体制 - - SQとは別の横断PJ - - 特にDXM、MSへの技術協力のためのPJ結成 - - MDXマーケ、パティオなども対象とする - - AIエージェントを全面活用したVibe Codingの実践 - - SQとPJの工数配分(20%前後) - - 勉強会、技術ブログの拡充 - - MDXエンジニア主体で運営していた勉強会・ブログ - - 事業部・職種にこだわらず解放。誰でも参加へ - -## このうち、重点項目はどれ？ - -- ナイル全社のAI効率化 -- BPO挑戦 -- エンジニア駆動開発 diff --git a/issues/template09.md b/issues/template09.md deleted file mode 100644 index 73067ffa..00000000 --- a/issues/template09.md +++ /dev/null @@ -1,77 +0,0 @@ -## 🔧 PRレビュー指摘対応 (dd08b91) - -### 対応した指摘 - -| # | 優先度 | ファイル | 指摘内容 | 対応 | -|---|--------|---------|----------|------| -| 1 | **P1** | `lease_screening_service.py` | CICスコア取得が日本語キーに対応していない | ✅ 修正済み | -| 2 | **P1** | `inquiry.py` | 同様にCICスコア取得が日本語キーに対応していない | ✅ 修正済み | -| 3 | **P1** | `docs/lease-screening-*.md` | final_categoryラベルがコードと不一致 | ✅ 修正済み | -| 4 | **P2** | `docs/lease-screening-*.md` | TIER_VERSIONがコードと不一致 | ✅ 修正済み | - ---- - -### 修正1・2: CICスコア取得キー修正 - -**問題**: `translated_data`（日本語キー変換後）から`creditGuidance`を参照していたため、CICスコアが常に`None`になっていた - -**修正**: 翻訳後のキー名を使用 - -```python -# Before -credit_answer = cic_result.get("信用照会回答エリア", {}) -cic_score_str = credit_answer.get("creditGuidance") - -# After -credit_answer = cic_result.get("信用照会回答エリア", {}) -cg_area = credit_answer.get("クレジットガイダンスエリア", {}) -cic_score_str = cg_area.get("指数") -``` - -**翻訳マップ（jp.yml）確認結果:** -- `creditGuidance` → `クレジットガイダンス` -- `creditGuidanceArea` → `クレジットガイダンスエリア` -- `cgResult` → `指数` - ---- - -### 修正3: final_categoryラベル名更新 - -ドキュメントをコード実装に合わせて更新: - -| 旧ドキュメント記載 | 新ドキュメント記載（コードと一致） | -|-------------------|----------------------------------| -| `自社審査_否決_パティオ通販` | `自社審査_否決_ナーチャ連携` | -| `自社審査_否決_買取` | `自社審査_否決_ナーチャ連携_買取案内` | -| `自社審査_完全否決` | `自社審査_否決_完全否決` | - ---- - -### 修正4: tier_version更新 - -| 項目 | 旧値 | 新値 | -|------|------|------| -| `tier_version` | 20260201 | 20260205 | - -criteria37-2.sql対応でバージョンが更新されていたため、ドキュメントも同期。 - ---- - -### テスト結果 - -``` -============================================================ -TierCalculator 単体テスト (criteria37-2.sql対応) -============================================================ -全テスト完了! -============================================================ -``` - -### 修正ファイル - -- `cic-proxy/lib/lease_screening_service.py` - CICスコア取得キー修正 -- `cic-proxy/lib/inquiry.py` - バッチTier判定のCICスコア取得修正 -- `docs/lease-screening-api.md` - final_category・tier_version更新 -- `docs/lease-screening-changelog.md` - 変更履歴追記・ラベル名更新 - -**PR URL**: https://github.com/takemi-ohama/ai-plugins/pull/13 diff --git a/plugins/affaan-m/README.md b/plugins/affaan-m/README.md index b82ef08d..38844c32 100644 --- a/plugins/affaan-m/README.md +++ b/plugins/affaan-m/README.md @@ -307,4 +307,4 @@ MIT License ## サポート -Issue報告: https://github.com/takemi-ohama/ai-plugins/issues +Issue報告: https://github.com/devbasex/ai-plugins/issues diff --git a/plugins/mcp-playwright/.claude-plugin/plugin.json b/plugins/mcp-playwright/.claude-plugin/plugin.json index 91b2af01..cca6d671 100644 --- a/plugins/mcp-playwright/.claude-plugin/plugin.json +++ b/plugins/mcp-playwright/.claude-plugin/plugin.json @@ -4,7 +4,7 @@ "description": "Playwright MCPを自動セットアップするプラグイン。Chromiumブラウザの自動インストールとMCP設定を提供します。", "author": { "name": "NDF Team", - "url": "https://github.com/takemi-ohama/ai-plugins" + "url": "https://github.com/devbasex/ai-plugins" }, "keywords": ["mcp", "playwright", "browser", "automation", "testing"] } diff --git a/plugins/mcp-playwright/README.md b/plugins/mcp-playwright/README.md index 11a6a481..8e9ef19d 100644 --- a/plugins/mcp-playwright/README.md +++ b/plugins/mcp-playwright/README.md @@ -157,4 +157,4 @@ MIT License ## サポート 問題が発生した場合は、GitHubリポジトリでissueを作成してください： -https://github.com/takemi-ohama/ai-plugins/issues +https://github.com/devbasex/ai-plugins/issues diff --git a/plugins/ndf/AGENTS.md b/plugins/ndf/AGENTS.md index 37153c59..aa32aa2a 100644 --- a/plugins/ndf/AGENTS.md +++ b/plugins/ndf/AGENTS.md @@ -9,7 +9,7 @@ - **名前**: ndf - **現在バージョン**: 4.4.0 - **種類**: 統合プラグイン（Skills + Agents + Hooks / v4.0.0 で Codex MCP 廃止） -- **リポジトリ**: https://github.com/takemi-ohama/ai-plugins +- **リポジトリ**: https://github.com/devbasex/ai-plugins > **Note (v3.0.0)**: Serena MCPは`mcp-serena`プラグインに分離。memory系スキルは廃止。CLAUDE.ndf.md注入は廃止。 diff --git a/plugins/ndf/README.md b/plugins/ndf/README.md index de21b723..59a59af0 100644 --- a/plugins/ndf/README.md +++ b/plugins/ndf/README.md @@ -57,7 +57,7 @@ GitHub、Context7 MCPは公式プラグインとして提供されています ```bash # Claude Codeで実行 -/plugin marketplace add https://github.com/takemi-ohama/ai-plugins +/plugin marketplace add https://github.com/devbasex/ai-plugins ``` ### ステップ2: プラグインのインストール @@ -717,7 +717,7 @@ NDFプラグインと併用することで、以下の機能が追加されま 問題が発生した場合： 1. 上記のトラブルシューティングセクションを確認 -2. GitHubリポジトリでイシューを作成: https://github.com/takemi-ohama/ai-plugins/issues +2. GitHubリポジトリでイシューを作成: https://github.com/devbasex/ai-plugins/issues ## ライセンス