第 6 章：操作与规范 —— 构建安全、自动化的工程标准

🎯 学习目标

完成本章后，你将能够：

✅ 制定严格的文件读写与命令执行规范，防止 AI 破坏生产环境。
✅ 配置 Pre/Post Hooks，在任务前后自动运行 Lint、测试或备份脚本。
✅ 掌握 Prompt 工程核心法则，写出角色清晰、约束明确、上下文丰富的高质量指令。
✅ 建立一套可复用的项目行为规范，让 AI 始终遵循你的编码风格。

6.1 Claude Code 操作说明：文件读写与命令执行规范

AI 拥有修改文件和执行系统命令的能力，这既是超能力也是风险源。必须建立明确的"交通规则"。

🛡️ 文件读写规范 (File I/O Policies)

1. 权限分级策略

在 .claude-code.json 中，根据文件类型设置不同的权限级别：

文件类型	推荐权限 (`file_write`)	理由
源代码 (`src/`)	`ask`	核心业务逻辑，需人工审查每一处变更。
测试代码 (`tests/`)	`auto`	风险较低，允许 AI 快速生成和迭代测试用例。
配置文件 (`config/`)	`ask`	错误配置可能导致服务启动失败，需确认。
文档 (`docs/`, `README`)	`auto`	纯文本，无执行风险，可自动更新。
锁定文件 (`package-lock.json`)	`auto`	由包管理器生成，AI 不应手动编辑，但可触发命令更新。
敏感文件 (`.env`, `secrets`)	`deny`	绝对禁止 AI 写入或读取，防止密钥泄露。

2. "原子性"修改原则

规范：要求 AI 每次只修改一个逻辑单元，避免一次性重写整个文件。
好处：便于 Diff 审查，出错时容易回滚。
Prompt 示例 ： "请仅修改 UserService 中的 login 方法，不要改动其他部分。如果涉及依赖引入，请单独列出。"

3. 备份机制

规范：在进行大规模重构（如重命名变量、移动文件）前，强制 AI 先执行备份命令。
Hook 联动：见 6.2 节，可通过 Hook 自动备份。

⚡ 命令执行规范 (Command Execution Policies)

1. 危险命令黑名单

永远不要让 AI 自动执行以下命令（即使是在 auto 模式下也要拦截）：

rm -rf / 或任何递归删除根目录的操作。
chmod 777 (除非特定调试场景)。
sudo 提权操作。
curl/wget 下载并直接执行管道脚本 (| bash)。

2. 环境隔离

规范：所有安装命令必须在虚拟环境或容器中进行。

配置：

json 复制代码

"custom_instructions": "所有 Python 包安装必须使用 'pip install -r requirements.txt' 且在 venv 环境中。严禁使用 'sudo pip install'。"

3. 长运行任务处理

规范：对于耗时超过 30 秒的命令（如编译大型项目、跑全量测试），AI 应异步执行或在后台运行，并定期汇报进度，而不是阻塞终端。

6.2 Claude Code 钩子 (Hooks)：在特定事件触发脚本

Hooks 是连接 AI 与现有 DevOps 工具的桥梁。它们允许你在 AI 行动的前后自动插入自定义逻辑。

⚙️ Hook 类型与配置

在 .claude-code.json 中定义：

json 复制代码

{
  "hooks": {
    "pre_task": "./scripts/pre-check.sh",      // 每次接收新任务前运行
    "pre_write": "./scripts/backup-file.sh",   // 每次写入文件前运行
    "post_write": "npm run lint",              // 每次写入文件后自动格式化/检查
    "pre_command": "./scripts/safety-check.sh",// 执行系统命令前进行安全检查
    "post_command": "echo 'Command completed'",// 命令执行后的清理工作
    "on_error": "./scripts/report-error.sh"    // 发生错误时自动上报
  }
}

💡 实战场景案例

场景 1：自动备份与快照

目标：防止 AI 误删重要文件。
脚本 (scripts/backup-file.sh):

bash 复制代码

#!/bin/bash
# 参数 $1 是被修改的文件路径
FILE=$1
if [[ $FILE == *"src/"* ]]; then
  cp "$FILE" "$FILE.bak.$(date +%s)"
  echo "✅ Backup created for $FILE"
