diff --git a/.claude/agents/build.md b/.claude/agents/build.md
index e814e10d..499cac33 100644
--- a/.claude/agents/build.md
+++ b/.claude/agents/build.md
@@ -3,14 +3,14 @@ name: build
 description: Compile the project using cmake and ninja. Use when code changes need to be built or when checking for compilation errors.
 tools: Bash
 model: Haiku
+effort: low
 ---
 
 Build the project from the project root.
 
-If the build directory doesn't exist yet, run:
-  mkdir -p build && cmake -GNinja -S . -B build
-
-Then always run:
+Run:
+  mkdir -p build
+  cmake -GNinja -S . -B build
   ninja -C build
 
 Report only errors and warnings. If the build succeeds, say so briefly.
diff --git a/.claude/agents/quality.md b/.claude/agents/quality.md
index acc48bae..fc63d2bc 100644
--- a/.claude/agents/quality.md
+++ b/.claude/agents/quality.md
@@ -3,6 +3,7 @@ name: quality
 description: Run pre-commit quality checks (clang-format, clang-tidy, clazy) on source files. Use after making code changes before finishing a task.
 tools: Bash
 model: Haiku
+effort: low
 ---
 
 Run quality checks from the project root.
diff --git a/.claude/agents/test-runner.md b/.claude/agents/test-runner.md
index 7e8b29a7..7bb1f59e 100644
--- a/.claude/agents/test-runner.md
+++ b/.claude/agents/test-runner.md
@@ -3,6 +3,7 @@ name: test-runner
 description: Run the test suite with ctest. Use after making code changes to verify correctness. The project must be built first.
 tools: Bash
 model: Haiku
+effort: low
 ---
 
 Run the test suite from the project root:
diff --git a/CLAUDE.md b/CLAUDE.md
index 8b9c4942..6fe9662e 100644
--- a/CLAUDE.md
+++ b/CLAUDE.md
@@ -2,6 +2,8 @@
 
 ## Build
 
+> **Preferred workflow:** use the sub-agents (`@agent-build`, `@agent-test-runner`, `@agent-quality`) defined in `.claude/agents/` — see the [Development](#development) section. The commands below are provided as reference and fallback only.
+
 All commands run from the **project root** unless noted.
 
 **Requirements:** Qt 6, C++20, Ninja. Compiler flags: `-Wall -Wextra -Werror`.
@@ -34,8 +36,6 @@ clang-format -i src/path/to/file.cpp
 ./scripts/run_clazy.sh src/path/to/file.cpp
 ```
 
-**Always run pre-commit after making source file changes.** All three checks must pass before the work is done.
-
 ## Project Structure
 
 ```text
@@ -89,4 +89,4 @@ Several sub-agents are defined in `.claude/agents/` to keep build/test/lint outp
 - **`@agent-quality`** - runs clang-format, clang-tidy, and clazy; reports only violations.
 - **`@agent-code-reviewer`** - reviews code for quality, safety, and best practices; provides specific, actionable feedback.
 
-Always use these agents rather than running the commands directly. After making source file changes: build, then run tests, then run quality checks - all must pass before the work is done.
+Always use these agents rather than running the commands directly. After making source file changes: build, then run tests, then run quality checks, then run code review - all required steps must pass before the work is done.