module-spec-generator

模块规格生成器技能

用途

此技能通过代码分析自动生成全面的模块规格，确保遵循 amplihack 的砖块理念，并支持有效地重新生成模块，同时不破坏系统连接。

使用此技能的时机

• 创建新模块：在实现前生成规格，以明确需求
• 记录现有模块：从可运行代码中提取规格，以供日后参考
• 模块评审：验证规格是否准确反映已实现的契约
• 重构决策：使用规格了解模块边界和依赖关系
• 知识保留：记录专家模式和设计决策

核心理念：砖块与连接点

砖块 = 具有一个明确职责的自包含模块 连接点 = 其他模块可连接到的公共契约（函数、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