Back to Details

philosophy-compliance-workflow

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Philosophy Compliance Workflow Skill

哲学合规工作流Skill

Purpose

目标

Systematic philosophy compliance review that ensures all code and architecture aligns with amplihack's core principles: ruthless simplicity, brick philosophy, and Zen-like minimalism. This skill validates that implementations serve clear purposes without unnecessary complexity.
通过系统性的哲学合规审查，确保所有代码和架构符合amplihack的核心原则：极致简洁、Brick哲学和禅意极简主义。本Skill验证实现是否服务于明确的目标，无不必要的复杂性。

When to Use This Skill

何时使用本Skill

USE FOR:
  • Architecture reviews before implementation
  • Code reviews for philosophy alignment
  • Refactoring validation (did we actually simplify?)
  • Module design verification
  • Pre-merge philosophy checks
  • Identifying over-engineering and complexity creep
AVOID FOR:
  • Functional bug fixes (not philosophy issues)
  • Performance optimization alone
  • Documentation updates
  • Pure syntax/style issues
适用场景：
  • 落地前的架构评审
  • 代码的哲学一致性评审
  • 重构验证（是否真正实现了简化？）
  • 模块设计验证
  • 合并前的哲学合规检查
  • 识别过度设计和复杂性蔓延
不适用场景：
  • 功能性bug修复（非哲学问题）
  • 仅性能优化
  • 文档更新
  • 纯语法/风格问题

Core Philosophy Principles

核心哲学原则

The Zen of Simple Code

简洁代码的禅道

  • Each line serves a clear purpose without embellishment
  • As simple as possible, but no simpler
  • Complex systems from simple, well-defined components
  • Handle what's needed now, not hypothetical futures
  • 每一行代码都有明确的用途，无冗余修饰
  • 尽可能简单，但不能过于简化
  • 由简单、定义清晰的组件构建复杂系统
  • 处理当下所需，而非假设性的未来需求

The Brick Philosophy

Brick哲学

  • A brick = Self-contained module with ONE clear responsibility
  • A stud = Public contract (functions, API, data model) others connect to
  • Regeneratable = Can be rebuilt from spec without breaking connections
  • Isolated = All code, tests, fixtures inside the module's folder
  • 一个Brick = 具有单一明确职责的独立模块
  • 一个Stud = 供其他模块连接的公共契约（函数、API、数据模型）
  • 可再生 = 可根据规范重建，且不破坏现有连接
  • 隔离性 = 所有代码、测试、 fixtures 都在模块目录内

Ruthless Simplicity

极致简洁

  • Start with the simplest solution that works
  • Add complexity only when justified
  • Question every abstraction
  • Code you don't write has no bugs
  • 从最简单的可行方案入手
  • 仅在有充分理由时才增加复杂性
  • 质疑每一个抽象层
  • 未编写的代码不会有bug

Review Process

审查流程

Step 1: Scope Identification

步骤1：范围确定

Identify what to review:
  • Single module, multiple modules, or full architecture
  • Recent changes or complete codebase
  • Specific complexity concerns or general review
Questions to ask:
  • What triggered this review?
  • What are the main concerns?
  • What's the expected outcome?
明确审查对象：
  • 单个模块、多个模块或完整架构
  • 近期变更或完整代码库
  • 特定复杂性问题或全面评审
需提出的问题：
  • 触发本次评审的原因是什么？
  • 主要关注点有哪些？
  • 预期结果是什么？

Step 2: Initial Analysis

步骤2：初步分析

Scan the code structure:
  • Module organization and boundaries
  • Public interfaces (the "studs")
  • Dependencies and coupling
  • Abstraction layers
  • Configuration complexity
Red flags to watch for:
  • Multiple responsibilities in one module
  • Unclear module boundaries
  • Deep inheritance hierarchies
  • Generic "framework" code
  • Future-proofing for hypothetical needs
扫描代码结构：
  • 模块组织与边界
  • 公共接口（即"Stud"）
  • 依赖关系与耦合度
  • 抽象层
  • 配置复杂度
需警惕的红色信号：
  • 单个模块承担多个职责
  • 模块边界不清晰
  • 深层继承层级
  • 通用"框架"代码
  • 针对假设性需求的超前设计

Step 3: Philosophy Questions

