pipeline-optimizer · v1.2.0 · 2026-07-30 · sha256 3945912530a91eda
pipeline-optimizer v1.2.0A

Name: pipeline-optimizer
Author: ellmos-ai
Immutable. This exact content is served forever at /api/v1/blob/3945912530a91eda.
---
name: pipeline-optimizer
version: 1.2.0
type: protocol
author: Lukas Geiger (method) + Claude (write-up)
created: 2026-05-16
updated: 2026-06-13
aliases: [project-folder-optimizer, pipeline-renovator, project-renovator]
description: 既存のパイプライン、個別プロジェクトフォルダ、ドキュメント構造、またはソフトウェアスタックを改善、改修、再構築するための構造化された6ステップのプロシージャ。「pipeline optimizer」（ソフトウェア、研究、ゲーム開発パイプラインなど、トピック全体のパイプライン対象）または「project-folder optimizer」（単一のソフトウェアツールや論文プロジェクトなど、パイプライン内の個別プロジェクトフォルダ対象）として呼び出し可能。「パイプラインXを改善する」、「スタックを最適化する」、「Yを再構築する」、「改修」、「パイプラインのリファクタリング」、「プロジェクトフォルダのクリーンアップ」、「フォルダ構造の改善」、「規約の統一」、「ドキュメントの統合」、「既存システムへの統合」、または確立された構造に対する実質的な介入タスクで起動。既存資産の調査、目的の明確化、理想像のスケッチ、ギャップ計画、経験的課題の特定、および新しいサブエージェントによる再テストを提供。並行標準の発生、重複、パイプラインの破綻を防止。
standalone: true
anthropic_compatible: true
bach_compatible: true
bach_origin: false
category: dev
tags: [pipeline, renovation, refactoring, stack, workflow, lessons-learned]
language: ja
status: active
dependencies: {'tools': [], 'services': [], 'protocols': [], 'python': []}
provenance: {'origin': 'custom', 'origin_path': '~/.claude/skills/pipeline-optimizer/', 'origin_version': '1.1.1', 'last_sync_from_origin': '2026-05-16', 'last_sync_to_origin': None, 'local_changes_since_sync': True}
---

> **日本語** — `pipeline-optimizer` の公式日本語版。


# Pipeline Optimizer / Project-Folder Optimizer (日本語)

**互換性問題を起こさない6ステップの改修プロセス** — 2つのスケールで適用可能:

| トリガー名 | 適用範囲（スコープ） | 例 |
|---|---|---|
| **Pipeline optimizer** | パイプライン全体、スタック、ドキュメント構造 | トピックパイプライン（例: `software/`、`research/`、`games/`、エージェントシステム） |
| **Project-folder optimizer** | パイプライン内の個別プロジェクトフォルダ | ソフトウェアツール、論文プロジェクト、ゲームプロジェクト |

ここでの**パイプライン**とは、共通の規約のもとで複数のプロジェクトが存在する、トピック指向のトップレベル構造を指します（例: リリースルールを持つソフトウェアパイプライン、出版手続きを持つ研究パイプライン）。

両者とも同じ6ステップのワークフローを使用します — 唯一の違いは**適用範囲（スコープ）**（パイプライン全体 vs. 単一プロジェクト）であり、それに伴いステップAにおける既存資産調査の深さが異なります。

## 本 Skill の適用タイミング

本 Skill は、新規構築（greenfield）ではなく、**既存の**構造を改善、再構築、または拡張するよう依頼された場合に適用されます。具体的なトリガー:

**パイプラインレベル**（スコープ: パイプライン全体）:
- 「パイプライン X を改善する」
- 「スタックを最適化する」
- 「ソフトウェアパイプラインを改修する」
- 「研究パイプラインにおけるドキュメント統合」
- トピックパイプライン、中央の `_tools/`、またはシステムコンポーネントに対する実質的な介入

**プロジェクトフォルダレベル**（スコープ: 単一プロジェクトフォルダ）:
- 「プロジェクトフォルダ X のクリーンアップ / 最適化」
- 「Y のフォルダ構造を改善する」
- 「単一ツールのリファクタリング」
- 「論文プロジェクトのセットアップ統一」
- 「ゲームプロジェクトフォルダをパイプライン標準に準拠させる」

