kaizen:kaizen

Kaizen：持续改进

秉持持续改进的理念——提出小步迭代的改进建议，设计防错方案，遵循既有模式，避免过度设计；自动应用这些原则，以提升质量并保持简洁

概述

持续进行小幅改进。通过设计防错。遵循行之有效的方法。只构建所需内容。

核心原则： 许多小改进胜过一次大改动。在设计阶段预防错误，而不是事后修复。

适用场景

始终适用于：

• 代码实现与重构
• 架构和设计决策
• 流程和工作流改进
• 错误处理与验证

理念： 通过渐进式改进和预防来保证质量，而不是靠大规模投入追求完美。

四大支柱

1. 持续改进（Kaizen）

频繁的小改进会累积成巨大的进步。

原则

渐进优于变革：

• 进行能提升质量的最小可行改动
• 一次只做一项改进
• 每次改动后先验证，再进行下一项
• 通过小胜利积蓄动力

始终让代码变得更好：

• 遇到小问题时就顺手修复
• 工作时进行重构（不超出范围）
• 更新过时的注释
• 发现无用代码时将其删除

迭代式优化：

• 第一版：让它能运行
• 第二轮：让它更清晰
• 第三轮：让它更高效
• 不要试图一次完成这三件事

```typescript // Iteration 1: Make it work const calculateTotal = (items: Item[]) => { let total = 0; for (let i = 0; i < items.length; i++) { total += items[i].price * items[i].quantity; } return total; };

// Iteration 2: Make it clear (refactor) const calculateTotal = (items: Item[]): number => { return items.reduce((total, item) => { return total + (item.price * item.quantity); }, 0); };

// Iteration 3: Make it robust (add validation) const calculateTotal = (items: Item[]): number => { if (!items?.length) return 0;

return items.reduce((total, item) => { if (item.price < 0 || item.quantity < 0) { throw new Error('Price and quantity must be non-negative'); } return total + (item.price * item.quantity); }, 0); };

每个步骤都完整、经过测试且能够正常运行
</Good>

<Bad>
```typescript
// Trying to do everything at once
const calculateTotal = (items: Item[]): number => {
  // Validate, optimize, add features, handle edge cases all together
  if (!items?.length) return 0;
  const validItems = items.filter(item => {
    if (item.price < 0) throw new Error('Negative price');
    if (item.quantity < 0) throw new Error('Negative quantity');
    return item.quantity > 0; // Also filtering zero quantities
  });
  // Plus caching, plus logging, plus currency conversion...
  return validItems.reduce(...); // Too many concerns at once
};

让人难以应对、容易出错、难以验证

实践方法

实现功能时：

1. 从可运行的最简单版本开始
2. 添加一项改进（错误处理、验证等）
3. 测试并验证
4. 如果时间允许，重复上述步骤
5. 不要一开始就试图做到完美

重构时：

• 一次修复一个代码异味
• 每次改进后提交
• 始终保持测试通过
• 达到“足够好”时就停下（避免边际收益递减）

审查代码时：

• 提出渐进式改进建议（而非重写）
• 按优先级排序：关键 → 重要 → 可有可无
• 优先关注影响最大的改动
• 即使不完美，也要接受“比以前更好”

2. Poka-Yoke（防错）

在编译或设计阶段设计能够预防错误的系统，而不是等到运行时再处理。

原则

让错误无法发生：

• 类型系统捕获错误
• 编译器强制执行约定
• 无法表示无效状态
• 尽早捕获错误（在进入生产环境之前）

以安全为导向进行设计：

• 尽早失败，并明确指出
• 提供有帮助的错误消息
• 让正确的路径一目了然
• 让错误的路径难以选择

分层防护：

1. 类型系统（编译时）
2. 验证（运行时，尽早执行）
3. 守卫（前置条件）
4. 错误边界（优雅降级）

类型系统防错

