agents: few tweaks

AGENTS.md

@@ -2,6 +2,11 @@
 
 This document provides instructions for AI agents (and their operators) before committing code and creating pull requests on this repository.
 
+## General Guidelines
+
+- **Keep changes minimal and focused.** Only modify code directly related to the task at hand. Do not refactor unrelated code, rename existing variables or functions for style, or bundle unrelated fixes into the same commit or PR.
+- **Do not add, remove, or update dependencies** unless the task explicitly requires it.
+
 ## Pre-Commit Checklist
 
 Before every commit, run **all** of the following checks and ensure they pass:
@@ -15,39 +20,7 @@ gofmt -w <modified files>
 goimports -w <modified files>
 ```
 
-### 2. Linting
-
-```sh
-go run ./build/ci.go lint
-```
-
-This runs additional style checks. Fix any issues before committing.
-
-### 3. Generated Code
-
-```sh
-go run ./build/ci.go check_generate
-```
-
-Ensures that all generated files (e.g., `gen_*.go`) are up to date. If this fails, run the appropriate `go generate` commands and include the updated files in your commit.
-
-### 4. Dependency Hygiene
-
-```sh
-go run ./build/ci.go check_baddeps
-```
-
-Verifies that no forbidden dependencies have been introduced.
-
-### 5. Tests
-
-```sh
-go run ./build/ci.go test
-```
-
-Run the full test suite. All tests must pass.
-
-### 6. Build All Commands
+### 2. Build All Commands
 
 Verify that all tools compile successfully:
 
@@ -57,9 +30,62 @@ make all
 
 This builds all executables under `cmd/`, including `keeper` which has special build requirements.
 
+### 3. Tests
+
+While iterating during development, use `-short` for faster feedback:
+
+```sh
+go run ./build/ci.go test -short
+```
+
+Before committing, run the full test suite **without** `-short` to ensure all tests pass, including the Ethereum execution-spec tests and all state/block test permutations:
+
+```sh
+go run ./build/ci.go test
+```
+
+### 4. Linting
+
+```sh
+go run ./build/ci.go lint
+```
+
+This runs additional style checks. Fix any issues before committing.
+
+### 5. Generated Code
+
+```sh
+go run ./build/ci.go check_generate
+```
+
+Ensures that all generated files (e.g., `gen_*.go`) are up to date. If this fails, first install the required code generators by running `make devtools`, then run the appropriate `go generate` commands and include the updated files in your commit.
+
+### 6. Dependency Hygiene
+
+```sh
+go run ./build/ci.go check_baddeps
+```
+
+Verifies that no forbidden dependencies have been introduced.
+
+## Commit Message Format
+
+Commit messages must be prefixed with the package(s) they modify, followed by a short lowercase description:
+
+```
+<package(s)>: description
+```
+
+Examples:
+- `core/vm: fix stack overflow in PUSH instruction`
+- `eth, rpc: make trace configs optional`
+- `cmd/geth: add new flag for sync mode`
+
+Use comma-separated package names when multiple areas are affected. Keep the description concise.
+
 ## Pull Request Title Format
 
-PR titles must follow this convention:
+PR titles follow the same convention as commit messages:
 
 ```
 <list of modified paths>: description
@@ -78,8 +104,8 @@ Use the top-level package paths, comma-separated if multiple areas are affected.
 Before creating a PR, confirm:
 
 - [ ] `gofmt` and `goimports` applied to all modified files
+- [ ] `make all` succeeds
+- [ ] `go run ./build/ci.go test` passes
 - [ ] `go run ./build/ci.go lint` passes
 - [ ] `go run ./build/ci.go check_generate` passes
 - [ ] `go run ./build/ci.go check_baddeps` passes
-- [ ] `go run ./build/ci.go test` passes
-- [ ] `make all` succeeds