步骤3：哲学问题核查

Ask the 5 core questions for each component:
  1. Necessity: "Do we actually need this right now?"
    • Is this solving a real problem today?
    • Or is it future-proofing for "maybe someday"?
  2. Simplicity: "What's the simplest way to solve this problem?"
    • Can we remove layers?
    • Is there a more direct approach?
  3. Modularity: "Can this be a self-contained brick?"
    • Does it have ONE clear responsibility?
    • Are the connection points (studs) obvious?
  4. Regenerability: "Can AI rebuild this from a specification?"
    • Is the contract clear enough?
    • Are dependencies well-defined?
  5. Value: "Does the complexity add proportional value?"
    • What would break if we simplified this?
    • Is the trade-off justified?
针对每个组件提出5个核心问题：
  1. 必要性："我们现在真的需要这个吗？"
    • 这是否在解决当下的实际问题？
    • 还是在为"也许某天会用到"做超前设计？
  2. 简洁性："解决这个问题的最简单方式是什么？"
    • 我们能否移除某些层级？
    • 是否有更直接的实现方式？
  3. 模块化："这能否成为一个独立的Brick？"
    • 它是否只有单一明确的职责？
    • 连接点（Stud）是否清晰明确？
  4. 可再生性："AI能否根据规范重建这个组件？"
    • 契约是否足够清晰？
    • 依赖关系是否定义明确？
  5. 价值性："复杂性带来的价值是否成正比？"
    • 如果我们简化这部分，会有什么功能受影响？
    • 这种权衡是否合理？

Step 4: Identify Violations

步骤4：识别违规情况

Categorize issues by severity:
CRITICAL (Must Fix):
  • Multiple responsibilities in one module
  • Circular dependencies
  • Unclear public contracts
  • Non-regeneratable designs
  • Tight coupling preventing module replacement
WARNING (Should Fix):
  • Premature optimizations
  • Excessive configuration options
  • Unnecessary abstractions
  • Generic "framework" patterns
  • Future-proofing without current need
SUGGESTION (Consider):
  • Opportunities for simplification
  • Alternative approaches with fewer dependencies
  • Ways to flatten abstraction layers
  • Module boundary improvements
按严重程度分类问题：
CRITICAL（必须修复）：
  • 单个模块承担多个职责
  • 循环依赖
  • 公共契约不清晰
  • 不可再生的设计
  • 耦合过紧导致模块无法替换
WARNING（应该修复）：
  • 过早优化
  • 过多配置选项
  • 不必要的抽象
  • 通用"框架"模式
  • 无当前需求的超前设计
SUGGESTION（建议考虑）：
  • 简化的机会
  • 依赖更少的替代方案
  • 扁平化抽象层的方法
  • 模块边界的改进方向

Step 5: Generate Review Report

步骤5：生成评审报告

Create structured review output:
markdown
undefined
创建结构化的评审输出：
markdown
undefined

Philosophy Compliance Review: [Component Name]

哲学合规评审：[组件名称]

Overall Score: [A/B/C/D/F]

总体评分：[A/B/C/D/F]

Summary

摘要

[One paragraph overview of findings]
[一段关于评审发现的概述]

Strengths (What Aligns)

优势（符合原则的部分）

  • [Philosophy-aligned patterns identified]
  • [Well-implemented brick designs]
  • [Clear simplicity examples]
  • [识别出的符合哲学的模式]
  • [实现良好的Brick设计]
  • [简洁性的优秀示例]

Concerns (Warnings)

关注点（警告）

  • [Complexity that should be addressed]
  • [Borderline philosophy violations]
  • [Opportunities for improvement]
  • [需要处理的复杂性问题]
  • [接近违规的情况]
  • [改进机会]

Violations (Critical Issues)

违规情况（严重问题）

  • [Clear departures from philosophy]
  • [Must-fix problems]
  • [Blocking issues for philosophy compliance]
  • [明显偏离哲学原则的情况]
  • [必须修复的问题]
  • [阻碍哲学合规的关键问题]

Recommendations

建议

Immediate Actions (Critical)

立即行动（严重问题）

  1. [Specific fix required with rationale]
  2. [Another critical fix]
  1. [具体修复方案及理由]
  2. [另一个严重修复需求]

Structural Improvements (Important)