```typescript // Error: string status can be any value type OrderBad = { status: string; // Can be "pending", "PENDING", "pnding", anything! total: number; };

// Good: Only valid states possible type OrderStatus = 'pending' | 'processing' | 'shipped' | 'delivered'; type Order = { status: OrderStatus; total: number; };

// Better: States with associated data type Order = | { status: 'pending'; createdAt: Date } | { status: 'processing'; startedAt: Date; estimatedCompletion: Date } | { status: 'shipped'; trackingNumber: string; shippedAt: Date } | { status: 'delivered'; deliveredAt: Date; signature: string };

// Now impossible to have shipped without trackingNumber

类型系统可防止整类错误
</Good>

<Good>
```typescript
// Make invalid states unrepresentable
type NonEmptyArray<T> = [T, ...T[]];

const firstItem = <T>(items: NonEmptyArray<T>): T => {
  return items[0]; // Always safe, never undefined!
};

// Caller must prove array is non-empty
const items: number[] = [1, 2, 3];
if (items.length > 0) {
  firstItem(items as NonEmptyArray<number>); // Safe
}

函数签名可确保安全

验证防错

```typescript // Error: Validation after use const processPayment = (amount: number) => { const fee = amount * 0.03; // Used before validation! if (amount <= 0) throw new Error('Invalid amount'); // ... };

// Good: Validate immediately const processPayment = (amount: number) => { if (amount <= 0) { throw new Error('Payment amount must be positive'); } if (amount > 10000) { throw new Error('Payment exceeds maximum allowed'); }

const fee = amount * 0.03; // ... now safe to use };

// Better: Validation at boundary with branded type type PositiveNumber = number & { readonly __brand: 'PositiveNumber' };

const validatePositive = (n: number): PositiveNumber => { if (n <= 0) throw new Error('Must be positive'); return n as PositiveNumber; };

const processPayment = (amount: PositiveNumber) => { // amount is guaranteed positive, no need to check const fee = amount * 0.03; };

// Validate at system boundary const handlePaymentRequest = (req: Request) => { const amount = validatePositive(req.body.amount); // Validate once processPayment(amount); // Use everywhere safely };

在边界处验证一次，其他地方即可安全使用
</Good>

#### 守卫与前置条件

<Good>
```typescript
// Early returns prevent deeply nested code
const processUser = (user: User | null) => {
  if (!user) {
    logger.error('User not found');
    return;
  }
  
  if (!user.email) {
    logger.error('User email missing');
    return;
  }
  
  if (!user.isActive) {
    logger.info('User inactive, skipping');
    return;
  }
  
  // Main logic here, guaranteed user is valid and active
  sendEmail(user.email, 'Welcome!');
};

守卫会明确声明并强制执行假设

配置防错

```typescript // Error: Optional config with unsafe defaults type ConfigBad = { apiKey?: string; timeout?: number; };

const client = new APIClient({ timeout: 5000 }); // apiKey missing!

// Good: Required config, fails early type Config = { apiKey: string; timeout: number; };

const loadConfig = (): Config => { const apiKey = process.env.API_KEY; if (!apiKey) { throw new Error('API_KEY environment variable required'); }

return { apiKey, timeout: 5000, }; };

// App fails at startup if config invalid, not during request const config = loadConfig(); const client = new APIClient(config);

在启动时失败，而不是在生产环境中失败
</Good>

#### 实践方法

**设计 API 时：**
- 使用类型约束输入
- 让无效状态无法表示
- 返回 Result<T, E>，而不是抛出异常
- 在类型中记录前置条件

**处理错误时：**
- 在系统边界处进行验证
- 使用守卫检查前置条件
- 尽早失败，并提供清晰的消息
- 记录调试所需的上下文

**配置时：**
- 优先选择必填项，而不是带默认值的可选项
- 在启动时验证所有配置
- 配置无效时应阻止部署
- 不允许不完整的配置

### 3. 标准化工作

遵循既有模式。记录行之有效的方法。让良好实践更容易遵循。
#### 原则

**一致性胜过巧思：**
- 遵循现有代码库的模式
- 不要重新发明已解决的问题
- 只有在新模式显著更好时才采用
- 新模式需团队达成共识

**文档与代码共存：**
- README 用于说明设置和架构
- CLAUDE.md 用于说明 AI 编码约定
- 注释解释“为什么”，而非“是什么”
- 复杂模式配有示例

**自动化规范：**
- 通过代码检查工具强制执行风格规范
- 通过类型检查强制执行契约
- 通过测试验证行为
- 通过 CI/CD 强制执行质量门槛

#### 遵循模式

<Good>
```typescript
// Existing codebase pattern for API clients
class UserAPIClient {
  async getUser(id: string): Promise<User> {
    return this.fetch(`/users/${id}`);
  }
}

