philosophy-compliance-workflow

Philosophy 合规工作流技能

用途

系统化审查 Philosophy 合规性，确保所有代码和架构都符合 amplihack 的核心原则：极致简洁、积木哲学和禅意极简主义。此技能用于验证实现是否服务于明确目的，且没有不必要的复杂性。

何时使用此技能

适用于：

• 实现前的架构审查
• 检查代码是否符合 Philosophy
• 重构验证（我们是否真的简化了？）
• 模块设计验证
• 合并前的 Philosophy 检查
• 识别过度设计和复杂性蔓延

不适用于：

• 功能性错误修复（不属于 Philosophy 问题）
• 单纯的性能优化
• 文档更新
• 纯语法或风格问题

核心 Philosophy 原则

简洁代码之道

• 每一行代码都有明确用途，不做修饰
• 尽可能简单，但不能更简单
• 用简单、定义明确的组件构建复杂系统
• 处理当前所需内容，而非假设的未来需求

积木哲学

• 积木 = 职责明确且仅有一个的自包含模块
• 凸点 = 公共契约（函数、API、数据模型），供其他模块连接
• 可重新生成 = 可根据规范重新构建，且不会破坏连接
• 隔离 = 所有代码、测试和夹具都位于模块文件夹内

极致简洁

• 从可行的最简单方案开始
• 只有在理由充分时才增加复杂性
• 质疑每个抽象
• 不写的代码就没有错误

审查流程

步骤 1：确定范围

确定审查内容：

• 单个模块、多个模块或完整架构
• 最近的更改或整个代码库
• 特定的复杂性问题或一般性审查

要问的问题：

• 是什么触发了这次审查？
• 主要顾虑是什么？
• 预期结果是什么？

步骤 2：初步分析

扫描代码结构：

• 模块组织和边界
• 公共接口（“凸点”）
• 依赖关系和耦合
• 抽象层
• 配置复杂性

需要留意的危险信号：

• 一个模块承担多项职责
• 模块边界不明确
• 深层继承层次
• 通用的“框架”代码
• 为假设的需求做前瞻性设计

步骤 3：Philosophy 问题

针对每个组件提出 5 个核心问题：

1. 必要性：“我们现在真的需要这个吗？”

   • 这是否在解决当下的实际问题？
   • 还是在为“也许有一天”做前瞻性设计？

2. 简洁性：“解决这个问题的最简单方法是什么？”

   • 能否移除一些层？
   • 有没有更直接的方法？

3. 模块化：“能否将其做成自包含的积木？”

   • 它是否只有一个明确的职责？
   • 连接点（凸点）是否清晰？

4. 可重新生成性：“AI 能否根据规范重新构建它？”

   • 契约是否足够清晰？
   • 依赖关系是否定义明确？

5. 价值：“复杂性带来的价值是否与之相称？”

   • 如果简化它，什么会出问题？
   • 这种权衡是否合理？

步骤 4：识别违规项

按严重程度对问题分类：

严重（必须修复）：

• 一个模块承担多项职责
• 循环依赖
• 公共契约不明确
• 无法重新生成的设计
• 紧密耦合导致模块无法替换

警告（应当修复）：

• 过早优化
• 配置选项过多
• 不必要的抽象
• 通用的“框架”模式
• 为当前不需要的内容做前瞻性设计

建议（可以考虑）：

• 简化的机会
• 依赖更少的替代方案
• 扁平化抽象层的方法
• 改进模块边界

步骤 5：生成审查报告

创建结构化审查结果：

# Philosophy Compliance Review: [Component Name]

## Overall Score: [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]

## 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]

### Structural Improvements (Important)

1. [Module boundary adjustments]
2. [Decoupling suggestions]

### Simplification Opportunities (Good to Have)

1. [Ways to reduce complexity]
2. [Abstraction removal suggestions]

## 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]

## Philosophy Alignment Score

- Ruthless Simplicity: [0-10]/10 - [Rationale]
- Brick Philosophy: [0-10]/10 - [Rationale]
- Zen Minimalism: [0-10]/10 - [Rationale]

**Overall: [Score]/10**

步骤 6：提供可执行的指导

对于每项违规，请提供：

