(kvrocks) branch unstable updated: docs(agents): clarify agent workflow guidance (#3455)

[tw...@apache.org]

This is an automated email from the ASF dual-hosted git repository.

PragmaTwice pushed a commit to branch unstable
in repository https://gitbox.apache.org/repos/asf/kvrocks.git


The following commit(s) were added to refs/heads/unstable by this push:
     new 8d0212583 docs(agents): clarify agent workflow guidance (#3455)
8d0212583 is described below

commit 8d021258308790627524f2cae594c75f22be2c31
Author: Twice <tw...@gmail.com>
AuthorDate: Fri Apr 24 13:18:31 2026 +0800

    docs(agents): clarify agent workflow guidance (#3455)
    
    This updates AGENTS.md to make repository-specific workflows clearer so
    agents can work more reliably and efficiently.
    
    Assisted-by: Codex
---
 AGENTS.md | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3face00e0..a5b6784ff 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -8,12 +8,17 @@ While working on Apache Kvrocks, please remember:
 - Only add meaningful comments when the code's behavior is difficult to understand.
 - Add or update tests to cover externally observable behavior and regressions when you change or add functionality.
 - Always run the formatter before submitting changes.
+- For non-trivial behavior, storage format, replication, or cluster changes, first look for an existing issue, discussion, or mailing list context before implementing.
 
 ## Build and Development Commands
 
 ### Building
 
 ```bash
+# Configure with Ninja when you want faster incremental builds.
+# The default generator is Makefiles unless --ninja is specified.
+./x.py build --ninja
+
 # Build kvrocks and utilities
 ./x.py build                    # Build to ./build directory
 ./x.py build -j N               # Build with N parallel jobs
@@ -30,6 +35,8 @@ While working on Apache Kvrocks, please remember:
 ./x.py fetch-deps               # Fetch dependency archives
 ```
 
+If the build directory was configured with Ninja, prefer incremental rebuilds like `cd build && ninja -j16 kvrocks` instead of re-running CMake.
+
 ### Testing
 
 ```bash
@@ -40,8 +47,9 @@ While working on Apache Kvrocks, please remember:
 # Run Go integration tests
 ./x.py test go
 
-# Run specific Go test by path
-./x.py test go tests/gocase/unit/...
+# Re-run a specific Go test name.
+# x.py test go currently forwards extra flags to "go test" but still runs "./...".
+./x.py test go build -run TestKMetadata
 ```
 
 ### Lint
@@ -159,7 +167,10 @@ Common scopes: `server`, `storage`, `commands`, `cluster`, `search`, `types`, `r
 ## Important Notes
 
 - Kvrocks aims for Redis protocol compatibility; always verify behavior against Redis when implementing or fixing commands.
-- All changes must pass `./x.py check format` and `./x.py check tidy`.
+- All changes must pass `./x.py check format`, and you should run `./x.py check tidy`, `./x.py check golangci-lint`, and the relevant tests when the touched code requires them.
 - Don't change public command behavior unless requested.
 - RocksDB is the core storage dependency; be cautious with storage-layer changes.
 - Adding a new column family breaks forward compatibility; avoid this if possible and prefer using existing column families.
+- Prefer focused patches over broad refactors when contributing.
+- Some website or documentation tasks may belong in the separate website repository rather than this repository.
+- If AI assistance is used, keep the generated changes reviewable and be able to explain and defend the final patch.