software-planner

安全ルール

_shared/core/safety-rules.md を参照してください。すべての安全ルールは共有レイヤーから読み込み、スキル間で重複して管理することを避けます。

クイックコマンド

コマンド	説明
/planner research <topic>	対象分野を調査します
/planner design <project>	システムアーキテクチャを設計します
/planner modules	モジュール仕様を生成します
/planner docs	バイリンガルドキュメントを作成します
/planner verify	検証チェックリストを実行します

ソフトウェア開発プランナー

確立された内部プロジェクトのパターンに従い、CLI、GUI、Web インターフェースを備えた Python ソフトウェアを計画・実装するための一連のワークフローです。

開発前の計画

ステップ 1：分野の調査

コードを書く前に、徹底的な調査を行います。

1. 学術文献の検索

   • Google Scholar、CNKI、IEEE、ACM で関連論文を検索します
   • 主要な PDF をダウンロードし、プロジェクトルートの pdf/ ディレクトリに保存します
   • 中核となる概念や手法を抽出します
   • 評価基準と指標を特定します

2. 既存ソリューションの分析

   • GitHub で類似プロジェクトを検索します
   • 機能の不足点と改善の機会を特定します
   • UI/UX のパターンとアーキテクチャ上の決定事項を記録します

3. 要件の統合

   • 学術的な知見と実務上のニーズを組み合わせます
   • 引用情報を含めて機能要件を定義します
   • 非機能要件（パフォーマンス、ユーザビリティ）を定めます

ステップ 2：アーキテクチャ設計

実装の前にシステムを設計します。

Software Name (v1.0)
├── Core Features (from research)
│   ├── Feature 1: [description with citation]
│   ├── Feature 2: [description with citation]
│   └── Feature 3: [description with citation]
├── Data Models
│   ├── Model 1: fields, relationships
│   └── Model 2: fields, relationships
├── Algorithms
│   ├── Algorithm 1: input, output, complexity
│   └── Algorithm 2: input, output, complexity
└── User Interfaces
    ├── CLI: commands, flags, arguments
    ├── GUI: windows, panels, controls
    └── Web: routes, templates, API endpoints

ステップ 3：モジュール仕様

各モジュールの責任範囲と目標サイズを明確に定義します。cli.py モジュールはコマンドライン引数の解析とルーティングを担当し、約 100 行を目標とします。gui.py モジュールは PySide6 のウィンドウ、コントロール、イベントハンドラーを提供し、約 200 行を目標とします。app.py モジュールは Flask のルートと API エンドポイントを含み、約 100 行を目標とします。core.py モジュールはビジネスロジック、アルゴリズム、データモデルを実装し、約 200 行を目標とします。api.py モジュールは ToolResult を使用する統合 Python API を提供し、約 100 行を目標とします。全モジュール合計で 500 行以上を目標とします。

インターフェース要件

CLI（コマンドラインインターフェース）

統一されたフラグの規約に従います。

import argparse

def main():
    parser = argparse.ArgumentParser(
        prog="softwarename",
        description="Software description",
        formatter_class=argparse.RawDescriptionHelpFormatter,
    )
    
    # Unified flags (required)
    parser.add_argument("-V", "--version", action="version", version=f"softwarename {__version__}")
    parser.add_argument("-v", "--verbose", action="store_true", help="Verbose output")
    parser.add_argument("-o", "--output", help="Output path")
    parser.add_argument("--json", action="store_true", dest="json_output", help="Output as JSON")
    parser.add_argument("-q", "--quiet", action="store_true", help="Suppress output")
    
    # Mode selection
    subparsers = parser.add_subparsers(dest="mode")
    
    # GUI mode
    gui_parser = subparsers.add_parser("gui", help="Launch GUI")
    gui_parser.add_argument("--no-web", action="store_true", help="Disable embedded web server")
    
    # Web mode
    web_parser = subparsers.add_parser("web", help="Launch web server")
    web_parser.add_argument("--host", default="127.0.0.1")
    web_parser.add_argument("--port", type=int, default=5000)
    
    # CLI operations
    cli_parser = subparsers.add_parser("cli", help="CLI mode")
    cli_parser.add_argument("input", help="Input file or data")

エントリーポイント（標準パターンに準拠）：ソフトウェアは複数のエントリーポイントをサポートします。デフォルトの呼び出しでは、コンテキストに応じて GUI または Web が起動します。明示的に GUI モードを指定するには softwarename gui を使用します。Web サーバーモードには softwarename web を使用します。CLI モードには softwarename cli <args> を使用します。モジュールを呼び出すには python -m packagename を使用します。

