diff --git a/AGENTS.md b/AGENTS.md
index 482c8fe52..c59306bcb 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -3,6 +3,25 @@
 - Repo: https://github.com/openclaw/openclaw
 - GitHub issues/comments/PR comments: use literal multiline strings or `-F - <<'EOF'` (or $'...') for real newlines; never embed "\\n".
 
+## Quick Reference
+
+**Build & Test:**
+```bash
+pnpm build                 # Type-check and build
+pnpm check                 # Run all checks (tsgo + lint + format)
+pnpm test                  # Run all unit tests
+pnpm test:coverage         # Run tests with coverage report
+vitest run path/to/file.test.ts  # Run single test file
+vitest run -t "test name"  # Run tests matching pattern
+```
+
+**Dev Commands:**
+```bash
+pnpm openclaw ...          # Run CLI in dev mode
+pnpm gateway:watch         # Auto-reload gateway on changes
+pnpm dev                   # Run node in dev mode
+```
+
 ## Project Structure & Module Organization
 
 - Source code: `src/` (CLI wiring in `src/cli`, commands in `src/commands`, web provider in `src/provider-web.ts`, infra in `src/infra`, media pipeline in `src/media`).
@@ -67,10 +86,50 @@
 - Language: TypeScript (ESM). Prefer strict typing; avoid `any`.
 - Formatting/linting via Oxlint and Oxfmt; run `pnpm check` before commits.
 - Add brief code comments for tricky or non-obvious logic.
-- Keep files concise; extract helpers instead of “V2” copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`.
+- Keep files concise; extract helpers instead of "V2" copies. Use existing patterns for CLI options and dependency injection via `createDefaultDeps`.
 - Aim to keep files under ~700 LOC; guideline only (not a hard guardrail). Split/refactor when it improves clarity or testability.
 - Naming: use **OpenClaw** for product/app/docs headings; use `openclaw` for CLI command, package/binary, paths, and config keys.
 
+### Import Style
+
+- Group imports: Node.js built-ins → external packages → local modules
+- Use `node:` prefix for built-in modules: `import fs from "node:fs";`
+- Always use `.js` extensions for local imports: `import { foo } from "./utils.js";`
+- Type-only imports: use `import type { ... }` when importing only types
+
+### Type Definitions
+
+- Prefer `type` over `interface` for most cases
+- Use strict typing; avoid `any` - use `unknown` and narrow with type guards instead
+- Export types that may be needed by other modules
+- Use TypeBox (`@sinclair/typebox`) for runtime validation schemas
+- Function return types: explicit when non-obvious, inferred for simple functions
+
+### Error Handling
+
+- Prefer explicit error handling over silent failures
+- Use try/catch for async operations that may fail
+- Create descriptive error messages with context
+- For expected errors, throw with meaningful messages
+- Log errors at appropriate levels using the tslog logger
+
+### Naming Conventions
+
+- **Files**: kebab-case (e.g., `agent-paths.ts`, `session-key.ts`)
+- **Test files**: `*.test.ts` (colocated), `*.e2e.test.ts` (e2e tests), `*.live.test.ts` (live integration tests)
+- **Functions**: camelCase (e.g., `resolveOpenClawAgentDir`, `ensureDir`)
+- **Classes**: PascalCase (e.g., `SessionManager`)
+- **Constants**: SCREAMING_SNAKE_CASE for true constants (e.g., `DEFAULT_AGENT_ID`)
+- **Types/Interfaces**: PascalCase (e.g., `JidToE164Options`)
+- **Variables**: camelCase (e.g., `tempStateDir`, `normalizedSelf`)
+
+### Documentation & Comments
+
+- Add JSDoc for public APIs and exported functions
+- Use inline comments for complex logic or non-obvious code
+- Keep comments concise and focused on "why" rather than "what"
+- Document function parameters and return types when non-obvious
+
 ## Release Channels (Naming)
 
 - stable: tagged releases only (e.g. `vYYYY.M.D`), npm dist-tag `latest`.