From ecc57d050d59bdaa24a116d4538c002d63aa655a Mon Sep 17 00:00:00 2001 From: Yangwook Kang Date: Mon, 18 May 2026 12:08:10 -0700 Subject: [PATCH] CLAUDE.md: restructure into Part 1 (general) / Part 2 (project-specific) - Reorganize rules into reusable general behavior vs kernbench-specific foundations + rules - Add Surfacing Choices, Coding Style (Simplicity First, Surgical Changes), Mental Model, Common Failure Modes - Clarify Phase 1 forbidden vs permitted-for-discussion (pseudocode, sketches allowed; final ready-to-apply diffs are Phase 2 only) - Tighten dead-code handling: mention + options before deletion - Drop redundant "SPEC.md and ADRs are the final authority" from Enforcement Defaults (already in Authority & Scope) Co-Authored-By: Claude Opus 4.7 (1M context) --- CLAUDE.md | 238 +++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 180 insertions(+), 58 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index e4787e5..2237a9d 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -5,27 +5,10 @@ SPEC.md and ADRs are the source of truth. --- -## Terminology +# Part 1 — General Behavior -- runtime API: - Host-facing public API used by benchmarks and user code (e.g., tensor deployment, kernel launch). -- simulation engine (sim_engine): - Discrete-event engine responsible for request injection, scheduling, and completion tracking. -- components: - Device-side nodes modeling hardware behavior (IO_CPU, M_CPU, PE_CPU, routers, engines, etc.). - -## Authority & Scope - -- SPEC.md defines the architectural contract. -- ADRs (docs/adr/ADR-*.md) define non-trivial architectural decisions. -- If a change conflicts with SPEC.md or an ADR: - - STOP. - - Explain the conflict. - - Propose options (keep spec, update ADR, or narrow scope). -- Do NOT silently change architecture. -- The repository structure reflects architectural intent; Claude Code MUST respect existing module boundaries and file locations. - ---- +> Reusable across repos. Describes *how* Claude Code interacts with the user +> and constructs changes, independent of this project's domain. ## Design Questions @@ -37,14 +20,21 @@ SPEC.md and ADRs are the source of truth. - ADRs - If a design question implies a change, default to Phase 1. ---- +## Surfacing Choices + +Applies to both design discussions and Phase 1 proposals. + +- If multiple valid interpretations of the request exist, present them. + Do NOT pick one silently. +- If a simpler approach exists, say so. Push back when warranted — + do NOT just implement the more complex path the user proposed. +- State required assumptions explicitly. If uncertain, ask before assuming. ## Change & Test Protocol (Mandatory) All non-trivial changes MUST follow a two-phase process. -Design discussion is always allowed; code changes are not. - ---- +Design discussion is always allowed. +Production code changes require Phase 1 approval before Phase 2 applies them. ### Phase 1 — Proposal + Verification @@ -63,20 +53,18 @@ Design discussion is always allowed; code changes are not. - Explain why the change is needed. - Explain consistency with SPEC.md and relevant ADRs. -1) **Verification Plan** +2) **Verification Plan** -- SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002). +- SPEC requirement(s) / ADR(s) affected. - Tests that validate the change: - existing tests to run, and/or - new tests to add. -- Concrete input cases used by the tests: - - topology (SIP / CUBE / PE layout) - - request parameters (src, dst, size_bytes). -- Expected observable assertions, such as: - - hop trace contains key waypoints, - - latency invariants (e.g., > 0, monotonic increase), - - deterministic route selection. - - **expected changes (or no changes) in generated diagrams**, if applicable. +- Concrete input cases used by the tests. +- Expected observable assertions. +- Expected changes (or no changes) in generated artifacts, if applicable. + +(Project-specific expectations for what these inputs/assertions look like: +see Part 2 → *Verification Plan — Project Expectations*.) If the Verification Plan is missing or vague, STOP. @@ -89,7 +77,13 @@ If the Verification Plan is missing or vague, STOP. - Any production code changes - Any SPEC.md or ADR modifications -- Any production diff output +- Final, ready-to-apply unified diffs (Phase 2 only) + +#### Permitted for design discussion + +- Pseudocode, interface sketches, type signatures +- Small illustrative snippets to clarify a design point +- "Before / after" excerpts (not full diffs) #### Phase 1 Output @@ -100,8 +94,6 @@ If the Verification Plan is missing or vague, STOP. - "No Phase 2 needed" OR - "Await approval for Phase 2" ---- - ### Phase 2 — Apply + Verify + Rollback #### Trigger @@ -112,10 +104,10 @@ Phase 2 is triggered ONLY by the exact user approval phrase: #### Phase 2 Rules -- Output **minimal unified diffs only** -- Modify ONLY production files declared in Phase 1 -- Do NOT include explanations, comments, or unchanged code -- Automatically apply the diff to the working tree +- Keep changes minimal and scoped to the approved Phase 1 proposal. +- Modify only production files declared in Phase 1. +- Avoid unrelated edits, cleanup, or formatting churn. +- Automatically apply approved changes to the working tree. #### Mandatory Verification @@ -126,7 +118,7 @@ Phase 2 is triggered ONLY by the exact user approval phrase: If ALL tests PASS: - Keep the applied changes -- Ensure generated diagrams (if affected) are consistent +- Ensure generated artifacts (if affected) are consistent - Report success concisely #### Failure Path (Mandatory) @@ -143,8 +135,142 @@ If ANY test FAILS: Tests must NEVER be weakened, removed, or altered to force Phase 2 to pass. +Failing tests may indicate: +- invalid assumptions, +- architectural violations, +- or incomplete modeling. + +Do not assume the test is wrong without explicit evidence. + +## Allowed Exceptions + +(Protocol Still Required) + +- comments or docstrings +- formatting-only changes +- type annotation changes with no runtime behavior change + +In exceptions, Phase 1 MUST explicitly state: +**"No behavior change; tests unchanged."** + +## Coding Style + +Applies to all production code changes (Phase 2) and test code (Phase 1). +The Phase 1/2 protocol decides *whether* and *what* to change; +this section decides *how* the resulting diff should look. + +### Simplicity First + +**Minimum code that solves the problem. Nothing speculative.** + +- Write the minimum code that satisfies the Phase 1 proposal. +- No abstractions for single-use code. +- No "flexibility"/"configurability" not declared in Phase 1. +- No error handling for impossible scenarios. + +Ask yourself: "Would a senior engineer say this is overcomplicated?" If yes, simplify. + +### Surgical Changes + +**Touch only what you must. Clean up only your own mess.** + +- Touch only files declared in the Phase 1 proposal. +- Don't "improve" adjacent code, comments, or formatting. +- Match existing style in the file, even if you'd do it differently. +- If your changes orphan imports/variables/functions, remove them. +- If you notice pre-existing dead code, do NOT delete it silently. + Mention it, and present options: + (a) delete (with approval), + (b) keep as-is, + (c) refactor to make it reachable / repurposed. + Let the user choose before acting. +- Every changed line must trace to the Phase 1 proposal. + +## Enforcement Defaults + +General fallbacks. Apply to anything not explicitly covered above. + +- If unsure whether a change is non-trivial → treat it as non-trivial. +- If unsure whether Phase 2 is allowed → STOP and ask. + --- +# Part 2 — Project-Specific (kernbench) + +> Specific to this repo's domain (SIP/CUBE/PE topology, runtime API, sim_engine). +> Replace this entire Part when adapting the framework to another repo. +> +> Contains **foundations** (Authority & Scope → Terminology → Mental Model → +> Common Failure Modes) followed by **rules** (Non-Trivial, Verification Plan, +> CLI, Derived Artifacts, runtime API / sim_engine Boundaries). + +## Authority & Scope + +- SPEC.md defines the architectural contract. +- ADRs (docs/adr/ADR-*.md) define non-trivial architectural decisions. +- If a change conflicts with SPEC.md or an ADR: + - STOP. + - Explain the conflict. + - Propose options (keep spec, update ADR, or narrow scope). +- Do NOT silently change architecture. +- The repository structure reflects architectural intent; Claude Code MUST respect existing module boundaries and file locations. + +## Terminology + +- runtime API: + Host-facing public API used by benchmarks and user code (e.g., tensor deployment, kernel launch). +- simulation engine (sim_engine): + Discrete-event engine responsible for request injection, scheduling, and completion tracking. +- components: + Device-side nodes modeling hardware behavior (IO_CPU, M_CPU, PE_CPU, routers, engines, etc.). + +## Mental Model + +The simulator is layered along **request flow**: + + runtime API (host-facing: tensor ops, kernel launch; + topology-agnostic, no routing — ADR-0007) + ↓ + sim_engine (schedules events, routes requests, + tracks completion via correlation IDs) + ↓ + components (device-side nodes: IO_CPU, M_CPU, PE_CPU, + routers, engines — model HW behavior + including interconnect) + +Configuration & decisions (orthogonal to request flow): +- **topology** — compiled at config time (ADR-0006); defines which + components exist and how they connect. Authoritative graph for sim_engine. +- **policy** (routing / address / placement) — consulted by sim_engine + during request handling. + +Invariant: all latency arises from **explicit scheduled events on modeled +components and links** (SPEC §0.1, R8). No implicit waits, no magic delays. + +Stay within layer boundaries; do not collapse or bypass for convenience. + +## Common Failure Modes + +Anti-patterns that violate the Mental Model or Golden Invariants (SPEC §0.1). +If your change does any of these, STOP and reconsider. + +- **runtime topology mutation** — topology is compiled at config time; do not + add/remove nodes or edges during simulation (ADR-0006). +- **nondeterministic iteration order** — never iterate sets, unordered dicts, + or anything else with implementation-defined order on the critical path. + Determinism is required (SPEC §0.1). +- **routing policy inside runtime API** — runtime API is topology-agnostic; + routing/fan-out belongs in policy + sim_engine (ADR-0007). +- **latency modeled outside sim_engine scheduling** — every delay must come + from an explicit scheduled event on a modeled component or link + (SPEC §0.1, R8). No magic sleeps, no hardcoded constants smuggled in. +- **hidden cross-layer coupling** — do not skip layer interfaces. + e.g., runtime API must not call into components directly, bypassing sim_engine. +- **silent ADR/SPEC reinterpretation** — surface conflicts; do not paper over them. + See *Authority & Scope* above. +- **weakening tests to make Phase 2 pass** — fix the code, not the test. + See *Part 1 → Phase 2 → Failure Path*. + ## What Counts as "Non-Trivial" (Protocol Required) @@ -158,20 +284,19 @@ Any of the following: - changes affecting determinism or connectivity - changes touching two or more production files ---- +## Verification Plan — Project Expectations -## Allowed Exceptions +Concrete forms that Part 1's *Verification Plan* MUST take in this repo: -(Protocol Still Required) - -- comments or docstrings -- formatting-only changes -- type annotation changes with no runtime behavior change - -In exceptions, Phase 1 MUST explicitly state: -**"No behavior change; tests unchanged."** - ---- +- SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002). +- Concrete input cases: + - topology (SIP / CUBE / PE layout) + - request parameters (src, dst, size_bytes). +- Expected observable assertions, such as: + - hop trace contains key waypoints, + - latency invariants (e.g., > 0, monotonic increase), + - deterministic route selection. + - **expected changes (or no changes) in generated diagrams**, if applicable. ## CLI Semantics @@ -187,10 +312,7 @@ In exceptions, Phase 1 MUST explicitly state: - does NOT require Phase 2 approval, - MUST be consistent with SPEC.md and ADRs. -## Enforcement Defaults +## runtime API / sim_engine Boundaries -- If unsure whether a change is non-trivial → treat it as non-trivial. -- If unsure whether Phase 2 is allowed → STOP and ask. -- SPEC.md and ADRs are the final authority. - runtime API MUST NOT hardcode topology/routing or internal hop sequences. - sim_engine MUST remain independent of runtime API semantics (no tensor/kernel policy logic).