GUI（PySide6 インターフェース）

PySide6 のデフォルトのスタイルを使用します。カスタムカラー、フォント、背景は使用しません。

from PySide6.QtWidgets import (
    QApplication, QMainWindow, QWidget, QVBoxLayout, 
    QHBoxLayout, QPushButton, QLabel, QLineEdit, 
    QComboBox, QSpinBox, QDoubleSpinBox, QTableWidget,
    QTabWidget, QGroupBox, QFileDialog, QMessageBox,
)
from PySide6.QtCore import Qt
import pyqtgraph as pg

class MainWindow(QMainWindow):
    def __init__(self):
        super().__init__()
        self.setWindowTitle("Software Name v1.0")
        self.setMinimumSize(800, 600)
        
        # Central widget with default styling
        central = QWidget()
        self.setCentralWidget(central)
        layout = QVBoxLayout(central)
        
        # Controls in group box
        control_group = QGroupBox("Parameters")
        control_layout = QHBoxLayout(control_group)
        
        # Input controls
        self.input_edit = QLineEdit()
        self.input_edit.setPlaceholderText("Enter input...")
        control_layout.addWidget(QLabel("Input:"))
        control_layout.addWidget(self.input_edit)
        
        # Action buttons
        btn_run = QPushButton("Run")
        btn_run.clicked.connect(self.run_analysis)
        control_layout.addWidget(btn_run)
        
        layout.addWidget(control_group)
        
        # Visualization with pyqtgraph
        self.plot_widget = pg.PlotWidget()
        self.plot_widget.setBackground('w')  # White background for plots
        self.plot_widget.showGrid(x=True, y=True)
        layout.addWidget(self.plot_widget)
        
        # Results table
        self.results_table = QTableWidget()
        self.results_table.setColumnCount(4)
        self.results_table.setHorizontalHeaderLabels(["ID", "Name", "Value", "Score"])
        layout.addWidget(self.results_table)

GUI 設計の原則：GUI の実装では、3 つの原則に従います。1 つ目は、システムのデフォルトカラーとデフォルトフォントのみを使用し、カスタム背景やカスタムスタイルシートは使用せず、デフォルトのスタイルを使うことです。2 つ目は、一貫したレイアウト構成に従うことです。上部にパラメーターを含むコントロールパネル、中央に pyqtgraph を使った可視化領域、下部に結果テーブルまたはログ出力を配置します。3 つ目は、適切なコントロールの種類を選ぶことです。テキスト入力には QLineEdit、数値入力には QSpinBox または QDoubleSpinBox、選択肢には QComboBox、真偽値オプションには QCheckBox、操作には QPushButton を使用します。

Web（Flask インターフェース）

from flask import Flask, render_template, jsonify, request

app = Flask(__name__)

@app.route("/")
def index():
    return render_template("index.html")

@app.route("/api/analyze", methods=["POST"])
def analyze():
    data = request.json
    result = perform_analysis(data)
    return jsonify(result.to_dict())

@app.route("/api/results/<id>")
def get_results(id):
    result = get_stored_result(id)
    return jsonify(result.to_dict())

def run_server(host="127.0.0.1", port=5000):
    print(f"Starting server at http://{host}:{port}")
    app.run(host=host, port=port, debug=False)

ToolResult パターン

すべての API 関数は ToolResult を返す必要があります。

from dataclasses import dataclass, field
from typing import Any, Optional

@dataclass
class ToolResult:
    success: bool
    data: Any = None
    error: Optional[str] = None
    metadata: dict = field(default_factory=dict)

    def to_dict(self) -> dict:
        return {
            "success": self.success,
            "data": self.data,
            "error": self.error,
            "metadata": self.metadata,
        }

サンプルデータの要件

テストとデモ用のサンプルデータを作成します。

データファイルの構成

data/
├── sample_input.json      # Example input data
├── sample_results.json    # Expected output for testing
├── test_cases.json        # Test case definitions
└── reference_data.csv     # Reference/benchmark data

サンプルデータのテンプレート

{
  "description": "Sample input for testing",
  "version": "1.0",
  "cases": [
    {
      "id": "case_001",
      "name": "Basic test case",
      "input": {
        "param1": "value1",
        "param2": 100
      },
      "expected_output": {
        "result": "expected_result",
        "score": 0.95
      }
    }
  ]
}

