<img src="../banner.png" width="100%" alt="pipeline-optimizer banner">

日本語 — 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 ディレクトリ）