• 清晰说明问题
• 说明其为何违背理念
• 具体的修复建议
• 修复后预期的改进
• 优先级（Critical/Important/Nice-to-have）

示例：

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

理念评分标准

极致简洁（0-10）

• 10：每个组件都有明确用途，复杂度最低
• 8-9：整体简洁，只有轻微的复杂度增长
• 6-7：存在一些不必要的抽象或面向未来的设计
• 4-5：存在明显的过度工程
• 0-3：复杂度超出必要程度，难以理解

积木理念（0-10）

• 10：所有模块都自成一体，且职责单一、明确
• 8-9：大多数模块遵循积木模式，耦合较少
• 6-7：有些边界不清晰，或承担多项职责
• 4-5：存在明显的耦合，契约不清晰
• 0-3：模块单体化或紧密耦合，无法重新生成

禅意极简主义（0-10）

• 10：拥抱简单，只处理当前需求
• 8-9：整体精简，但包含少量额外功能
• 6-7：不必要地应对了一些假设的未来需求
• 4-5：存在大量面向未来的设计和“以防万一”的代码
• 0-3：为“也许有一天”而过度工程

总体评分

• A（9-10）：与理念高度契合
• B（7-8）：表现良好，只需少量改进
• C（5-6）：可以接受，但需要关注
• D（3-4）：契合度较差，需要大幅重构
• F（0-2）：存在全面且严重的理念违规

正面模式（优秀设计示例）

符合理念的设计：

• 职责单一、用途明确的模块
• 包含所有代码和测试的自成一体的目录
• 用于连接的、清晰直观的公共接口（连接柱）
• 直接、简单明了的实现
• 尽量减少依赖（优先使用标准库）

示例：优秀的积木模块

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

反面模式（应避免的示例）

违背理念的设计：

• 承担多项职责的上帝对象
• 缺乏明确理由的抽象基类
• 为简单功能设计的复杂配置系统
• 通用的“灵活”框架
• 过早进行性能优化

示例：糟糕的设计

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

与其他工作流集成

何时将理念审查与以下工作结合：

• Builder 之后：验证已实现的代码是否符合理念
• Architect 之前：确保设计规范拥抱简洁
• Reviewer 期间：将理念纳入审查标准
• 与 Cleanup 结合：找出可精简或删除的内容

默认工作流阶段：

• 架构阶段：开始实现之前
• 代码审查阶段：实现之后、合并之前
• 重构阶段：验证精简工作

核心箴言

• “之后增加复杂度，比移除复杂度容易”
• “不写的代码就没有漏洞”
• “清晰胜过巧妙”
• “最好的代码往往是最简单的”
• “模块应该像积木：自成一体且可重新生成”
• “我们现在需要它吗，还是只是在面向未来？”
• “能实现目标的最简单方案是什么？”

常见陷阱

伪装的复杂性：

• “这样更灵活” → 往往意味着过度工程
• “以后可能会需要” → 没有当前需求的面向未来设计
• “这样更通用” → 通用往往意味着复杂
• “行业最佳实践” → 可能不适用于你的规模

理念陷阱：

• “以防万一”而添加抽象层
• 为单一用例构建框架
• 在需要插件之前就创建插件系统
• 未测量性能就进行优化
• 为假设的规模进行设计

成功标准

一次成功的理念审查应：

• 识别所有关键的理念违规
• 提供可执行的修复建议
• 说明违规为何重要
• 客观地为各个组件打分
• 验证是否已准备好重新生成
• 赞扬符合理念的模式
• 引导团队采用更简单的设计

输出产物

生成的文档：

• 理念审查报告（Markdown）
• 按优先级排列的待办事项
• 修复前后对比（如果已应用修复）
• 各模块的重新生成评估

保存位置：

• ~/.amplihack/.claude/runtime/logs/<session>/philosophy_review_<timestamp>.md
• 如果已应用修复，则在提交消息中附上链接
• 使用 amplihack.memory.discoveries 中的 store_discovery() 将学到的模式存入记忆

请记住

你是系统的理念守护者。质疑复杂性，赞扬简洁性，并确保每项架构决策都朝着禅意的理想迈进：打造优雅、精简的软件。

你的目标并非完美，而是持续改进，让代码更简单、更清晰、更易于重新生成。