ドキュメントの構成

README.md（英語）

必須セクションはそれぞれ200語以上です。セクション1では、背景、問題の説明、動機など、プロジェクトの背景を説明します。セクション2では、ユースケース、対象ユーザー、ワークフローを含むアプリケーションシナリオを説明します。セクション3では、CPU、GPU、メモリの要件を含むハードウェア互換性について詳しく説明します。セクション4では、Windows、macOS、Linuxのオペレーティングシステムのサポートについて説明します。セクション5では、Pythonのバージョンと必須パッケージを含む依存関係を列挙します。セクション6では、pipでのインストール、ソースからのインストール、設定手順を説明します。セクション7では、CLIコマンド、GUIの操作、Webインターフェースを含む使用方法を説明します。セクション8では、プレースホルダーと説明を添えてスクリーンショットを掲載します。セクション9では、GPLv3の記述を含むライセンス情報を説明します。

README_CN.md（中国語）

英語版と同じ構成で、次のように翻訳されています。セクション1では 项目背景（プロジェクトの背景）を扱います。セクション2では 应用场景（アプリケーションシナリオ）を扱います。セクション3では 兼容硬件（ハードウェア互換性）を扱います。セクション4では 操作系统（オペレーティングシステム）を扱います。セクション5では 依赖环境（依存環境）を扱います。セクション6では 安装过程（インストール）を扱います。セクション7では 使用方法（使用方法）を扱います。セクション8では 运行截图（スクリーンショット）を扱います。セクション9では 授权协议（ライセンス）を扱います。

README テンプレート

README テンプレートは、ドキュメントを構成するための形式を提供します。十分な詳細を確保するため、各セクションには少なくとも200語を含めてください。「プロジェクトの背景」セクションでは、学術的な背景や実用上の必要性も含め、ソフトウェアの背景、問題、動機を説明します。「アプリケーションシナリオ」セクションでは、具体的なユースケース、対象ユーザー、一般的なワークフローを説明します。「ハードウェア互換性」セクションでは、CPU要件、必要に応じたGPU要件、メモリ要件、ストレージ要件を説明します。「オペレーティングシステム」セクションでは、Windows、macOS、Linuxのサポート状況と、具体的なバージョン要件を説明します。「依存関係」セクションでは、Pythonのバージョン要件、バージョン制約付きの主要な依存関係、オプションの依存関係を列挙します。「インストール」セクションでは、pip、conda、ソースからのインストール方法を、手順に沿って説明します。「使用方法」セクションでは、CLIの例、GUIの操作方法、Webインターフェースの使い方を示します。「スクリーンショット」セクションでは、GUIとWebインターフェースの画像を掲載します。「ライセンス」セクションでは、GPLv3を明記し、LICENSE ファイルを参照します。

プロジェクトのファイル構成

project_name/
├── pyproject.toml          # Package configuration
├── requirements.txt        # Dependencies list
├── LICENSE                 # GPLv3 license
├── README.md               # English documentation
├── README_CN.md            # Chinese documentation
├── MANIFEST.in             # Package manifest
├── upload_pypi.sh          # PyPI upload script (Unix)
├── upload_pypi.bat         # PyPI upload script (Windows)
├── pdf/                    # Academic reference papers
│   ├── paper1.pdf
│   └── paper2.pdf
├── data/                   # Sample data
│   ├── sample_input.json
│   └── test_cases.json
├── images/                 # Screenshots
│   └── placeholder.png
├── tests/                  # Test suite
│   ├── __init__.py
│   ├── conftest.py
│   └── test_core.py
└── packagename/            # Main package
    ├── __init__.py         # Version and exports
    ├── __main__.py         # python -m entry
    ├── cli.py              # CLI implementation
    ├── gui.py              # GUI implementation
    ├── app.py              # Flask web app
    ├── core.py             # Business logic
    └── api.py              # Unified API

使用例

データ分析ツールの計画

/planner research "time series analysis with interactive visualization"
/planner design "TimeViz - time series analysis tool"
/planner modules --interface cli,web
/planner docs --lang zh,en
/planner verify

科学シミュレーションの計画

/planner research "molecular dynamics simulation with GPU acceleration"
/planner design "MolSim" --domain scientific
/planner modules --interface gui,cli

小規模プロジェクトのクイックスタート

/planner design "MyTool" --minimal
/planner modules --single-file

トラブルシューティング

調査フェーズの結果が広範すぎる

