module-spec-generator

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Module Spec Generator Skill

模块规范生成器Skill

Purpose

用途

This skill automatically generates comprehensive module specifications from code analysis, ensuring adherence to amplihack's brick philosophy and enabling effective module regeneration without breaking system connections.

该Skill可通过代码分析自动生成全面的模块规范，确保符合amplihack的brick哲学，并能在不破坏系统连接的情况下高效地重新生成模块。

When to Use This Skill

使用场景

Creating new modules: Generate specs before implementation to clarify requirements
Documenting existing modules: Extract specifications from working code for future reference
Module reviews: Verify specs accurately represent implemented contracts
Refactoring decisions: Use specs to understand module boundaries and dependencies
Knowledge preservation: Document expert patterns and design decisions

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

Core Philosophy: Bricks & Studs

核心理念：Bricks & Studs

Brick = Self-contained module with ONE clear responsibility Stud = Public contract (functions, API, data models) others connect to Regeneratable = Can be rebuilt from specification without breaking connections

A good spec enables rebuilding ANY module independently while preserving its connection points.

Brick = 具有单一明确职责的独立模块 Stud = 供其他模块连接的公共契约（函数、API、数据模型） Regeneratable = 可根据规范重新构建且不破坏连接

优质的规范允许在保留连接点的前提下独立重建任意模块。

Specification Template

规范模板

Every module specification includes these sections:

每个模块规范包含以下部分：

1. Module Overview

1. 模块概述

undefined

undefined