**横断的・共通:**
- 「X を再構築し、既存の Y に統合する」
- 「リファクタリング」、「統合」
- 「規約の統一」
- 「既存システムへの統合」

## 既存建築物（資産）の比喩

家を改修するには、まず**何で作られているか**（石、木、プラスチック）、**何のためにあるのか**（山小屋、ソフトウェア工房）、アンド**すでにどこで機能を果たしているか**を知る必要があります。同じ規律がパイプラインにも適用されます。

---

## 実施手順 — 6ステップ（スキップ不可、順序変更不可）

### ステップ A — 既存資産の調査

**質問:** 家は何で作られていますか？

**パイプラインスコープ**（すべてのルートドキュメント + ツール + テンプレート）:
- [ ] **すべてのルートドキュメントを完全に読み込む**（スニペットや挿入箇所だけで判断しない）
- [ ] テンプレートフォルダ（`_templates/`、`_TEMPLATES/`）およびツールフォルダ（`_tools/`）の確認
- [ ] ポリシーファイル: 例: GITHUB-POLICY.md, RELEASE-MANAGEMENT.md, QUALITY_RULES.md, NAMING-SYSTEM.md, 出版手続き など
- [ ] ステータススナップショット: 例: PROJECT_STATUS.md, ステータス概要, releases.json, レジストリファイル
- [ ] チェックリスト: 例: リリースチェックリスト, ビルド/PDFチェックリスト
- [ ] ワークフロー: AGENTS.md, GUIDE.md, SKILL.md
- [ ] 経験教訓ファイル: LESSONS_LEARNED.md, MEMORY.md, ループ状態ファイル

**プロジェクトフォルダスコープ**（単一プロジェクトの実体 + 関連するパイプライン規約）:
- [ ] **プロジェクトフォルダ内のすべての Markdown および制御ファイルを読み込む**（README, CHANGELOG, TASKS/TODO, DONE, CONCEPT, アクションプラン, 証明メモ など）
- [ ] **コード構造の調査:** src/, tests/, ビルド構成（pyproject.toml, requirements.txt, プロジェクトマニフェスト, ツールチェーンファイル など）
- [ ] **親パイプラインの規約を考慮する**（例: ソフトウェアプロジェクトの場合: GitHub ポリシー, 命名システム, リリース管理, テンプレート）
- [ ] **プロジェクト内の既存ツール/スクリプトをスキャンする**（`_tools/`, `_scripts/`, build_*.bat, START スクリプト）
- [ ] **設定ファイル:** `.gitignore`, LICENSE, NOTICE, SECURITY.md, CODE_OF_CONDUCT.md

**アンチパターン:** `grep -l "<keyword>"` を使用して挿入箇所を検索し、ファイルのコンテキストを理解せずに直接挿入すること。

**アウトプット:** 選択したスコープにおけるすべての関連規約、ツール、テンプレートを含むインベントリメモ。

### ステップ B — 目的の特定

**質問:** 家は何のために存在していますか？

目的を 1〜2 文で明示的に記述します。

**パイプラインの例:**

| パイプライン | 目的 |
|---|---|
| ソフトウェアパイプライン | デスクトップアプリ + ブラウザツールを開発・テストし、ストア/GitHub にリリースする |
| 研究パイプライン | 学術論文を執筆・査読し、リポジトリ/プレプリントサーバーに公開する |
| ゲームパイプライン | ゲームを開発し、ターゲットプラットフォームで公開する |
| エージェントシステム | マルチエージェントオーケストレーションのための LLM システム |

**プロジェクトフォルダの例:**

| プロジェクトフォルダ | 目的 |
|---|---|
| `software/PlannerApp` | 計画管理デスクトップアプリ、商用、プライベートリポジトリ |
| `research/CosmologyModel` | モデル論文シリーズ + 数値計算 |
| `games/SortingChaos` | ソートゲーム、アルファ段階、レベル進行 |

