module-spec-generator

モジュール仕様生成スキル

目的

このスキルは、コード分析に基づいて包括的なモジュール仕様を自動生成し、amplihack のブリック哲学への準拠を確保するとともに、システムとの接続を損なわずにモジュールを効果的に再生成できるようにします。

このスキルを使用する場面

• 新しいモジュールの作成：実装前に仕様を生成して、要件を明確にします
• 既存モジュールの文書化：動作するコードから仕様を抽出し、今後の参照に備えます
• モジュールのレビュー：仕様が実装済みの契約を正確に表しているか確認します
• リファクタリングの判断：仕様を使って、モジュールの境界と依存関係を把握します
• ナレッジの保持：専門家のパターンと設計上の判断を文書化します

中核となる理念：ブリックとスタッド

ブリック = 明確な責任を 1 つだけ持つ、自己完結型のモジュール スタッド = 他のモジュールが接続する公開契約（関数、API、データモデル） 再生成可能 = 接続を損なわずに、仕様から再構築できます

優れた仕様があれば、接続点を維持しながら、任意のモジュールを単独で再構築できます。

仕様テンプレート

すべてのモジュール仕様には、次のセクションを含めます。

1. モジュールの概要

# [Module Name] Specification

## Purpose
One-sentence description of the module's core responsibility.

## Scope
What this module handles | What it explicitly does NOT handle

## Philosophy Alignment
How this module embodies brick principles and simplicity.

2. 公開契約（「スタッド」）

## Public Interface

### Functions
- `function_name(param: Type) -> ReturnType`
  Brief description of what it does.

### Classes/Data Models
- `ClassName`
  - Fields: list with types
  - Key methods: list

### Constants/Enums
Important module-level constants and their purposes.

3. 依存関係

## Dependencies

### External Dependencies
- `library_name` (version): What it's used for

### Internal Dependencies
- `module_path`: How this module depends on it

### NO External Dependencies (Best Case)
Pure Python, standard library only.

4. モジュール構成

## Module Structure

module_name/ ├── init.py # all を介した公開インターフェース ├── core.py # 主な実装 ├── models.py # データモデル（必要な場合） ├── utils.py # 内部ユーティリティ ├── tests/ │ ├── init.py │ ├── test_core.py # 主な機能のテスト │ ├── test_models.py # データモデルのテスト（必要な場合） │ └── fixtures/ │ └── sample_data.json └── examples/ └── basic_usage.py # 使用例

5. テスト要件

## Test Requirements

### Unit Tests
- Test 1: Purpose and what it verifies
- Test 2: ...

### Integration Tests (if applicable)
- Test 1: ...

### Coverage Goal
Target test coverage percentage (typically 85%+)

6. 使用例

## Example Usage

```python
from module_name import PublicFunction, DataModel

# Usage example 1
result = PublicFunction(input_data)

# Usage example 2
model = DataModel(field1="value", field2=123)

## Step-by-Step Analysis Process

### Step 1: Understand the Module
1. Read all module files (focus on `__init__.py` and core implementations)
2. Identify the single core responsibility
3. Note architectural patterns used (classes, functions, mixins, etc.)

### Step 2: Extract Public Contract
1. List all exports in `__all__` or equivalent
2. Document function signatures with full type hints
3. Identify data structures (classes, NamedTuple, dataclass)
4. Extract constants and their meanings
5. Include docstrings for each public item

### Step 3: Map Dependencies
1. Scan imports at module level
2. Categorize:
   - Standard library (good - include version constraints)
   - External packages (list version requirements)
   - Internal modules (note the module path)
3. Identify circular dependencies (red flag)

### Step 4: Analyze Module Structure
1. Map file organization
2. Identify what goes in each file
3. Note test fixtures and examples

### Step 5: Identify Test Requirements
1. What behaviors MUST be tested
2. What edge cases exist
3. What integration points need coverage
4. Suggest coverage target

### Step 6: Generate Spec Document
1. Create Specs/[module-name].md
2. Fill in all sections using analysis
3. Include example code
4. Verify spec allows module regeneration

## Usage Examples

### Example 1: Generate Spec for New Module

ユーザー：新しい認証モジュールを作成しています。 ブリック哲学に沿った仕様を生成してください。

Claude：

1. モジュールの目的、公開関数、依存関係についてユーザーに質問します
2. コードベース内の類似モジュールを分析します
3. 以下を含む包括的な仕様を生成します：
   • 明確で単一の責任
   • スタッドを定義する公開契約
   • テスト要件
   • 実装例
4. Specs/authentication.md に保存します

### Example 2: Document Existing Module

ユーザー：既存のキャッシュモジュールの仕様を生成してください。

Claude：

1. .claude/tools/amplihack/caching/ ディレクトリを分析します
2. すべてのエクスポートを抽出します
3. 公開関数とシグネチャを文書化します
4. 依存関係を整理します
5. テスト要件を特定します
6. Specs/caching.md を作成します
7. 仕様が実装と一致するか確認することを提案します

### Example 3: Verify Module Spec Accuracy

ユーザー：既存のセッション管理の仕様が 実装を正確に説明しているか確認してください。

Claude：

1. Specs/session-management.md を読みます
2. .claude/tools/amplihack/session/ 内の実際のコードを分析します
3. 以下を比較します：
   • 公開契約（関数、シグネチャ）
   • 記載された依存関係
   • テストカバレッジ
4. 相違点を報告します
5. 必要に応じて仕様の更新を提案します

## Analysis Checklist

### Code Analysis
- [ ] Read all Python files in module
- [ ] Identify `__all__` or equivalent public interface
- [ ] Extract all public function signatures
- [ ] Document all public classes with fields and methods
- [ ] List module-level constants
- [ ] Map all imports (external and internal)

### Philosophy Verification
- [ ] Single clear responsibility
- [ ] No unnecessary abstractions
- [ ] Public interface clear and minimal
- [ ] Dependencies are justified
- [ ] No external dependencies (if possible)
- [ ] Patterns align with amplihack principles

### Specification Quality
- [ ] Spec is complete and precise
- [ ] Code examples are accurate and working
- [ ] Test requirements are realistic
- [ ] Module structure is clear
- [ ] Someone could rebuild module from spec
- [ ] Regeneration preserves all connections

## Template for Module Specs

```markdown
# [Module Name] Specification

