197 lines
5.2 KiB
Markdown
197 lines
5.2 KiB
Markdown
# 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).
|