kernbench2/CLAUDE.md

Claude Code Instructions (Repo)

This repository uses Claude Code with strict architectural and verification rules. SPEC.md and ADRs are the source of truth.

---

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.).

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.

---

Design Questions

• Design / architecture questions are ALWAYS allowed.
• Design questions MUST NOT modify:
  • production code
  • test code
  • SPEC.md
  • ADRs
• If a design question implies a change, default to Phase 1.

---

Change & Test Protocol (Mandatory)

All non-trivial changes MUST follow a two-phase process. Design discussion is always allowed; code changes are not.

---

Phase 1 — Proposal + Verification

(No Production Code Changes)

Purpose

• Decide what to change and how it will be validated
• Establish verification coverage BEFORE touching production code

Phase 1 MUST include

1. Design Proposal

• Explain the design change.
• Explain why the change is needed.
• Explain consistency with SPEC.md and relevant ADRs.

1. Verification Plan

• SPEC requirement(s) / ADR(s) affected (e.g., R1/R2/R5, ADR-0002).
• 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.

If the Verification Plan is missing or vague, STOP.

Allowed in Phase 1

• Creating or modifying test code only
• Running tests and reporting results

Forbidden in Phase 1

• Any production code changes
• Any SPEC.md or ADR modifications
• Any production diff output

Phase 1 Output

• Proposal + Verification Plan
• Tests added/modified (if any)
• Test execution results (PASS / FAIL)
• Clear recommendation:
  • "No Phase 2 needed" OR
  • "Await approval for Phase 2"

---

Phase 2 — Apply + Verify + Rollback

Trigger

Phase 2 is triggered ONLY by the exact user approval phrase:

"ok"

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

Mandatory Verification

• Run the tests defined in the Phase 1 Verification Plan

Success Path

If ALL tests PASS:

• Keep the applied changes
• Ensure generated diagrams (if affected) are consistent
• Report success concisely

Failure Path (Mandatory)

If ANY test FAILS:

• Immediately rollback ALL Phase 2 changes
• Do NOT keep partial changes
• Report:
  • failing test names
  • error messages / assertions
  • brief hypothesis of the root cause
• Return to Phase 1 state

Tests must NEVER be weakened, removed, or altered to force Phase 2 to pass.

---

What Counts as "Non-Trivial"

(Protocol Required)

Any of the following:

• routing policy or ordering changes
• topology builder changes (nodes, links, parameters)
• address decoding / PhysAddr behavior
• latency composition rules
• changes affecting determinism or connectivity
• changes touching two or more production files

---

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."

---

CLI Semantics

• kernbench run --device <id> runs the benchmark on a single device.
• Omitting --device runs the benchmark on all devices discovered in the topology (logically parallel).
• Device enumeration is handled by the CLI only; benchmarks MUST remain single-device.

Derived Artifacts (Clarification)

• Generated diagrams under docs/diagrams/ are derived artifacts, not production code.
• Creating or updating files in docs/diagrams/:
  • does NOT count as a production code change,
  • does NOT require Phase 2 approval,
  • MUST be consistent with SPEC.md and ADRs.

Enforcement Defaults

• 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).