## Purpose
[Single sentence describing core responsibility]

## Scope
**Handles**: [What this module does]
**Does NOT handle**: [What is explicitly out of scope]

## Philosophy Alignment
- ✅ Ruthless Simplicity: [How it embodies this]
- ✅ Single Responsibility: [Core job]
- ✅ No External Dependencies: [True/False with reason]
- ✅ Regeneratable: [Yes, module can be rebuilt from this spec]

## Public Interface (The "Studs")

### Functions
```python
def primary_function(param: Type) -> ReturnType:
    """Brief description.

    Args:
        param: Description with constraints

    Returns:
        Description of return value
    """

クラス

class DataModel:
    """Brief description of responsibility.

    Attributes:
        field1 (Type): Description
        field2 (Type): Description
    """

定数

• CONSTANT_NAME：説明と使用方法

依存関係

外部

なし - Python 標準ライブラリのみ

内部

• .models：データ構造
• .utils：共有ユーティリティ

モジュール構成

module_name/
├── __init__.py       # Exports via __all__
├── core.py          # Implementation
├── models.py        # Data models
├── utils.py         # Utilities
├── tests/
│   └── test_core.py
└── examples/
    └── usage.py

テスト要件

中核機能のテスト

• ✅ 有効な入力で primary_function をテストします
• ✅ 無効な入力に対するエラー処理をテストします
• ✅ エッジケースをテストします

契約の検証

• ✅ all 内のすべてのエクスポート項目が動作します
• ✅ 型ヒントが実際の動作と一致します
• ✅ 戻り値がドキュメントと一致します

カバレッジ目標

行カバレッジ 85% 以上

使用例

from module_name import primary_function, DataModel

# Basic usage
result = primary_function(input_data)

# Data model usage
model = DataModel(field1="value", field2=123)
print(model.field1)

再生成時の注意事項

このモジュールは、以下を維持しながら、この仕様から再構築できます。

• ✅ 公開契約（すべての「スタッド」を維持）
• ✅ 依存関係（同じ外部／内部依存関係）
• ✅ テストインターフェース（同じテスト要件）
• ✅ モジュール構成（同じファイル構成）

## Output Location

Specifications are saved to: `Specs/[module-name].md`

This keeps all module specifications in a central, discoverable location.

## Integration with Builder Agent

After spec generation, the Builder Agent can:
1. Read the specification
2. Implement the module exactly as specified
3. Verify implementation matches spec
4. Run tests defined in spec
5. Regenerate modules when requirements change

## Quality Checks

After generating a spec, verify:

1. **Can someone rebuild the module from this spec?**
   - Yes = spec is complete
   - No = add missing details

2. **Does every exported function have a clear purpose?**
   - Yes = public interface is clear
   - No = combine or clarify functions

3. **Are all dependencies justified?**
   - Yes = move forward
   - No = remove or replace with simpler approach

4. **Would this prevent breaking other modules?**
   - Yes = studs are well-defined
   - No = clarify connection points

## Common Pitfalls to Avoid

- **Over-specification**: Don't specify implementation details
- **Under-documentation**: Document WHY, not just WHAT
- **Ambiguous contracts**: Be precise about inputs/outputs
- **Unclear dependencies**: Explicitly list all external/internal deps
- **Missing examples**: Always include working code examples
- **Ignored test requirements**: Tests define contract completeness

## Success Criteria

A good module spec:
- [ ] Single, clear responsibility
- [ ] Complete public interface documentation
- [ ] Explicit dependency list
- [ ] Realistic test requirements
- [ ] Working code examples
- [ ] Someone can rebuild module from it
- [ ] Regeneration preserves all connections
- [ ] Follows brick philosophy
- [ ] No future-proofing or speculation
- [ ] Regeneratable without breaking system