架构改进（重要）

  1. [Module boundary adjustments]
  2. [Decoupling suggestions]
  1. [模块边界调整建议]
  2. [解耦建议]

Simplification Opportunities (Good to Have)

简化机会（值得做）

  1. [Ways to reduce complexity]
  2. [Abstraction removal suggestions]
  1. [降低复杂性的方法]
  2. [移除抽象层的建议]

Regeneration Assessment

再生性评估

Can AI rebuild these components from specifications?
  • Module A: [Ready/Needs Work] - [Specific reason]
  • Module B: [Ready/Needs Work] - [Specific reason]
What's blocking regeneration:
  • [List specific issues preventing clear AI regeneration]
AI能否根据规范重建这些组件？
  • 模块A：[已就绪/需改进] - [具体原因]
  • 模块B：[已就绪/需改进] - [具体原因]
阻碍再生的因素：
  • [列出阻碍AI清晰重建的具体问题]

Philosophy Alignment Score

哲学一致性评分

  • Ruthless Simplicity: [0-10]/10 - [Rationale]
  • Brick Philosophy: [0-10]/10 - [Rationale]
  • Zen Minimalism: [0-10]/10 - [Rationale]
Overall: [Score]/10
undefined
  • 极致简洁：[0-10]/10 - [评分理由]
  • Brick哲学：[0-10]/10 - [评分理由]
  • 禅意极简：[0-10]/10 - [评分理由]
总体评分：[分数]/10
undefined

Step 6: Provide Actionable Guidance

步骤6：提供可执行指导

For each violation, provide:
  • Clear explanation of the problem
  • Why it violates philosophy
  • Specific fix recommendation
  • Expected improvement from fix
  • Priority (Critical/Important/Nice-to-have)
Example:
Issue: SessionManager class has 8 different responsibilities
Violation: Breaks single responsibility (brick philosophy)
Fix: Split into:
  - SessionStore (persistence only)
  - SessionValidator (validation only)
  - SessionLifecycle (creation/expiry only)
Impact: Each brick becomes regeneratable and testable independently
Priority: Critical
针对每个违规情况，需提供：
  • 问题的清晰解释
  • 违反哲学原则的原因
  • 具体的修复建议
  • 修复后的预期改进
  • 优先级（严重/重要/值得做）
示例：
问题：SessionManager类承担8种不同职责
违规：违反单一职责原则（Brick哲学）
修复方案：拆分为：
  - SessionStore（仅负责持久化）
  - SessionValidator（仅负责验证）
  - SessionLifecycle（仅负责创建/过期）
影响：每个Brick可独立再生和测试
优先级：严重

Philosophy Scoring Rubric

哲学评分标准

Ruthless Simplicity (0-10)

极致简洁（0-10分）

  • 10: Every component serves clear purpose, minimal complexity
  • 8-9: Generally simple with minor complexity creep
  • 6-7: Some unnecessary abstractions or future-proofing
  • 4-5: Significant over-engineering present
  • 0-3: Complex beyond necessity, hard to understand
  • 10分：每个组件用途明确，复杂度极低
  • 8-9分：总体简洁，仅存在轻微的复杂性蔓延
  • 6-7分：存在一些不必要的抽象或超前设计
  • 4-5分：存在明显的过度设计
  • 0-3分：复杂度远超需求，难以理解

Brick Philosophy (0-10)

Brick哲学（0-10分）

  • 10: All modules self-contained with clear single responsibility
  • 8-9: Most modules follow brick pattern with minor coupling
  • 6-7: Some unclear boundaries or multiple responsibilities
  • 4-5: Significant coupling and unclear contracts
  • 0-3: Monolithic or tightly coupled, not regeneratable
  • 10分：所有模块都是独立的，具有明确的单一职责
  • 8-9分：大多数模块遵循Brick模式，仅存在轻微耦合
  • 6-7分：部分模块边界不清晰或承担多个职责
  • 4-5分：耦合严重，契约不清晰
  • 0-3分：单体化或耦合过紧，不可再生

Zen Minimalism (0-10)

