61 lines
4.6 KiB
Markdown
61 lines
4.6 KiB
Markdown
# Project notes for agents
|
|
|
|
## AGENT RULES
|
|
- you **MUST NOT** change `AGENTS.md` or `CLAUDE.md` unless explicitly asked
|
|
- you **MUST** never do `git push`, unless you're explicitly told to
|
|
- you **MUST NOT** commit to `main`. If the current branch is `main`, ask the user before making changes whether to create a new branch or to make the changes without committing
|
|
- you **MUST** always run `cargo fmt --all` after changing file contents. Never pass formatting options on the command line (`--config`, `--edition`, ...) or invoke `rustfmt` directly on files; when present, formatting settings come from `rustfmt.toml` and `Cargo.toml`
|
|
- you **MUST** use conventional commits when committing (`feat`, `fix`, `perf`, `refactor`, `chore`, `docs`, `test`, `dev`), with `!` and a `BREAKING CHANGE:` footer for API breaks
|
|
- `dev` is used for tooling, debugging aids and test-flakiness work that doesn't change shipped behaviour
|
|
- `bump` (dependency version bumps) and `release` are used by maintainers; don't create release commits unless asked
|
|
- you **MUST** end commit messages with a `Co-Authored-By:` trailer naming yourself as the agent (product name only, no model or version), e.g. `Co-Authored-By: Claude <noreply@anthropic.com>`
|
|
- you **MUST** inform the user about commits or any other changes to git, including the commit message
|
|
- you **SHOULD** commit your changes after every step, unless the user tells you to not commit or a file with the name `.NOCOMMIT` exists in the project root. This applies to all changes, including docs, `AGENTS.md`, CI and config files, not just Rust code
|
|
- changes that affect compilation or tests (Rust code, `Cargo.toml`/`Cargo.lock`, build scripts, test data) may only be committed after `cargo clippy` and `cargo test` pass
|
|
- other changes (Markdown, CI, editor or deployment config) don't need those checks; commit them right away
|
|
- check the current branch (`git branch --show-current`) before every commit, not just at the start of the session
|
|
- you **SHOULD** commit formatting-only changes separately from functional changes: if `cargo fmt --all` reformats code you didn't change, commit that first as `chore: cargo fmt`; do not stage unrelated user changes
|
|
- you **SHOULD** add user-visible changes to the `Unreleased` section of [CHANGELOG.md](CHANGELOG.md) (Keep a Changelog format), creating that section if needed
|
|
|
|
## Commands
|
|
|
|
```sh
|
|
cargo build --workspace --all-targets
|
|
cargo test --workspace --no-default-features
|
|
cargo clippy --all -- -D warnings # must stay clean
|
|
cargo fmt --all
|
|
```
|
|
|
|
Lint conventions:
|
|
|
|
- Configure workspace lints in `[workspace.lints]` in the root [Cargo.toml](Cargo.toml); new crates should opt in with `[lints] workspace = true`.
|
|
- Change lint levels there, not on the command line or in CI.
|
|
|
|
## Project Context
|
|
|
|
- `src/main.rs` hosts the Axum API and simulation thread; `src/world.rs` owns
|
|
world behavior and snapshots; `src/storage.rs` persists snapshots.
|
|
- `config.rn` defines the Rune simulation defaults and agent behavior. Runtime
|
|
script edits are not written back to this file; see the README before changing
|
|
reset or persistence behavior.
|
|
- `ui/` is the Leptos/Wasm frontend. Keep its API/model changes aligned with the
|
|
server payloads in `src/main.rs`.
|
|
|
|
## Conventions
|
|
|
|
- Use descriptive variable and function names so the code explains itself.
|
|
- Comment only code that needs clarification, and keep comments short.
|
|
- Add dependencies to `[workspace.dependencies]` in the root [Cargo.toml](Cargo.toml) and use `dep.workspace = true` in crates.
|
|
- Use `thiserror` in libraries and `anyhow` only in binaries/tools.
|
|
- Use `tracing` for logging. Only add tracy spans in performance-critical code.
|
|
|
|
## Code reviews
|
|
|
|
Whenever asked for a code review (of commits, a branch, a diff, or specific files), report every finding as an entry in a list, in this exact shape:
|
|
|
|
- **Location:** `file:line` (use a range like `file:120-146` when the finding spans several lines)
|
|
- **Category:** one of `Blocking`, `FYI`, `Nit` (add categories such as `Question` only when none fit)
|
|
- **Comment:** what could be improved and the concrete problem or risk, including the failure scenario when claiming a defect—not just an abstract concern
|
|
|
|
Order findings by severity (`Blocking` first). Use `Blocking` for things that must change before merge (defects, unbounded resource use, or violations of these rules), `FYI` for design consequences and risks worth a conscious decision, and `Nit` for style/cleanliness. Verify claims against the code and run the Clippy and test commands from [Commands](#commands) before reporting; say when a finding is a possibility rather than a confirmed defect.
|