claude-code-bash-patterns

Claude Code Bash 模式

状态：已可用于生产 ✅ | 最后验证：2025-11-18

---

快速入门

基本命令

ls -la

命令串联

bun install && bun run build && bun test

钩子

创建 .claude-hook-pretooluse.sh：

#!/usr/bin/env bash
# PreToolUse hook - runs before every Bash command

echo "Running: $1"

加载 references/hooks-examples.md，查看完整的钩子模式。

---

五种核心模式

1. 顺序操作（&&）

适用场景：每条命令都依赖前一条命令成功执行

git add . && git commit -m "message" && git push

原因：任一命令失败时都会停止执行链

---

2. 并行操作（多次工具调用）

适用场景：命令彼此独立

Message with multiple Bash tool calls in parallel

加载 references/cli-tool-integration.md，查看并行模式。

---

3. 会话持久化

适用场景：需要在多条命令之间保持状态

# Set environment variable
export API_KEY="sk-..."

# Use in later commands (same session)
curl -H "Authorization: Bearer $API_KEY" api.example.com

---

4. 后台进程

适用场景：长时间运行的任务

npm run dev &
# Get PID with $!

---

5. 自动化钩子

适用场景：需要命令执行前后的逻辑

加载 references/hooks-examples.md，查看所有钩子类型。

---

关键规则

务必做到 ✅

1. 顺序依赖操作使用 &&（不要使用分号）
2. 带空格的路径要加引号（cd "path with spaces"）
3. 执行破坏性操作前检查环境（rm、git push --force）
4. 优先使用专用工具（使用 Bash 前先用 Read、Grep、Glob）
5. 为长时间运行的操作设置超时（最长 10 分钟）
6. 将输入传递给 shell 命令前先进行验证
7. 对重复模式使用钩子（日志记录、验证）
8. 保持会话状态（只导出一次变量）
9. 显式处理错误（检查退出代码）
10. 在 .claude/commands/ 中记录自定义命令

绝不要做 ❌

1. 绝不要对有依赖关系的命令使用 ;（应使用 &&）
2. 绝不要遗漏带空格路径的引号
3. 绝不要未经确认就运行 rm -rf
4. 绝不要在命令输出中暴露机密
5. 绝不要忽略超时限制（最长 10 分钟）
6. 存在专用工具时，绝不要使用 bash 操作文件
7. 绝不要用换行符串联命令（应明确使用 && 或 ;）
8. 未经用户明确要求，绝不要强制推送到 main
9. 未经用户要求，绝不要跳过钩子（--no-verify）
10. 绝不要使用交互式命令（git rebase -i、git add -i）

---

Git 工作流

基本提交

git add . && git commit -m "feat: add feature"

测试后提交

npm test && git add . && git commit -m "fix: bug fix" && git push

拉取请求

git checkout -b feature/new && git add . && git commit -m "feat: new feature" && git push -u origin feature/new

加载 references/git-workflows.md，查看完整工作流，包括：

• 功能分支工作流
• PR 创建自动化
• 提交消息约定
• 提交前验证

---

钩子：高级自动化

PreToolUse 钩子

.claude-hook-pretooluse.sh：

#!/usr/bin/env bash
COMMAND="$1"

# Log all commands
echo "[$(date)] Running: $COMMAND" >> ~/claude-commands.log

# Block dangerous patterns
if [[ "$COMMAND" =~ rm\ -rf\ / ]]; then
    echo "❌ Blocked dangerous command"
    exit 1
fi

钩子类型

• pretooluse - 每条 Bash 命令执行前
• stop - 对话结束前
• user-prompt-submit - 用户提交消息后

加载 references/hooks-examples.md，查看所有钩子类型和示例。

---

CLI 工具集成

npm/bun

bun install && bun run build

wrangler（Cloudflare）

bunx wrangler deploy

gh（GitHub CLI）

gh pr create --title "Fix bug" --body "Description"