// New code follows the same pattern
class OrderAPIClient {
  async getOrder(id: string): Promise<Order> {
    return this.fetch(`/orders/${id}`);
  }
}

一致性让代码库更易预测

```typescript // Existing pattern uses classes class UserAPIClient { /* ... */ }

// New code introduces different pattern without discussion const getOrder = async (id: string): Promise => { // Breaking consistency "because I prefer functions" };

不一致会造成困惑
</Bad>

#### 错误处理模式

<Good>
```typescript
// Project standard: Result type for recoverable errors
type Result<T, E> = { ok: true; value: T } | { ok: false; error: E };

// All services follow this pattern
const fetchUser = async (id: string): Promise<Result<User, Error>> => {
  try {
    const user = await db.users.findById(id);
    if (!user) {
      return { ok: false, error: new Error('User not found') };
    }
    return { ok: true, value: user };
  } catch (err) {
    return { ok: false, error: err as Error };
  }
};

// Callers use consistent pattern
const result = await fetchUser('123');
if (!result.ok) {
  logger.error('Failed to fetch user', result.error);
  return;
}
const user = result.value; // Type-safe!

代码库中统一采用的标准模式

文档规范

```typescript /** * Retries an async operation with exponential backoff. * * Why: Network requests fail temporarily; retrying improves reliability * When to use: External API calls, database operations * When not to use: User input validation, internal function calls * * @example * const result = await retry( * () => fetch('https://api.example.com/data'), * { maxAttempts: 3, baseDelay: 1000 } * ); */ const retry = async ( operation: () => Promise, options: RetryOptions ): Promise => { // Implementation... }; ``` 说明原因、时机和做法

实践中

添加新模式之前：

• 在代码库中查找是否已有解决类似问题的方法
• 查看 CLAUDE.md 中的项目约定
• 如果要打破现有模式，请与团队讨论
• 引入新模式时更新文档

编写代码时：

• 与现有文件结构保持一致
• 使用相同的命名约定
• 遵循相同的错误处理方式
• 从相同的位置导入

评审时：

• 检查是否与现有代码保持一致
• 指出代码库中的示例
• 建议遵循规范
• 如果出现新规范，更新 CLAUDE.md

4. 即时（JIT）

构建当下所需的功能，不多也不少。避免过早优化和过度工程化。

原则

YAGNI（你不会需要它）：

• 只实现当前需求
• 不添加“以防万一”的功能
• 不编写“以后可能会需要”的代码
• 删除臆测性代码

采用能满足需求的最简单方案：

• 从直接明了的方案开始
• 只在需要时增加复杂度
• 需求变化时进行重构
• 不预判未来需求

根据测量结果进行优化：

• 避免过早优化
• 优化前先进行性能分析
• 测量变更的影响
• 接受“足够好”的性能

YAGNI 实践

```typescript // Current requirement: Log errors to console const logError = (error: Error) => { console.error(error.message); }; ``` 简单，满足当前需求 ```typescript // Over-engineered for "future needs" interface LogTransport { write(level: LogLevel, message: string, meta?: LogMetadata): Promise; }

class ConsoleTransport implements LogTransport { /... / } class FileTransport implements LogTransport { / ... / } class RemoteTransport implements LogTransport { / .../ }

class Logger { private transports: LogTransport[] = []; private queue: LogEntry[] = []; private rateLimiter: RateLimiter; private formatter: LogFormatter;

// 200 lines of code for "maybe we'll need it" }

const logError = (error: Error) => { Logger.getInstance().log('error', error.message); };

为臆想的未来需求而构建
</Bad>

**何时增加复杂度：**
- 当前需求确有要求
- 使用过程中发现了痛点
- 测量发现了性能问题
- 出现了多种使用场景

<Good>
```typescript
// Start simple
const formatCurrency = (amount: number): string => {
  return `$${amount.toFixed(2)}`;
};