目的は**あらゆる介入を誘導します** — 目的を果たさない施策は破棄されます。

### ステップ C — 理想像のスケッチ

**質問:** この目的のための完璧な家はどのようなものですか？

- 自分自身の視点からスケッチします（簡潔に、最大10項目）
- ベストプラクティスの比較を取り入れます（例: SaaS の場合は Vercel スタック、研究の場合は scientific-python スタック）
- 詳細な最適化に陥らないようにします — トップレベルの概要スケッチで十分です

**アウトプット:** パイプラインごとの「理想状態」5〜10項目

### ステップ D — ギャップ分析と計画

**パイプラインごとの4つの質問:**

1. **家にはすでに何がありますか？** — 理想と解決方法が異なっていても、**機能的に同等**であれば含まれます。
   *例:* 理想では「サードパーティライセンスに pip-licenses を使用」と指定されているが、現実はカスタム生成スクリプトがそれをラップしている → 機能的に同等であるため、介入不要。

2. **何が機能を阻害していますか？** — 現在、障害や余分な手間を引き起こしている既存構造。

3. **機能していないものは何ですか？** — デッドコード、時代遅れの規約、未使用のツール。

4. **何が機能を測定可能な形改善しますか？** — 期待される利益を伴う具体的な介入。

→ これにより**具体的な計画**を策定:
- 何を**新規構築**するか？
- 何を**拡張**するか？
- 何を**解体/撤去**するか？
- 何を**変更なし**とするか（明確に命名することが重要！）

**アウトプット:** 列「*介入事項* / *既存状態* / *施策* / *根拠*」を持つ計画表

### ステップ E — 実証的に取り組む

トップダウンの計画だけでなく、課題（ペインポイント）を収集します:

- [ ] **既知のバグ**: イシュートラッカー、TASKS/TODO/DONE ファイル
- [ ] **エラー履歴**: 経験教訓ファイル、バグ修正ログ、チェックレジストリ
- [ ] **自動化の破綻**: 「いつも手動で行わなければならない作業は何か？」
- [ ] **ユーザーインタビュー**: 具体的にヒアリング — 課題、要望、回避策
- [ ] **セルフテスト**: パイプラインを一通り実行してみる（新規プロジェクトの作成、ビルドの実行、リリースのシミュレーション） — どこで破綻するか？

実証的に発見された課題によって、ステップDの計画の**優先順位が決定**されます。

### ステップ F — 実施後の再テスト

- [ ] 改修コンテキストの影響を受けていない**新しいサブエージェント**に、変更後のワークフローを実行させる
- [ ] **測定可能な事前/事後データ**: セットアップ時間、エラー率、手動ステップ数、ビルド時間
- [ ] **回帰防止チェック**: 変更後も既存のワークフローが正常に動作するか？
- [ ] **測定可能な改善が見られない**場合、または回帰が発生した場合: 改修を**ロールバック**するか再調整する

## アンチパターン（禁止事項）

| アンチパターン | 損害 | 処方箋 |
|---|---|---|
| ドキュメントを読まずに挿入箇所を検索する | 並行標準の発生 | ステップ A を完全実行 |
| 「X のベストプラクティス」を1:1でそのまま導入する | 不互換 | ステップ D で機能的に比較 |
| 規約を確認せずに新しいファイルを作成する | 重複（例: NOTICE.md ↔ THIRD_PARTY_LICENSES.txt） | ステップ A + ステップ D |
| 実証データなしでトップダウン計画を立てる | 解決策が実際の課題とズレる | 計画決定前にステップ E を実行 |
| 自身の変更をテストしない | 未検出の回帰 | 新しいエージェントでステップ F を実行 |
| 状態が不明確なまま「後で明確化」とする | ユーザーが後から衝突に気づく | 不確実な場合は、ステップ D をユーザーと再確認 |

## ケーススタディ — NOTICE.md 事件

**任務:** 複数のトピックパイプライン（ソフトウェア、研究、ゲーム）にわたってパイプラインの改善を実施。

**ミス:** ステップAをスキップ — 完全なポリシーファイルを読まずに、挿入箇所のみを検索。