加载 references/cli-tool-integration.md，查看完整的工具模式。

---

自定义命令

创建 .claude/commands/deploy.md：

---
description: Deploy to production
---

Run these steps:
1. Run tests: `npm test`
2. Build: `npm run build`
3. Deploy: `wrangler deploy`

用户可以通过以下命令调用：/deploy

加载 templates/custom-command-template.md，查看模板。

---

安全

工具允许列表

settings.json：

{
  "dangerousCommandsAllowList": [
    "git push --force"
  ]
}

机密管理

# ✅ Good: Use environment variables
export API_KEY="$SECURE_VALUE"

# ❌ Bad: Hardcode secrets
curl -H "Authorization: Bearer sk-abc123..."

加载 references/security-best-practices.md，查看完整的安全指南。

---

常见用例

用例 1：提交前测试

npm test && git add . && git commit -m "message"

用例 2：验证后部署

npm run lint && npm test && npm run build && bunx wrangler deploy

用例 3：多仓库操作

cd repo1 && git pull && cd ../repo2 && git pull

用例 4：后台进程

npm run dev &

加载 references/cli-tool-integration.md，查看更多模式。

---

故障排除

问题：命令超时

解决方案：延长超时时间或使用后台模式

# Background mode
npm run dev &

问题：带空格的路径导致失败

解决方案：给路径加引号

cd "path with spaces/file.txt"

问题：钩子阻止命令执行

解决方案：检查 .claude-hook-pretooluse.sh 中的钩子逻辑

加载 references/troubleshooting-guide.md，查看所有问题的解决方法。

---

何时加载参考文档

以下情况请加载 references/git-workflows.md：

• 设置 git 自动化
• 以编程方式创建 PR
• 需要提交消息规范
• 想了解提交前验证模式

以下情况请加载 references/hooks-examples.md：

• 创建自定义钩子
• 需要钩子模板
• 想了解验证模式
• 实施日志记录／安全机制

以下情况请加载 references/cli-tool-integration.md：

• 编排多个 CLI 工具
• 需要特定工具的模式
• 想了解并行执行示例
• 排查工具集成问题

以下情况请加载 references/security-best-practices.md：

• 配置安全防护
• 设置允许列表
• 管理密钥
• 防止危险操作

以下情况请加载 references/troubleshooting-guide.md：

• 调试命令失败问题
• 遇到超时
• 钩子行为异常
• 会话状态问题

---

使用捆绑资源

参考文档（references/）

• git-workflows.md - 完整的 git 自动化模式
• hooks-examples.md - 包含示例的所有钩子类型
• cli-tool-integration.md - 工具编排模式
• security-best-practices.md - 安全配置指南
• troubleshooting-guide.md - 常见问题及解决方案

模板（templates/）

• custom-command-template.md - 自定义命令模板
• settings.json - 安全设置示例
• .envrc.example - 环境变量示例
• github-workflow.yml - GitHub Actions 集成
• dangerous-commands.json - 危险模式列表

---

示例

功能开发工作流

git checkout -b feature/oauth && \
  npm test && \
  git add . && \
  git commit -m "feat(auth): add OAuth support" && \
  git push -u origin feature/oauth

CI/CD 流水线

npm run lint && \
  npm test && \
  npm run build && \
  bunx wrangler deploy

多项目更新

cd project1 && bun install && cd ../project2 && bun install

---

官方文档

• Claude Code Bash Tool：https://docs.claude.com/en/docs/claude-code/tools
• Hooks：https://docs.claude.com/en/docs/claude-code/hooks
• Custom Commands：https://docs.claude.com/en/docs/claude-code/custom-commands

---

有疑问？遇到问题？

1. 查看 references/troubleshooting-guide.md，了解常见问题
2. 查看 references/git-workflows.md，了解 git 模式
3. 查看 references/hooks-examples.md，了解自动化
4. 加载 references/security-best-practices.md，了解安全相关内容