禅意极简（0-10分）

  • 10: Embraces simplicity, handles only current needs
  • 8-9: Mostly minimal with some extra features
  • 6-7: Some hypothetical futures addressed unnecessarily
  • 4-5: Considerable future-proofing and "just in case" code
  • 0-3: Over-engineered for "maybe someday" scenarios
  • 10分：完全拥抱简洁，仅处理当前需求
  • 8-9分：总体极简，仅存在少量额外功能
  • 6-7分：存在不必要的针对假设性未来的处理
  • 4-5分：大量超前设计和"以防万一"的代码
  • 0-3分：为"也许某天会用到"的场景过度设计

Overall Grade

总体等级

  • A (9-10): Excellent philosophy alignment
  • B (7-8): Good with minor improvements needed
  • C (5-6): Acceptable but needs attention
  • D (3-4): Poor alignment, significant refactoring needed
  • F (0-2): Critical philosophy violations throughout
  • A（9-10分）：哲学一致性极佳
  • B（7-8分）：良好，仅需少量改进
  • C（5-6分）：可接受，但需关注
  • D（3-4分）：一致性差，需要大量重构
  • F（0-2分）：存在全面的严重哲学违规

Green Patterns (Examples of Good Design)

优秀模式（良好设计示例）

Philosophy-Aligned Designs:
  • Single-responsibility modules with clear purpose
  • Self-contained directories with all code and tests
  • Obvious public interfaces (studs) for connections
  • Direct, straightforward implementations
  • Minimal dependencies (preferring standard library)
Example: Good Brick Module
authentication/
├── __init__.py        # Exports: authenticate, validate_token
├── core.py           # Implementation (one responsibility)
├── models.py         # User, Token (clear data models)
├── tests/
│   └── test_core.py  # Comprehensive tests
└── README.md         # Regeneration specification

Public Contract (Studs):
- authenticate(username, password) -> Token
- validate_token(token) -> User

One Responsibility: Authentication only (not authorization, not user management)
Regeneratable: Yes, from README.md specification
符合哲学的设计：
  • 具有明确目标的单一职责模块
  • 包含所有代码和测试的独立目录
  • 连接用的清晰公共接口（Stud）
  • 直接、直观的实现
  • 依赖极少（优先使用标准库）
示例：优秀的Brick模块
authentication/
├── __init__.py        # 导出：authenticate, validate_token
├── core.py           # 实现（单一职责）
├── models.py         # User, Token（清晰的数据模型）
├── tests/
│   └── test_core.py  # 全面测试
└── README.md         # 再生规范

公共契约（Stud）：
- authenticate(username, password) -> Token
- validate_token(token) -> User

单一职责：仅负责认证（不负责授权，不负责用户管理）
可再生：是，可根据README.md规范重建

Red Patterns (Examples to Avoid)

不良模式（需避免的示例）

Philosophy Violations:
  • God objects with multiple responsibilities
  • Abstract base classes without clear justification
  • Complex configuration systems for simple features
  • Generic "flexible" frameworks
  • Premature performance optimizations
Example: Bad Design
user_system/
├── framework.py          # Generic abstraction layer
├── manager.py            # UserManager does everything
├── config/               # Extensive config system
├── plugins/              # Plugin architecture (unused)
└── adapters/             # Future-proofing for other DBs

Problems:
- UserManager handles auth, profile, settings, notifications
- Framework adds complexity without current value
- Plugin system built for "maybe someday"
- Multiple responsibilities, not regeneratable
违反哲学的设计：
  • 承担多个职责的上帝对象
  • 无明确理由的抽象基类
  • 为简单功能设计的复杂配置系统
  • 通用"灵活"框架
  • 过早的性能优化
示例：不良设计
user_system/
├── framework.py          # 通用抽象层
├── manager.py            # UserManager包办一切
├── config/               # 庞大的配置系统
├── plugins/              # 插件架构（未使用）
└── adapters/             # 为其他数据库做超前设计

问题：
- UserManager处理认证、个人资料、设置、通知
- 框架增加了无当前价值的复杂度
- 插件系统是为"也许某天会用到"而构建
- 承担多个职责，不可再生

Integration with Other Workflows

与其他工作流的集成

When to combine philosophy review with:
  • After Builder: Validate implemented code follows philosophy
  • Before Architect: Ensure design specs embrace simplicity
  • During Reviewer: Include philosophy as review criteria
  • With Cleanup: Identify what to simplify/remove
