diff --git a/AGENTS.md b/AGENTS.md
index b0fde7668c..5da60c1f42 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -14,14 +14,49 @@ See the License for the specific language governing permissions and
 limitations under the License.
 -->
 
-# Agent Guide for brpc
+# Repository Guidelines
 
-This file is read by automated agents (security scanners, code
-analyzers, AI assistants) operating on this repository.
+## Project Structure & Module Organization
 
-## Security
+Core C++ code lives in `src/`: `src/brpc`, `src/bthread`,
+`src/butil`, `src/bvar`, `src/json2pb`, and `src/mcpack2pb`. Tests are in
+`test/` and mirror module names. Samples are in `example/`; utilities
+are in `tools/`. Documentation is under `docs/en` and `docs/cn`; packaging and
+bindings live in `package/`, `homebrew-formula/`, `python/`, and `java/`.
 
-Security model: [SECURITY.md](./SECURITY.md)
+## Build, Test, and Development Commands
 
-Agents that scan this repository should consult `SECURITY.md` and the
-threat model it links before reporting issues.
+- `sh config_brpc.sh --headers=/usr/include --libs=/usr/lib && make`: configure and build with Make.
+- `cmake -B build && cmake --build build -j6`: configure and build with CMake.
+- `cmake -B build -DBUILD_UNIT_TESTS=ON && cmake --build build -j6 && cd build && ctest`: run CMake tests.
+- `cd test && make && sh run_tests.sh`: run the Make-based test suite.
+- `bazel build //:brpc` and `bazel test //test/...`: build or test with Bazel.
+- `cd example/echo_c++ && make && ./echo_server & ./echo_client`: smoke-test an example.
+
+## Coding Style & Naming Conventions
+
+Follow Google C++ style with 4-space indentation. Keep feature-specific code in
+the relevant protocol or module, not broad files such as `server.cpp` or
+`channel.cpp`, unless the behavior is general. Use existing names:
+`*_unittest.cpp` or `*_unittest.cc`, module prefixes such as `brpc_`,
+`bthread_`, and `bvar_`, and `.proto` files beside related code.
+
+## Testing Guidelines
+
+New behavior should include unit tests. Run the smallest relevant test first,
+then the broader affected suite. Tests use Google Test and live in `test/`.
+Some integration tests require Redis or MySQL and may skip when absent.
+
+## Commit & Pull Request Guidelines
+
+Recent history uses short imperative subjects such as `Fix bazel compile error
+on macOS`. Keep commits focused, explain behavioral impact when needed, and
+link issues. Pull requests should describe the change, list tests run, note
+platform or dependency assumptions, and pass GitHub Actions.
+
+## Security & Configuration Tips
+
+Read `SECURITY.md` before reporting vulnerabilities. Avoid committing
+build directories, local paths, credentials, or machine-specific configuration.
+Prefer flags such as `--with-glog`, `--with-thrift`, `--with-asan`,
+or the matching CMake/Bazel options.