**結果:** `THIRD_PARTY_LICENSES.txt` + カスタムライセンス生成器（`pip-licenses` のラッパー）が確立されていたにもかかわらず、7つのファイルに「新しいライセンスファイル」として `NOTICE.md` を導入 — これはパイプラインの GitHub ポリシー（必須ファイル + ライセンスチェックリスト）に文書化されていた。すべてのソフトウェアプロジェクトには既に THIRD_PARTY ファイルが存在していた。

**発覚:** ユーザーから指摘されて初めて発覚（「権利管理は既にあったはずだが」）。

**修正:** プロジェクトテンプレートから NOTICE.md を削除し、さらに6つのファイルを調整、`pip-licenses` の代わりに既存のライセンス生成器を参照するように修正。

**教訓:** ステップ A が完全に実行されていれば、書き込み前に衝突が検出されていた。

## 経験則

1. **「パイプラインの改善」においては、書く時間と同じくらいまず読むこと。**
2. **既存の標準が存在しないという証明がない限り、新しい標準を作らない。**
3. **新しい並行ツールを作るのではなく、既存のツール/ラッパーを使用する。**
4. **「無駄な機械的追加」は通常「既存のものを拡張する」ことよりも悪い。**
5. **衝突発生時のロールバック**は、2つの並行標準を運用するよりも常に優れている。

## 完了チェックリスト

パイプラインの改修を「完了」と報告する前に:

- [ ] ステップ A: 関連するすべてのルートドキュメントを読み込んだか？
- [ ] ステップ B: パイプラインの目的を 1〜2 文で記述したか？
- [ ] ステップ C: 理想像をスケッチしたか（5〜10項目）？
- [ ] ステップ D: 表によるギャップ分析を行ったか（維持 / 拡張 / 新規 / 廃棄）？
- [ ] ステップ E: 実証データを確認したか（バグ、教訓、セルフテスト、ユーザーインタビュー）？
- [ ] 計画についてユーザーと合意したか？
- [ ] ステップ F: 新しいサブエージェントでテストし、改善が測定可能か？
- [ ] 並行標準が導入されていないか？
- [ ] 衝突が発生した場合: ロールバックされたか、あるいは正直に説明されたか？

## 最適なプロジェクトフォルダ構造（プロジェクトフォルダオプティマイザー向け）

本 Skill を**単一のプロジェクトフォルダ**に適用する場合、以下の組み合わせ推奨が理想的な参照（ステップ C）として役立ちます:

### Anthropic 標準 (Claude Code)

| ファイル/フォルダ | 機能 |
|---|---|
| `CLAUDE.md` (ルート) | Claude Code により自動読み込み、プロジェクト固有の指示 |
| `.claude/settings.json` | 権限、環境変数、モデル選択（コミット対象） |
| `.claude/settings.local.json` | ローカルオーバーライド（コミット不可、`.gitignore` に追加） |
| `.claude/commands/*.md` | カスタムスラッシュコマンド |
| `.claude/agents/*.md` | カスタムサブエージェント |
| `.claude/skills/<name>/SKILL.md` | プロジェクト Skill |

### 独自のプロジェクトドキュメントテンプレート（推奨）

独自のプロジェクトドキュメントテンプレート（例: `<your-workspace>/_templates/project-docs/` 配下）を維持している場合、**3つの構築プロファイル**が効果的です。分割例: **MINIMAL** は 7 つのルートファイル（`AGENTS.md`, `CLAUDE.md`, `README.md`, `START.md`, `STATE.md`, `TODO.md`, `DONE.md`）と `_tools/` によるセッションコアセットを提供します。**STANDARD** は `CHANGELOG.md`, `DECISIONS.md`, `PATTERNS.md` を追加します。**FULL** は 14 のルートファイルに拡張し、さらに `ARCHITECTURE.md`, `WORKFLOWS.md`, `TOOLS.md`, `GLOSSARY.md` ならびに `workflows/` および `.github/` を追加します。

→ **このようなテンプレートを新しいプロジェクトのベースとして使用する**（手動作成ではなくコピーする）。

### パイプライン固有の追加項目（例）