// Requirement evolves: support multiple currencies
const formatCurrency = (amount: number, currency: string): string => {
  const symbols = { USD: '$', EUR: '€', GBP: '£' };
  return `${symbols[currency]}${amount.toFixed(2)}`;
};

// Requirement evolves: support localization
const formatCurrency = (amount: number, locale: string): string => {
  return new Intl.NumberFormat(locale, {
    style: 'currency',
    currency: locale === 'en-US' ? 'USD' : 'EUR',
  }).format(amount);
};

只在需要时增加复杂度

过早抽象

```typescript // One use case, but building generic framework abstract class BaseCRUDService { abstract getAll(): Promise; abstract getById(id: string): Promise; abstract create(data: Partial): Promise; abstract update(id: string, data: Partial): Promise; abstract delete(id: string): Promise; }

class GenericRepository { /300 lines / } class QueryBuilder { / 200 lines/ } // ... building entire ORM for single table

为不确定的未来构建庞大的抽象
</Bad>

<Good>
```typescript
// Simple functions for current needs
const getUsers = async (): Promise<User[]> => {
  return db.query('SELECT * FROM users');
};

const getUserById = async (id: string): Promise<User | null> => {
  return db.query('SELECT * FROM users WHERE id = $1', [id]);
};

// When pattern emerges across multiple entities, then abstract

只有在 3 个以上案例中验证模式后才进行抽象

性能优化

```typescript // Current: Simple approach const filterActiveUsers = (users: User[]): User[] => { return users.filter(user => user.isActive); };

// Benchmark shows: 50ms for 1000 users (acceptable) // ✓ Ship it, no optimization needed

// Later: After profiling shows this is bottleneck // Then optimize with indexed lookup or caching

根据测量结果而非假设进行优化
</Good>

<Bad>
```typescript
// Premature optimization
const filterActiveUsers = (users: User[]): User[] => {
  // "This might be slow, so let's cache and index"
  const cache = new WeakMap();
  const indexed = buildBTreeIndex(users, 'isActive');
  // 100 lines of optimization code
  // Adds complexity, harder to maintain
  // No evidence it was needed
};

为未经测量的问题设计复杂方案

实践中

实现时：

• 解决眼前的问题
• 采用直接明了的方法
• 抵制“万一……”的想法
• 删除臆测性代码

优化时：

• 先分析性能，再进行优化
• 测量优化前后的效果
• 记录进行优化的原因
• 在测试中保留简单版本

进行抽象时：

• 等待出现 3 个以上相似案例（三次法则）
• 尽可能简化抽象
• 宁可重复代码，也不要错误抽象
• 模式明确后再重构

与命令集成

Kaizen 技能指导你的工作方式。命令提供结构化分析：

• /why：根因分析（5 Whys）
• /cause-and-effect：多因素分析（鱼骨图）
• /plan-do-check-act：迭代改进周期
• /analyse-problem：全面文档记录（A3）
• /analyse：智能选择方法（现场观察／价值流图／浪费分析）

使用命令进行结构化问题解决。将技能应用于日常开发。

危险信号

违背持续改进：

• “我以后再重构”（但永远不会）
• 让代码变得比接手时更糟
• 一次性大规模重写，而不是渐进改进

违背防错：

• “用户只要小心点就行”
• 使用后才验证，而不是使用前验证
• 可选配置却不做验证

违背标准化作业：

• “我更喜欢按自己的方式来”
• 不检查现有模式
• 忽视项目约定

违背准时化：

• “说不定哪天会用到”
• 还没用就先构建框架
• 不经测量就优化

请记住

改善的核心是：

• 持续进行小幅改进
• 通过设计预防错误
• 遵循经过验证的模式
• 只构建所需内容

而不是：

• 第一次就追求完美
• 大规模重构项目
• 炫技式抽象
• 过早优化

心态： 今天做到足够好，明天做得更好。如此反复。