From 549cd2c283072a7ca807a815d00327863a06bc47 Mon Sep 17 00:00:00 2001 From: Steve Biedermann Date: Mon, 12 Oct 2026 13:47:04 +0200 Subject: [PATCH] dev: update AGENTS.md --- .gitignore | 1 + AGENTS.md | 48 ++++++++++++++++++++++++++++++++++-------------- CHANGELOG.md | 9 +++++++++ 3 files changed, 44 insertions(+), 14 deletions(-) create mode 100644 CHANGELOG.md diff --git a/.gitignore b/.gitignore index 76c2ee2..0d4a6a2 100644 --- a/.gitignore +++ b/.gitignore @@ -1,4 +1,5 @@ /target +/.NOCOMMIT sim.db sim.db-shm sim.db-wal diff --git a/AGENTS.md b/AGENTS.md index 9daf7d2..0c541f9 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -1,26 +1,35 @@ # 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** always run formatting tools such as `cargo fmt` after you changed the contents of a file -- you **MUST** use conventional commits when committing (`feat`, `fix`, `perf`, `refactor`, `chore`, `docs`), with `!` and a `BREAKING CHANGE:` footer for API breaks -- you **MUST** end commit messages with the trailer `Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>` +- 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 ` - 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, but only when `cargo clippy` and `cargo test` pass -- you **SHOULD** commit formatting-only changes separately from functional changes +- 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 -cargo clippy --workspace --all-targets -- -D warnings # must stay clean +cargo test --workspace --no-default-features +cargo clippy --all -- -D warnings # must stay clean cargo fmt --all ``` -The server build runs `build.rs`, which builds `ui/` for `wasm32-unknown-unknown` -and embeds the generated assets; there is no separate UI packaging step. See -[README.md](README.md) for setup and run instructions. +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 @@ -34,7 +43,18 @@ and embeds the generated assets; there is no separate UI packaging step. See ## Conventions -- Comment only code that needs clarification. -- Warnings are treated as errors (`-D warnings`). -- After Rust changes, run `cargo fmt --all`; formatting is not needed for - documentation-only changes. +- 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. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..9072a5f --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,9 @@ +# Changelog + +Notable changes to this project are documented here. + +## [Unreleased] + +### Added + +- Expose the Picard actor console over the `/api/actors/ws` WebSocket endpoint.