diff --git a/AGENTS.md b/AGENTS.md
index 8433ac6e79..2a71edb05a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # AGENTS.md
 
-This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing anything under `packages/` — the service map, event surface, loop lifecycle, and extension seams. The documentation standard is [docs/AGENTS.md](docs/AGENTS.md).
+This is the monorepo of the DeepSeek Harness group; it hosts **DeepSeek Harness SDK**, a plugin-based SDK for building agent harnesses. The codebase is built on the vendored Cordis framework, microkernel-style: **everything is a plugin**. Read [docs/architecture.md](docs/architecture.md) before changing `packages/`; the documentation standard is [docs/AGENTS.md](docs/AGENTS.md).
 
 ## Pre-release stance: foundation over blast radius
 
@@ -52,7 +52,7 @@ pnpm run demo:acp       # ACP server agent (needs DEEPSEEK_API_KEY)
 
 ### Run the CI gates locally before marking a PR ready
 
-From a fresh clone or worktree, `pnpm run build` first — publint and the NodeNext check validate built `lib/`. The CI-equivalent run:
+During implementation, run the narrowest affected checks; run this full CI-equivalent sequence only when complete and before marking a PR ready. From a fresh clone/worktree, `pnpm run build` first because publint and NodeNext validate built `lib/`:
 
 ```sh
 set -euo pipefail
diff --git a/docs/development.i18n.yaml b/docs/development.i18n.yaml
index cef11b8352..393ba013d5 100644
--- a/docs/development.i18n.yaml
+++ b/docs/development.i18n.yaml
@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write
-development.md: f032764fff29baaca007211db8b69d9a5129078f
-development.zh.md: 3a650d03ce7cafd0e34290ae918e5a303c2ad8a9
+development.md: 3201eb8c8715eea437098409e7cfe93e13c3204f
+development.zh.md: fcf6a7f2718cc4f3009f38fa4360ae38bdfe843f
diff --git a/docs/development.md b/docs/development.md
index f032764fff..3201eb8c87 100644
--- a/docs/development.md
+++ b/docs/development.md
@@ -84,9 +84,11 @@ The GitHub workflow runs these gates on each pull request:
 
 `pnpm run hygiene` is the local shorthand for `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types`; CI also runs `pnpm run constraints` as an earlier fail-fast step, then runs the full hygiene script after `pnpm run build`.
 
+During implementation, prefer the narrowest gate that can fail for the change you just made: filtered tests for touched packages/specs, `pnpm run typecheck` after type or API changes, `pnpm run lint` after code edits, and the specific doc/generator check only when that surface changed. Run the full CI-gate sequence from `AGENTS.md` once the change is complete and before marking a PR ready; repeat it only after later edits could invalidate the result.
+
 ## Daily commands
 
-Use these from the repo root:
+Use these from the repo root as a command reference, not as a checklist to rerun after every edit:
 
 ```sh
 pnpm run test           # unit tests
diff --git a/docs/development.zh.md b/docs/development.zh.md
index 3a650d03ce..fcf6a7f271 100644
--- a/docs/development.zh.md
+++ b/docs/development.zh.md
@@ -84,9 +84,11 @@ GitHub 工作流在每个 pull request 上运行这些门禁：
 
 `pnpm run hygiene` 是 `pnpm run knip && pnpm run publint && pnpm run constraints && pnpm run verify-node-next-types` 的本地简写；CI 还会把 `pnpm run constraints` 作为更早的快速失败步骤单独跑一次，然后在 `pnpm run build` 之后跑完整的 hygiene 脚本。
 
+开发过程中，优先运行刚才那次改动可能打红的最窄门禁：针对受影响 package/spec 的过滤测试；类型或 API 变动后跑 `pnpm run typecheck`；代码改动后跑 `pnpm run lint`；只在触及文档或生成面时跑对应的 doc/generator 检查。改动完成、准备把 PR 标为 ready 前，再按 `AGENTS.md` 中的完整 CI 门禁跑一遍；只有后续改动可能让结果失效时才重复全量。
+
 ## 日常命令
 
-在仓库根目录使用：
+在仓库根目录使用；下面是命令参考，不是每次编辑后都要重新跑一遍的 checklist：
 
 ```sh
 pnpm run test           # unit tests