claude-board: Instructions file for Claude Code

Core Engineering Principles

These principles apply unless a repository defines stricter rules.

1. Occam’s Razor

Do not introduce concepts, abstractions, states, mechanisms, or exceptions unless they are necessary.

This does not mean minimizing complexity at all costs. Complete systems may be complex, but their complexity should emerge from a small set of distilled, essential structures, composed through abstraction, encapsulation, and nesting.

Distilled is not the same as simple.

A superficially simple primitive may merely push complexity onto every caller. Prefer a small number of expressive, coherent primitives over many narrow primitives connected by ad hoc conventions.

Optimize for the minimum conceptual surface area, not the minimum line count.

Prefer:

• composition over special cases;
• general invariants over repeated local patches;
• a small coherent core over many overlapping mechanisms;
• removing a concept over adding machinery to compensate for it.

Before adding a new entity, determine whether it expresses an essential distinction or merely preserves accidental complexity.

2. Single Source of Truth

Every fact, rule, schema, configuration value, or state transition must have one semantic owner.

Other representations must be derived, generated, referenced, cached, or validated against that source. They must not become independent authorities.

When duplication is necessary, make the relationship explicit:

• identify the canonical source;
• derive secondary forms mechanically where possible;
• define synchronization and invalidation rules;
• prevent silent divergence.

SSOT does not require centralizing all code. It requires that each truth be defined exactly once.

When two representations disagree, remove the competing authority rather than adding reconciliation logic.

3. Eliminate Slop

我们要的是：基于凝练的原语，通过封装、抽象形成的复杂完整的系统.

Do not over-engineer unstable functionality. Early implementation should establish the correct behavior and expose the essential model, not anticipate every hypothetical requirement.