[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.

undefined

该模块如何体现brick原则和简洁性。

undefined

2. Public Contract (The "Studs")

2. 公共契约（即"Studs"）

undefined

undefined

Public Interface

公共接口

Functions

函数

function_name(param: Type) -> ReturnType

Brief description of what it does.

function_name(param: Type) -> ReturnType

简要描述功能。

Classes/Data Models

类/数据模型

```
ClassName
```
- Fields: list with types
- Key methods: list

```
ClassName
```
- 字段：带类型的列表
- 关键方法：列表

Constants/Enums

常量/枚举

Important module-level constants and their purposes.

undefined

重要的模块级常量及其用途。

undefined

3. Dependencies

3. 依赖项

undefined

undefined

Dependencies

依赖项

External Dependencies

外部依赖

```
library_name
```
(version): What it's used for

```
library_name
```
（版本）：用途说明

Internal Dependencies

内部依赖

```
module_path
```
: How this module depends on it

```
module_path
```
：该模块如何依赖它

NO External Dependencies (Best Case)

无外部依赖（最佳情况）

Pure Python, standard library only.

undefined

纯Python，仅使用标准库。

undefined

4. Module Structure

4. 模块结构

undefined

undefined

Module Structure

模块结构


module_name/
├── **init**.py # Public interface via **all**
├── core.py # Main implementation
├── models.py # Data models (if needed)
├── utils.py # Internal utilities
├── tests/
│ ├── **init**.py
│ ├── test_core.py # Main functionality tests
│ ├── test_models.py # Data model tests (if needed)
│ └── fixtures/
│ └── sample_data.json
└── examples/
└── basic_usage.py # Usage examples

undefined


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 # 使用示例

undefined

5. Test Requirements

5. 测试要求

undefined

undefined

Test Requirements

测试要求

Unit Tests

单元测试

Test 1: Purpose and what it verifies
Test 2: ...

测试1：目的及验证内容
测试2：...

Integration Tests (if applicable)

集成测试（如适用）

Test 1: ...

测试1：...

Coverage Goal

覆盖率目标

Target test coverage percentage (typically 85%+)

undefined

目标测试覆盖率（通常为85%+）

undefined

6. Example Usage

6. 使用示例

undefined

undefined

Example Usage

使用示例

python

from module_name import PublicFunction, DataModel

python

from module_name import PublicFunction, DataModel

Usage example 1

示例1

result = PublicFunction(input_data)

Usage example 2

示例2

model = DataModel(field1="value", field2=123)

```

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)
Identify the single core responsibility
Note architectural patterns used (classes, functions, mixins, etc.)

阅读所有模块文件（重点关注
```
__init__.py
```
和核心实现）
确定单一核心职责
记录使用的架构模式（类、函数、混合类等）

Step 2: Extract Public Contract

步骤2：提取公共契约

List all exports in
```
__all__
```
or equivalent
Document function signatures with full type hints
Identify data structures (classes, NamedTuple, dataclass)
Extract constants and their meanings
Include docstrings for each public item

列出
```
__all__
```
或等效方式导出的所有内容
记录带有完整类型提示的函数签名
识别数据结构（类、NamedTuple、dataclass）
提取常量及其含义
包含每个公共项的文档字符串

Step 3: Map Dependencies

步骤3：映射依赖项

Scan imports at module level
Categorize:
- Standard library (good - include version constraints)
- External packages (list version requirements)
- Internal modules (note the module path)
Identify circular dependencies (red flag)

扫描模块级别的导入
分类：
- 标准库（推荐 - 包含版本约束）
- 外部包（列出版本要求）
- 内部模块（记录模块路径）
识别循环依赖（危险信号）

Step 4: Analyze Module Structure

步骤4：分析模块结构

Map file organization
Identify what goes in each file
Note test fixtures and examples

映射文件组织方式
确定每个文件的用途
记录测试夹具和示例

Step 5: Identify Test Requirements

步骤5：确定测试要求

What behaviors MUST be tested
What edge cases exist
What integration points need coverage
Suggest coverage target

哪些行为必须测试
存在哪些边缘情况
哪些集成点需要覆盖
建议覆盖率目标

Step 6: Generate Spec Document

步骤6：生成规范文档

Create Specs/[module-name].md
Fill in all sections using analysis
Include example code
Verify spec allows module regeneration

创建Specs/[module-name].md
使用分析结果填充所有章节
包含示例代码
验证规范是否允许模块重新生成

Usage Examples

使用示例

Example 1: Generate Spec for New Module

示例1：为新模块生成规范


User: I'm creating a new authentication module.
Generate a spec that ensures it follows brick philosophy.

Claude:

1. Interviews user about module purpose, public functions, dependencies
2. Analyzes similar modules in codebase
3. Generates comprehensive spec with:
   - Clear single responsibility
   - Public contract defining studs
   - Test requirements
   - Example implementations
4. Saves to Specs/authentication.md


用户：我正在创建一个新的认证模块。
生成符合brick哲学的规范。

Claude：

1. 与用户沟通模块用途、公共函数、依赖项
2. 分析代码库中的类似模块
3. 生成全面的规范，包括：
   - 明确的单一职责
   - 定义Studs的公共契约
   - 测试要求
   - 示例实现
4. 保存至Specs/authentication.md

Example 2: Document Existing Module

示例2：记录现有模块


User: Generate a spec for the existing caching module.

Claude:

1. Analyzes .claude/tools/amplihack/caching/ directory
2. Extracts **all** exports
3. Documents public functions with signatures
4. Maps dependencies
5. Identifies test requirements
6. Creates Specs/caching.md
7. Offers to verify spec matches implementation


用户：为现有的缓存模块生成规范。

Claude：

1. 分析.claude/tools/amplihack/caching/目录
2. 提取`__all__`中的所有导出内容
3. 记录带有签名的公共函数
4. 映射依赖项
5. 确定测试要求
6. 创建Specs/caching.md
7. 提供验证规范与实现是否匹配的服务

Example 3: Verify Module Spec Accuracy

示例3：验证模块规范的准确性


User: Check if the existing session management spec
accurately describes the implementation.

Claude:

1. Reads Specs/session-management.md
2. Analyzes actual code in .claude/tools/amplihack/session/
3. Compares:
   - Public contract (functions, signatures)
   - Dependencies listed
   - Test coverage
4. Reports discrepancies
5. Suggests spec updates if needed


用户：检查现有的会话管理规范
是否准确描述了实现内容。

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)

阅读模块中的所有Python文件
识别
```
__all__
```
或等效的公共接口
提取所有公共函数签名
记录所有带字段和方法的公共类
列出模块级常量
映射所有导入（外部和内部）

Philosophy Verification

理念验证

Specification Quality

规范质量

Template for Module Specs

模块规范模板

markdown

undefined

markdown

undefined

[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")

公共接口（即"Studs"）

Functions

函数

python

def primary_function(param: Type) -> ReturnType:
    """Brief description.

    Args:
        param: Description with constraints

    Returns:
        Description of return value
    """

python

def primary_function(param: Type) -> ReturnType:
    """简要描述。

    参数：
        param：带约束的描述

    返回：
        返回值描述
    """

Classes

类

python

class DataModel:
    """Brief description of responsibility.

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

python

class DataModel:
    """职责的简要描述。

    属性：
        field1 (Type)：描述
        field2 (Type)：描述
    """

Constants

常量

```
CONSTANT_NAME
```
: Description and usage

```
CONSTANT_NAME
```
：描述及用途

Dependencies

依赖项

External

外部

None - pure Python standard library

无 - 纯Python标准库

Internal

内部

```
.models
```
: Data structures
```
.utils
```
: Shared utilities

```
.models
```
：数据结构
```
.utils
```
：共享工具函数

Module Structure

模块结构

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

module_name/
├── __init__.py       # 通过__all__导出
├── core.py          # 实现代码
├── models.py        # 数据模型
├── utils.py         # 工具函数
├── tests/
│   └── test_core.py
└── examples/
    └── usage.py

Test Requirements

测试要求

Core Functionality Tests

核心功能测试

✅ Test primary_function with valid input
✅ Test error handling with invalid input
✅ Test edge cases

✅ 测试primary_function的有效输入
✅ 测试无效输入的错误处理
✅ 测试边缘情况

Contract Verification

契约验证

✅ All exported items in all work
✅ Type hints match actual behavior
✅ Return values match documentation

✅
```
__all__
```
中的所有导出项均可正常工作
✅ 类型提示与实际行为匹配
✅ 返回值与文档描述一致

Coverage Target

覆盖率目标

85%+ line coverage

85%+ 行覆盖率

Example Usage

使用示例

python

from module_name import primary_function, DataModel

python

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)

undefined

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

undefined

Regeneration Notes

重生成说明

This module can be rebuilt from this specification while maintaining:

✅ Public contract (all "studs" preserved)
✅ Dependencies (same external/internal deps)
✅ Test interface (same test requirements)
✅ Module structure (same file organization)

undefined

可根据本规范重建该模块，同时保持：

✅ 公共契约（所有"Studs"保留）
✅ 依赖项（相同的外部/内部依赖）
✅ 测试接口（相同的测试要求）
✅ 模块结构（相同的文件组织）

undefined

Output Location

输出位置

Specifications are saved to:

Specs/[module-name].md

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

规范保存至：

Specs/[module-name].md

这样可将所有模块规范集中存储在一个易于查找的位置。

Integration with Builder Agent

与Builder Agent的集成

After spec generation, the Builder Agent can:

Read the specification
Implement the module exactly as specified
Verify implementation matches spec
Run tests defined in spec
Regenerate modules when requirements change

生成规范后，Builder Agent可：

读取规范
完全按照规范实现模块
验证实现是否符合规范
运行规范中定义的测试
当需求变化时重新生成模块

Quality Checks

质量检查

After generating a spec, verify:

Can someone rebuild the module from this spec?
- Yes = spec is complete
- No = add missing details
Does every exported function have a clear purpose?
- Yes = public interface is clear
- No = combine or clarify functions
Are all dependencies justified?
- Yes = move forward
- No = remove or replace with simpler approach
Would this prevent breaking other modules?
- Yes = studs are well-defined
- No = clarify connection points

生成规范后，需验证：

他人能否根据本规范重建模块？
- 是 = 规范完整
- 否 = 补充缺失细节
每个导出函数是否都有明确的用途？
- 是 = 公共接口清晰
- 否 = 合并或明确函数
所有依赖项是否合理？
- 是 = 继续推进
- 否 = 移除或替换为更简单的方案
这是否能避免破坏其他模块？
- 是 = Studs定义明确
- 否 = 明确连接点

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

undefined

优质的模块规范需满足：

单一、明确的职责
完整的公共接口文档
明确的依赖项列表
切合实际的测试要求
可运行的代码示例
他人可根据其重建模块
重生成时保留所有连接
遵循brick哲学
无过度设计或推测
重生成时不破坏系统

undefined