commit - release 1
This commit is contained in:
@@ -0,0 +1,196 @@
|
||||
# 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).
|
||||
Reference in New Issue
Block a user