diff --git a/.githooks/pre-commit b/.githooks/pre-commit
index 56a4e836..f7123747 100755
--- a/.githooks/pre-commit
+++ b/.githooks/pre-commit
@@ -1,7 +1,7 @@
 #!/bin/sh
 #
-# Pre-commit 提交门槛（启用：git config core.hooksPath .githooks，
-# 约定见 ShadowsocksX-NG2/AGENTS.md，工具安装与版本见 ShadowsocksX-NG2/README.md）：
+# Pre-commit 检查（启用：git config core.hooksPath .githooks，
+# 行为约定见仓库根目录 README.md，工具安装与版本见 ShadowsocksX-NG2/README.md）：
 #   1. 对暂存的 ShadowsocksX-NG2/ 下 .swift 文件先 `swift format` 格式化，
 #      格式化结果直接写回暂存区（只改暂存区、不动工作区，部分暂存安全）；
 #   2. 再用 SwiftLint 检查暂存内容：error 级违规拒绝提交，warning 仅提示。
@@ -76,7 +76,7 @@ if ! swiftlint lint --config "${NG2_DIR}/.swiftlint.yml" --quiet "${TMP_DIR}" >"
 	echo "pre-commit: SwiftLint 发现 error 级违规，提交被拒绝" >&2
 	echo "pre-commit: 报告中的 0001_xxx.swift 是暂存内容的临时副本，序号_ 后为原文件名：" >&2
 	cat "${LINT_LOG}" >&2
-	echo "pre-commit: 请修复后重新提交；手动检查方式见 ShadowsocksX-NG2/AGENTS.md" >&2
+	echo "pre-commit: 请修复后重新提交；手动检查方式见 ShadowsocksX-NG2/README.md" >&2
 	exit 1
 fi
 
diff --git a/AGENTS.md b/AGENTS.md
index d5f4db7a..06a2887a 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -2,10 +2,6 @@
 
 macOS Shadowsocks 客户端。`Legacy/` 是已冻结的旧版实现,仅作只读参考(见 Legacy/AGENTS.md);新实现位于 `ShadowsocksX-NG2/`。
 
-## NG2 提交门槛
-
-`ShadowsocksX-NG2/` 的 Swift 代码提交前必须过 `swift format` 格式化与 SwiftLint 检查,由 pre-commit 钩子强制;新 clone 先启用钩子。约定与启用步骤见 `ShadowsocksX-NG2/AGENTS.md`,工具安装与基线版本见其 `README.md`。
-
 ## Agent skills
 
 ### Issue tracker