• 修正方法：--domain scientific|web|cli|gui フラグで範囲を絞り、最近の論文を対象にするには --year 2024-2026 を追加します。関連性の低い分野を除外するには --exclude-field を使用します。

モジュールの仕様が抽象的すぎる

• 修正方法：APIレベルで分解するには /planner modules --detailed を使用します。各モジュールの擬似コードを生成するには --example を追加します。

ドキュメント生成で空のひな形が作成される

• 修正方法：ドキュメントを生成する前に、モジュール仕様が完成していることを確認します。モジュールのシグネチャから自動入力するには /planner docs --fill を使用します。

インターフェース設計が競合する

• 修正方法：/planner design --resolve を使用して、CLI／GUI／Webインターフェース間の競合を検出し、解決します。

エッジケース

• モノレポの計画：--monorepo フラグを使用すると、依存関係の共有追跡を含む、パッケージごとのモジュール仕様を生成できます。
• レガシーシステムの移行：--migrate-from <old-spec> を指定すると、古いアーキテクチャと新しい計画を比較し、互換性を損なう変更を検出します。
• 多言語プロジェクト：--languages python,rust,typescript を指定すると、複数の言語にまたがるインターフェースの互換性を検証できます。
• リアルタイムシステム：--domain realtime を使用すると、モジュール仕様にレイテンシ予算と並行処理モデルが追加されます。
• 組み込み／制約のある環境：--domain embedded を指定すると、メモリ予算と依存関係のサイズ制限が追加されます。
• 空のプロジェクトのひな形作成：既存のコードがない場合、/planner design <name> --seed を実行すると、アーキテクチャとともに最小限のテンプレートが生成されます。

AIGC 対応の出力

ソフトウェアの計画書は、汎用的なテンプレート文ではなく、具体的な数値と制約を含むプロジェクト固有の内容にしてください。アンチ AIGC 検出ルールの詳細については、rules/anti-aigc.md を参照してください。

主な要件：

• 要件には、「優れたユーザー体験」のような表現ではなく、定量化された制約を含めてください
• モジュールの説明には、行数の目標と依存関係の方向を含めてください
• 技術の選定には、代替案を採用しない理由を含めてください
• 「優れた／堅牢な／強力な」はすべて、測定可能な基準に置き換えてください

バージョン履歴

バージョン	日付	変更内容
1.0.0	2026-04-01	初版。CLI／GUI／Web の計画、学術研究の統合
1.0.1	2026-05-09	安全ルール、例、トラブルシューティング、エッジケースを追加

ルール

• rules/pre-development.md - 調査および計画フェーズ
• rules/interface-design.md - CLI／GUI／Web のパターン
• rules/documentation.md - README の要件
• rules/sample-data.md - テストデータの作成
• rules/anti-aigc.md - ソフトウェア計画のアンチ AIGC 検出ルール

検証チェックリスト

プロジェクトを完了とする前に、以下の項目を確認してください。すべてのモジュールを合わせて、コードが 500 行以上あること。CLI で統一されたフラグ（-V、-v、-o、--json、-q）を使用していること。GUI でカスタムスタイルを使わず、PySide6 のデフォルトスタイルを使用していること。Web インターフェースに REST API があること。すべての関数が ToolResult を返すこと。サンプルデータファイルが data ディレクトリにあること。テストケースが定義されていること。README.md に 200 語以上のセクションが 9 つすべてあること。README_CN.md に 200 語以上のセクションが 9 つすべてあること。学術論文の PDF が pdf/ ディレクトリにあること。GPLv3 の LICENSE ファイルがあること。requirements.txt があること。pyproject.toml が正しく設定されていること。PyPI アップロード用スクリプトがあること。

クイックスタートテンプレート

# Create project structure
mkdir -p project_name/{pdf,data,images,tests,packagename}

# Create required files
touch project_name/{pyproject.toml,requirements.txt,LICENSE,README.md,README_CN.md}
touch project_name/upload_pypi.{sh,bat}

# Create package files
touch project_name/packagename/{__init__.py,__main__.py,cli.py,gui.py,app.py,core.py,api.py}

# Create test files
touch project_name/tests/{__init__.py,conftest.py,test_core.py}

関連項目

• python-project-developer の /python-project — 計画したプロジェクト構成を実装する
• master-architect の /architect design — アーキテクチャを詳細に分解する
• coding-agent-patterns の /agent-patterns — 複数インターフェースのアプリケーション向け統合パターン