パイプラインに応じて、さらに必須ファイルが追加されます — 典型的なパターン:

- **ソフトウェアプロジェクト:** LICENSE, CODE_OF_CONDUCT.md, SECURITY.md, CONTRIBUTING.md, THIRD_PARTY_LICENSES.txt（自動生成）, pyproject.toml/requirements.txt, パイプラインの中央リリースレジストリへのエントリ。→ 利用可能な場合: パイプラインの cookiecutter テンプレートを使用。
- **研究プロジェクト:** 概念ドキュメント、アクションプラン、出版プラン、アーカイブ/ソース/結果/データフォルダ（`_archive/`, `_sources/`, `_results/`, `_data/`）、LaTeX 用の `paper/`。証明プロジェクトの場合: 証明チェーンとステータスを含む証明メモファイル。
- **ゲームプロジェクト:** エンジンのプロジェクトマニフェストおよびツールチェーンファイル（例: Roblox/Rojo の場合: default.project.json, rokit.toml, wally.toml, selene.toml）、ゲームデザインドキュメント、エンジン規約に基づく `src/{server,client,shared}/`。

### 完全な詳細参照

→ 本 Skill フォルダ内の **`references/optimal-project-structure.md`**（ドイツ語）を参照。内容:
- `settings.json` の例（Anthropic スキーマ）
- 必須の `.gitignore` エントリ
- アンチパターン（プロジェクトフォルダに含めるべきでないもの）
- パイプラインタイプごとの推奨ワークフロー（ソフトウェア/研究/ゲーム）
- ドキュメントファイルの YAML ヘッダー規約
- 自動チェックのスケッチ

## 関連 Skill（本 Skill の代わりにいつ使用するか？）

| Skill | いつ使用するか |
|---|---|
| **`project-onboarding`** | 外部の既存リポジトリを自身のシステムに取り込む場合 |
| Project bootstrapper（利用可能な場合） | 既存のパイプライン内に新しいプロジェクトを作成する場合（新規構築、改修なし） |
| Pipeline bootstrapper（利用可能な場合） | 完全に新しいパイプラインを作成する場合（稀なケース） |
| System onboarding（利用可能な場合） | 新しいマシンをセットアップする場合 |

**pipeline optimizer** は**改修**を担当し、新規構築や導入は担当しません。Skill コレクションに Skill インデックスがある場合は、一致するブートストラップ Skill を検索してください。

## 相互参照

- 詳細参照: `references/optimal-project-structure.md`（本 Skill フォルダ内）
- Anthropic Claude Code ドキュメント: `https://docs.claude.com/en/docs/claude-code`
- 利用可能な場合: グローバルユーザールール（例: `~/CLAUDE.md` 内の「改修」セクション）およびパイプライン固有のスタック記述

## スコープの選択: パイプライン vs. プロジェクトフォルダ

どのスコープを指しているかが不明確な場合は、**ステップ A の前に確認**してください:

| 手がかり | スコープ |
|---|---|
| 「ソフトウェアパイプライン全体を改善する」 | パイプライン |
| 「ツール X のフォルダをクリーンアップする」 | プロジェクトフォルダ |
| 「中央リリースレジストリを同期する」 | パイプライン（中央資産） |
| 「ゲーム Y の AssetBuilder をリファクタリングする」 | プロジェクトフォルダ |
| 「パイプライン全体にチェック規約を導入する」 | パイプライン |
| 「プロジェクト Z にチェックファイルを作成する」 | プロジェクトフォルダ |

**プロジェクトフォルダスコープ**では、介入の互換性を保つため、親パイプラインの規約も常に簡単に確認してください（ステップ A の拡張）。

---

## 変更履歴

### 1.2.0 (2026-06-13)
- Skill ライブラリでの最初の公開: 個人パス、具体的なパイプライン/プロジェクト名、プライベート Skill への参照を汎用的な例に置き換え。手順自体（6ステップ、アンチパターン、ケーススタディ、チェックリスト）は変更なし

### 1.1.1 (2026-06-01) 以前
- 内部バージョン（公開前のプライベート Skill ディレクトリ）