diff --git a/README.md b/README.md
index dd03c017..31242b04 100644
--- a/README.md
+++ b/README.md
@@ -13,3 +13,13 @@
 ```
 
 旧版工程的功能说明与使用文档见 [Legacy/README.md](Legacy/README.md)。
+
+## 开发钩子
+
+新 clone 后，在仓库根目录启用 Git hooks：
+
+```bash
+git config core.hooksPath .githooks
+```
+
+启用后，`pre-commit` 只检查暂存区中 `ShadowsocksX-NG2/` 下的 `.swift` 文件：`swift format` 的结果写回暂存区、不修改工作区；SwiftLint 的 error 级违规拒绝提交，warning 仅提示。`Legacy/` 和其他文件跳过；没有 NG2 Swift 文件时直接放行。含有 NG2 Swift 文件但缺少工具时，提交检查失败。工具安装与版本见 [`ShadowsocksX-NG2/README.md`](ShadowsocksX-NG2/README.md)。
diff --git a/ShadowsocksX-NG2/AGENTS.md b/ShadowsocksX-NG2/AGENTS.md
index 4a5e5969..409bd144 100644
--- a/ShadowsocksX-NG2/AGENTS.md
+++ b/ShadowsocksX-NG2/AGENTS.md
@@ -1,21 +1,3 @@
 # ShadowsocksX-NG2
 
 新实现（2.0）所在目录。仓库级约定见根目录 [`AGENTS.md`](../AGENTS.md)；工程结构、外部二进制供应链、签名基线、构建测试命令、代码风格工具安装与基线版本见 [`README.md`](README.md)，本文件不重复。
-
-## Swift 提交门槛
-
-- **启用钩子**（新 clone 必做一次，否则门槛不生效）：
-
-  ```bash
-  git config core.hooksPath .githooks
-  ```
-
-- 钩子只检查本目录暂存的 `.swift` 文件（其余目录含 `Legacy/` 一律跳过）：`swift format` 结果直接写进提交、工作区不动；SwiftLint error 级违规拒绝提交，warning 仅提示。
-- 手动执行（在本目录内运行配置才自动加载；`swift format` 作用于目录需 `-r`）：
-
-  ```bash
-  swift format format --in-place -r App Tests Domain
-  swiftlint lint
-  ```
-
-- 调规则只针对实际痛点：改 `.swift-format` / `.swiftlint.yml` 的 PR 须给出触发案例，并同步更新 README 中的基线版本。
diff --git a/ShadowsocksX-NG2/README.md b/ShadowsocksX-NG2/README.md
index 2579fe1b..cea799b8 100644
--- a/ShadowsocksX-NG2/README.md
+++ b/ShadowsocksX-NG2/README.md
@@ -34,29 +34,42 @@ ShadowsocksX-NG 的现代化重写版本。新工程的全部源码与构建配
 - 测试 target 用 Apple Development 证书签名：宿主 app 开启 Hardened Runtime 后 library validation 要求被注入的 xctest 包同 Team 签名。
 - Release 配置关闭 `CODE_SIGN_INJECT_BASE_ENTITLEMENTS`，保证发布产物 entitlements 只来自项目文件。
 
-## 构建与测试
+## 开发、构建与测试
+
+在本目录内，日常格式化、静态检查、工程生成、构建和测试优先使用 `Taskfile.dist.yml` 定义的任务：
+
+```bash
+task format
+task lint
+task lint:fix  # 需要自动修复 SwiftLint 违规时使用；执行后再运行 task lint
+task gen:prj   # 生成 Xcode 工程
+task build     # 构建 Debug 版本 app
+task test      # 运行单元测试
+```
+
+`task format` 会格式化 `App/`、`Tests/`、`Domain/` 和 `Agent/` 下的 Swift 文件；`task lint:fix` 会修改源文件，执行后检查并复核 diff。
+
+新 clone 或清单变更后，在本目录内先取外部二进制，再生成工程（顺序不可颠倒）：
 
 ```bash
-cd ShadowsocksX-NG2
-# 新 clone 或清单变更后：先取外部二进制，再生成工程（顺序不可颠倒）
 Scripts/fetch-external-binaries.sh
-xcodegen generate
-# 构建
-xcodebuild -project ShadowsocksX-NG2.xcodeproj -scheme ShadowsocksX-NG2 \
-  -configuration Debug -destination 'platform=macOS,arch=arm64' build
-# 运行单元测试
-xcodebuild -project ShadowsocksX-NG2.xcodeproj -scheme ShadowsocksX-NG2 \
-  -destination 'platform=macOS,arch=arm64' test
+task gen:prj
+```
+
+发布前对构建产物运行打包门槛检查：
+
+```bash
 # 打包门槛（对构建产物；发布前必须全绿）
 Scripts/packaging-gate.sh \
-  .build/DerivedData/Build/Products/Debug/ShadowsocksX-NG2.app
+  .build/derivedData/Build/Products/Debug/ShadowsocksX-NG2.app
 ```
 
 ## 代码风格工具
 
 - `swift format` 随 Xcode/Swift 工具链提供，无需单独安装（基线：Apple Swift 6.4）；SwiftLint 需 `brew install swiftlint`（基线 0.65.0）。工具缺失时，含本目录 Swift 文件的提交会被 pre-commit 钩子拒绝而不是放行。
 - 配置文件：`.swift-format` 是 Swift 6.4 工具链默认规则的快照（固定成文件，工具链升级不漂移）；`.swiftlint.yml` 默认规则起步，只声明排除项与个别和 format 基线冲突的关闭项（文件内有触发案例注释）。
-- 提交门槛的行为约定、钩子启用与手动执行命令见 [`AGENTS.md`](AGENTS.md)。
+- 仓库级 `pre-commit` 钩子的启用方式和检查范围见根目录 [`README.md`](../README.md)。
+- 调整规则只针对实际痛点：修改 `.swift-format` / `.swiftlint.yml` 的 PR 须给出触发案例，并同步更新本节中的基线版本。
 
 ## 依赖升级