fi

效果：每次 AI 试图修改 src/ 下的文件时，自动先存一份带时间戳的备份。

场景 2：代码质量守门员

目标：确保 AI 生成的代码符合 Lint 规范。
配置:

json 复制代码

"post_write": "eslint --fix && prettier --write"

效果：AI 写完代码后，自动运行 ESLint 和 Prettier 修复格式问题。如果修复失败，可以在 on_error 中通知用户。

场景 3：测试驱动开发 (TDD) 自动化

目标：强制 AI 写完功能必写测试。
脚本 (scripts/ensure-tests.sh):

bash 复制代码

# 检查是否有新增的源文件但没有对应的测试文件
# 如果有，抛出错误阻止任务完成

配置:

json 复制代码

"post_task": "./scripts/ensure-tests.sh"

⚠️ Hook 编写注意事项

执行速度：Hook 脚本必须轻量快速，否则会严重拖慢 AI 响应速度。
退出码 ：
- 返回 0：继续执行。
- 返回非 0：中断当前 AI 操作，并向 AI 报告错误信息（AI 会尝试根据错误自我修正）。
安全性：Hook 脚本本身也应是可信的，避免在 Hook 中引入新的安全风险。

6.3 最佳实践：如何编写清晰的 Prompt 以获得最佳结果

Prompt 是与 AI 协作的编程语言。高质量的 Prompt = 高质量代码。

🏆 CORE 框架：构建完美指令

1. Context (上下文)

提供足够的背景信息，让 AI 知道"我们在哪"、"要做什么"。

❌ 坏例子："修复这个 bug。"
✅ 好例子："在 src/payment.js 中，当用户余额不足时，系统没有抛出正确的 InsufficientFundsError，而是返回了 null。请参考 src/errors.js 中的错误定义进行修复。"

2. Objective (目标)

清晰、具体地描述预期结果。

❌ 坏例子："优化一下性能。"
✅ 好例子："将 getUserList 函数的时间复杂度从 O(n^2) 降低到 O(n log n)，并使用内存缓存减少数据库查询次数。"

3. Restrictions (约束)

明确告诉 AI不要做什么，以及必须遵守的规则。

✅ 示例：
- "严禁使用 any 类型，必须定义具体的 Interface。"
- "不要修改 public API 的签名，保持向后兼容。"
- "只使用项目已有的 lodash 库，不要引入新依赖。"

4. Examples (示例/格式)

给出输入输出的样例，或指定回复格式。

✅ 示例：
- "请按照以下格式输出：1. 问题分析; 2. 修改方案; 3. 代码块。"
- "参考 src/utils/formatDate.ts 的风格来编写新的日期处理函数。"

🧩 高级技巧：Few-Shot Prompting (少样本提示)

在复杂任务中，给 AI 一两个正确的示例，效果提升巨大。

Prompt 模板 ：

"我们需要创建一个新的 API 端点。请参照以下现有端点的结构：

[示例输入] : 创建 /users 端点
[示例输出]:

Controller: UserController.ts (包含 GET, POST)

Route: routes/users.ts

Test: tests/users.test.ts

现在任务 : 创建 /products 端点。请模仿上述结构生成代码。"

🔄 迭代式 Prompt 策略

不要指望一次成功。采用 "规划 -> 执行 -> 审查 -> 修正" 的循环：

第一轮："请分析这段代码的潜在安全隐患。" (让 AI 思考)
第二轮："基于你的分析，列出修复计划，不要写代码。" (确认方向)
第三轮："计划批准。请逐步实施修复，每步完成后暂停让我确认。" (控制节奏)
第四轮："第三步的逻辑有点问题，应该是...请修正并重跑测试。" (反馈修正)

📝 将规范固化到 `custom_instructions`

将通用的最佳实践写入配置文件，避免每次重复唠叨：

json 复制代码

"custom_instructions": "你是一名资深后端工程师。
1. 始终优先使用 TypeScript 严格模式。
2. 所有异步操作必须包含 try-catch 错误处理。
3. 数据库查询必须使用参数化语句防止 SQL 注入。
4. 代码注释必须用英文，解释 'Why' 而不是 'What'。
5. 遇到不确定的需求，先提问澄清，不要盲目猜测。"