Default workflow position:
  • Architecture Phase: Before implementation starts
  • Code Review Phase: After implementation, before merge
  • Refactoring Phase: Validate simplification efforts
何时将哲学评审与其他工作流结合：
  • Builder之后：验证落地的代码是否符合哲学原则
  • Architect之前：确保设计规范拥抱简洁
  • Reviewer期间：将哲学原则纳入评审标准
  • Cleanup阶段：识别需要简化/移除的内容
默认工作流位置：
  • 架构阶段：落地开始前
  • 代码评审阶段：落地完成后，合并前
  • 重构阶段：验证简化成果

Key Mantras

核心准则

  • "It's easier to add complexity later than to remove it"
  • "Code you don't write has no bugs"
  • "Favor clarity over cleverness"
  • "The best code is often the simplest"
  • "Modules should be bricks: self-contained and regeneratable"
  • "Do we need this NOW, or are we future-proofing?"
  • "What's the simplest thing that could possibly work?"
  • "后续增加复杂度比移除它更容易"
  • "未编写的代码不会有bug"
  • "优先选择清晰而非巧妙"
  • "最好的代码往往是最简单的"
  • "模块应像Brick一样：独立且可再生"
  • "我们现在需要这个，还是在做超前设计？"
  • "最简单的可行方案是什么？"

Common Pitfalls

常见陷阱

Disguised Complexity:
  • "This makes it flexible" → Often means over-engineered
  • "We might need this later" → Future-proofing without current need
  • "This is more generic" → Generic often means complex
  • "Industry best practice" → May not apply to your scale
Philosophy Traps:
  • Adding abstraction layers "just in case"
  • Building frameworks for single use cases
  • Creating plugin systems before needing plugins
  • Optimizing before measuring performance
  • Designing for hypothetical scale
伪装的复杂性：
  • "这让它更灵活" → 通常意味着过度设计
  • "我们以后可能需要这个" → 无当前需求的超前设计
  • "这更通用" → 通用往往意味着复杂
  • "行业最佳实践" → 可能不适用于你的规模
哲学误区：
  • "以防万一"地添加抽象层
  • 为单一用例构建框架
  • 在需要插件前就创建插件系统
  • 未做性能度量就进行优化
  • 为假设性的规模做设计

Success Criteria

成功标准

A successful philosophy review:
  • Identifies all critical philosophy violations
  • Provides actionable fix recommendations
  • Explains why violations matter
  • Scores components objectively
  • Validates regeneration readiness
  • Celebrates philosophy-aligned patterns
  • Guides team toward simpler designs
一次成功的哲学评审需满足：
  • 识别所有严重的哲学违规
  • 提供可执行的修复建议
  • 解释违规的影响
  • 客观评分组件
  • 验证再生就绪性
  • 认可符合哲学的模式
  • 引导团队走向更简洁的设计

Output Artifacts

输出产物

Generated documents:
  • Philosophy review report (markdown)
  • Action items with priorities
  • Before/after comparison (if fixes applied)
  • Regeneration assessment per module
Where to save:
  • ~/.amplihack/.claude/runtime/logs/<session>/philosophy_review_<timestamp>.md
  • Link in commit message if fixes applied
  • Store patterns learned in memory using 
    store_discovery()
    from 
    amplihack.memory.discoveries
生成的文档：
  • 哲学评审报告（markdown格式）
  • 带优先级的行动项
  • 修复前后对比（若已应用修复）
  • 各模块的再生性评估
存储位置：
  • ~/.amplihack/.claude/runtime/logs/<session>/philosophy_review_<timestamp>.md
  • 若应用修复，在提交信息中添加链接
  • 使用
    amplihack.memory.discoveries
    中的
    store_discovery()
    将学到的模式存储到内存中

Remember

谨记

You are the philosophical conscience of the system. Challenge complexity, celebrate simplicity, and ensure every architectural decision moves toward the Zen ideal of elegant, essential software.
Your goal is not perfection - it's continuous improvement toward simpler, clearer, more regeneratable code.
你是系统的哲学良心。挑战复杂性，推崇简洁性，确保每一个架构决策都朝着优雅、本质化软件的禅道理想迈进。
你的目标不是完美——而是持续改进，朝向更简洁、清晰、可再生的代码。