- Be precise, concise, and evidence-based. Avoid vague statements and unnecessary long explanations.
- Inspect the relevant code, configuration, tests, and existing patterns before changing behavior.
- For clear, scoped implementation requests, proceed without asking for another approval.
- For open-ended feature or design requests with more than one viable approach, present the options and a recommendation before editing.
- Ask for clarification only when ambiguity materially affects behavior, scope, data, security, or an irreversible/external action.
- Verify assumptions that could affect correctness. When version- or API-specific behavior matters, prefer official documentation.
- Keep changes focused on the requested work. Avoid unrelated refactors or cleanup.
- Prefer established repository patterns unless there is a concrete reason to change them.
Focus on substance over praise. Skip unnecessary compliments, engage critically with my ideas, question my assumptions, identify my biases, and offer counterpoints when relevant. Don't shy away from disagreement, and ensure that any agreements are grounded in reason and evidence.
Understand which parts of the system the requested behavior actually crosses and update all affected parts.
Depending on the task, this may include runtime behavior, domain logic, persistence, schemas, generated artifacts, external interfaces, tests, documentation, or obsolete code.
Do not treat this as a mechanical checklist. Update what is relevant to the real workflow and no more.
Reason from the actual entry point through downstream behavior instead of modifying only the directly mentioned function or file.
Where relevant, consider:
- success and empty cases;
- partial and failure paths;
- retry or reuse behavior;
- boundary conditions;
- persistence or serialization round-trips;
- downstream consumers.
Do not add handling for hypothetical states that are not reachable through the supported workflow unless explicitly requested.
Each important validation, invariant, transition, relationship, decision, or derived value should have one authoritative owner.
Do not duplicate the same semantic rule across callers and callees, services and domain objects, persistence and runtime models, generated and handwritten models, or multiple helpers.
Boundary validation may validate a relationship or input at the boundary, but should not reimplement invariants already guaranteed by the authoritative object.
Do not introduce unnecessary:
- copied semantic fields;
- mirrored models;
- duplicated derived values;
- alternative decision paths;
- compatibility paths that keep two implementations active;
- multiple implementations of the same calculation or rule.
Representations at different layers may differ in shape, but they should agree on the same semantics and source of truth.
When a defect comes from incorrect ownership, duplicated state, an inconsistent invariant, or a broken workflow, fix that cause rather than layering guards, filters, fallbacks, validators, or special cases around the symptom.
Additional defensive checks are appropriate when they protect a real boundary or failure mode, not when they compensate for an unresolved architectural problem.
When behavior is replaced, remove the obsolete implementation instead of leaving parallel architectures active.
Check for stale:
- validation;
- helpers;
- branches;
- fields or enums;
- imports or parameters;
- comments or diagnostics;
- tests;
- compatibility paths.
Do not remove an important behavioral guarantee merely because its previous implementation was replaced. Move the guarantee and its regression coverage to the new authoritative owner.
Keep cleanup scoped to code made obsolete by the requested change unless broader cleanup is explicitly requested.
- Add regression coverage for changed behavior when appropriate.
- Prefer tests of the authoritative behavior and real workflow over tests that only exercise isolated helpers.
- Define each test by the intended user or domain guarantee and the concrete defect it must catch. A passing test must distinguish the required behavior from a plausible broken implementation.
- Test functional guarantees and observable outcomes. Never create tests that merely reaffirm the current implementation or freeze incidental counts, positions, or ordering; assert those only when they are themselves the intended feature or behavioral guarantee.
- Derive expected results from requirements or independent fixtures, not from the production helper or calculation being tested.
- Assert observable outcomes at the relevant boundary: persisted data, emitted commands, delivered notifications, interaction responses, or the relevant rendered region. Check the actual target and seed the state named by the test.
- Use exact string assertions when the string itself is required output, such as copied content, time formatting, protocol bytes, or explicitly required UI wording. Do not lock down incidental prose, punctuation, or complete footer text.
- For rendering tests, verify association, selection, visibility, clipping, and controls in their relevant rows or regions. Whole-screen substring searches alone do not prove those guarantees.
- Synchronize process tests using correlated events or persisted outcomes when available. Do not use cosmetic success messages or arbitrary sleeps as evidence that an operation completed.
- Keep fixtures independent between tests. Use the lowest test layer that exercises the required path, and retain functional coverage of important cross-layer workflows. Duplicate coverage at multiple layers must protect distinct boundaries.
- Preserve meaningful negative guarantees, such as preventing writes, duplicate alerts, or disclosure of private data. Do not add tests solely to prove that removed code or a superseded implementation is absent.
- Use targeted checks while iterating, then run the relevant broader verification before considering the work complete.
- Never claim that a test, lint, formatting, generation, build, or other verification step passed unless it was actually run.
- If a relevant check cannot be run, state that clearly.
- Before finishing, review the complete diff for:
- missing requirements;
- duplicated semantic authority;
- stale or parallel behavior;
- inconsistent representations or contracts;
- missing generated artifacts or other required follow-up;
- accidental unrelated changes.
- Do not consider the work complete while a known reachable defect or duplicated semantic authority remains in the changed behavior.
Require explicit user intent before actions with meaningful external, destructive, or irreversible side effects, such as:
- committing or pushing;
- publishing npm packages, creating tags, or triggering releases;
- changing GitHub state such as PRs, issues, labels, or repository settings;
- deleting or overwriting files outside the scope of the requested change;
- other actions that cannot be safely undone locally.
Project-specific restrictions may tighten these defaults.
- Rust crate
claude-code-rust(binaryclaude-rs, edition 2024) built with Cargo.rust-toolchain.tomlpins channel1.89; the MSRV inCargo.tomlis1.88.0. - TypeScript bridge in
agent-sdk/and the root npm package both use npm with Node>=24.agent-sdk/is an npm workspace of the root package with a single rootpackage-lock.json; install both withnpm cifrom the repository root. - Bun is only the bundled bridge runtime for source runs and release packaging. It is not the package manager.
Run the Rust checks after Rust changes. They match the core jobs in .github/workflows/pr.yml:
cargo fmt --all -- --check
cargo clippy --all-targets --all-features -- -D warnings
cargo test --all-features -- --test-threads=1
cargo fetch --lockedRun the bridge checks from agent-sdk/ after bridge changes. They match .github/workflows/_agent-sdk.yml:
npm run build
npm run test
npm run lint
npm run knip
npm run auditRun these only when the change touches the matching area:
- Dependency graph (
Cargo.toml,Cargo.lock,deny.toml):cargo deny check bans licenses sources advisories. - MSRV-sensitive code, if the toolchain is installed:
cargo +1.88.0 check --all-features. - Duplicate code in
src,agent-sdk/src, orbin:npm run quality:duplicatesfrom the repository root. - npm packaging, installers, or
scripts/: thenpm-package-layoutjob in.github/workflows/pr.ymlis the canonical command list.
- Every new
.rsfile starts with// SPDX-License-Identifier: Apache-2.0. - Clippy denies
unwrap_used,expect_used,panic, andexitin production code (Cargo.toml[lints.clippy]; tests are exempted throughclippy.toml). Usethiserrorfor library errors andanyhowin main/app code. - When outdated, dead, or currently unused production code must remain temporarily during a change, mark it with
#[allow(dead_code)]and a short removal note. Never hide dead or unused production code behind#[cfg(test)]; remove it before finalizing when possible. - The Rust side and the bridge talk NDJSON over stdio. A change to the wire contract must update both
src/agent/wire.rsandagent-sdk/src/types.tsin the same change. - The
@anthropic-ai/claude-agent-sdkversion is pinned identically in the rootpackage.jsonandagent-sdk/package.json; bump both together with the root lockfile. - PR titles are linted by
.github/workflows/pr-title.yml. Allowed types, also used for commit messages:feat,fix,docs,style,refactor,perf,test,chore,ci,revert. Scope is optional.
agent-sdk/dist/istscbuild output and is gitignored. Rebuild it withnpm run build --prefix agent-sdkafter bridge changes; the app spawnsagent-sdk/dist/bridge.js, so a stale build hides bridge changes at runtime.dist-npm/,dist-install/,dist-pack/,docs/book/, andjscpd-report/are generated by repository scripts and gitignored. Do not edit them by hand.- There are no database schemas or migrations.
- When logging is enabled without
--log-file, the default filename is timestamped per run:claude-rs-YYYYMMDDTHHMMSSZ-pPID-rRUN.log.
- Never open, create, close, update, or otherwise operate on GitHub PRs, issues, or repository settings from this workspace. If a PR is needed, create only local draft text such as
pr.mdwhen explicitly requested; the user owns all GitHub actions. Pushing commits is covered by the Git section. - Do not trigger releases, create tags, or publish npm packages. Release workflow changes are maintainer-owned and must preserve the invariants in
CONTRIBUTING.mdanddocs/src/architecture.md. - Do not terminate the bridge runtime process
claude-rs-bridge-bun.exe. When cleaning up development processes, stop only PIDs started in the current session.
Prefer existing CLI commands and repository scripts when they provide the canonical workflow.
When moving or renaming tracked files, preserve history with git mv when appropriate.
Read-only Git inspection such as git status, git diff, git log, and git show is allowed.
Commit and push only when the user asks for it in that turn, never as a side effect of finishing a task. One approval covers that commit or push only; it does not carry over to later ones.
Do not merge, rebase, create/delete/rename branches, switch branches, or rewrite history unless explicitly requested.
When writing or suggesting a commit message:
- describe the net changes against
HEAD, not the local implementation path; - use imperative mood, present tense, and concise language;
- use the format
<type>(<scope>): <message>with a type from the PR title list in Repository conventions; - include 2–5 precise bullet points in the body;
- do not mention temporary or uncommitted planning files unless they are part of the intended change;
- do not add a
Co-Authored-Bytrailer, a generated-by footer, or any other agent attribution.
Example:
chore(agent-sdk): align integration with 0.3.286
- pin root and bridge dependencies to SDK 0.3.286
- propagate new command, lifecycle, MCP, task, artifact, and paste metadata
- handle conversation replacement identity and cache invalidation
- align CLI rendering and ownership decisions with SDK metadata
- add Rust and bridge regression coverage for migrated contracts
Personal, untracked instructions live in PERSONAL.md at the repository root. The file is optional and gitignored. If it exists, read it and apply it in addition to this document. It may add personal tooling and preferences; it does not relax the restrictions above.
@PERSONAL.md