🧪 动手练习：建立你的规范体系

练习 1：配置安全钩子

在项目根目录创建 scripts/safety-backup.sh。
编写脚本：当检测到 .env 文件被修改时，立即终止操作并报警。
在 .claude-code.json 中配置 pre_write 钩子指向该脚本。
尝试让 AI 修改 .env 文件，观察是否被拦截。

练习 2：应用 CORE 框架

找一个现有的复杂函数。
使用 CORE 框架 编写一个 Prompt，要求 AI 重构该函数（增加日志、优化异常处理、添加类型定义）。
对比使用普通 Prompt ("重构这个函数") 的结果，评估代码质量差异。

练习 3：固化团队规范

假设你是一个团队 Lead，制定 3 条针对该项目的核心编码规范（如命名风格、错误处理、注释要求）。
将这 3 条规范填入 .claude-code.json 的 custom_instructions。
启动新会话，让 AI 生成一段新代码，验证它是否自动遵守了这些规范。

❓ 常见陷阱与解答 (FAQ)

问题	原因分析	解决方案
Hook 导致死循环	`post_write` 触发了文件修改，又触发 `post_write`。	在 Hook 脚本中检测触发源，或使用标志位文件防止递归触发。
AI 忽略约束	Prompt 太长，约束被淹没在上下文中；或约束与其他指令冲突。	将关键约束放在 Prompt 最后 (Recency Bias)，或放入 `custom_instructions`。
备份文件堆积	Hook 每次都备份，磁盘爆满。	在 Hook 中加入清理逻辑，只保留最近 N 个备份，或仅在大版本变更前备份。
Prompt 太模糊	"让它更好"这种指令让 AI 无从下手。	量化指标："将加载时间减少 50%"，"将圈复杂度降低到 10 以下"。

📝 本章小结

规范即安全：通过权限分级和命令黑名单，为 AI 戴上"紧箍咒"。
Hooks 即自动化：利用前后置脚本，将 Lint、测试、备份融入 AI 工作流，实现无人值守的质量保障。
Prompt 即代码 ：使用 CORE 框架 和 迭代策略，像编写程序一样编写指令，获得确定性高的输出。
配置即文化 ：将团队规范写入 custom_instructions，让 AI 成为团队文化的传承者。

🚀 下一步预告 ：

掌握了操作规范后，我们将进入 第三阶段：高级功能与定制 。下一章 第 7 章：记忆与上下文管理，将揭秘如何让 AI 拥有"长期记忆"，记住你的项目架构和个人偏好，越用越聪明！

第 6 章：操作与规范 —— 构建安全、自动化的工程标准

🎯 学习目标

6.1 Claude Code 操作说明：文件读写与命令执行规范

🛡️ 文件读写规范 (File I/O Policies)

1. 权限分级策略

2. "原子性"修改原则

3. 备份机制

⚡ 命令执行规范 (Command Execution Policies)

1. 危险命令黑名单

2. 环境隔离

3. 长运行任务处理

6.2 Claude Code 钩子 (Hooks)：在特定事件触发脚本

⚙️ Hook 类型与配置

💡 实战场景案例

场景 1：自动备份与快照

场景 2：代码质量守门员

场景 3：测试驱动开发 (TDD) 自动化

⚠️ Hook 编写注意事项

6.3 最佳实践：如何编写清晰的 Prompt 以获得最佳结果

🏆 CORE 框架：构建完美指令

1. Context (上下文)

2. Objective (目标)

3. Restrictions (约束)

4. Examples (示例/格式)

🧩 高级技巧：Few-Shot Prompting (少样本提示)

🔄 迭代式 Prompt 策略

📝 将规范固化到 custom_instructions

🧪 动手练习：建立你的规范体系

练习 1：配置安全钩子

练习 2：应用 CORE 框架

练习 3：固化团队规范

❓ 常见陷阱与解答 (FAQ)

📝 本章小结

📝 将规范固化到 `custom_instructions`