> For the complete documentation index, see [llms.txt](https://zhouhao4221.gitbook.io/haiqing-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://zhouhao4221.gitbook.io/haiqing-docs/07-tooling.md).

# 07 · 工具

AI 工具与自动化技术栈。AI 原生团队的基础设施层。

***

## 目的

工具是原则落地的方式，但工具选错了反而增加噪音。本章节解释如何评估和配置 AI 工具——选型标准是什么、怎么集成到工作流、如何避免常见的配置误区。

***

## 当前技术栈

| 类别    | 工具                |
| ----- | ----------------- |
| AI 编码 | Claude Code、Codex |
| 版本控制  | Git + 结构化 PR 模板   |
| CI/CD | 按项目配置             |
| 提示管理  | 本仓库（04-prompt）    |

***

## 工具选型标准

评估新 AI 工具时，逐条回答：

1. 它解决了哪个具体问题？已有工具为何不够？
2. 输出是否可验证 — 能知道它什么时候错了吗？
3. 是否支持结构化输入，还是只接受自由文本？
4. 团队使用它需要什么前提知识？
5. 出故障时的降级方案是什么？

以上问题不能全部回答，暂缓采用。

***

## Claude Code 配置规范

每个项目根目录应维护 `CLAUDE.md`，包含：

* 项目背景和目录结构说明
* 不能自动修改的文件或目录
* 代码约定（命名规范、禁用的模式）
* 常用任务的提示入口（指向 `04-prompt/`）

权限配置原则：最小权限，按需开放。

***

## CI/CD 集成建议

在流水线中可加入的 AI 步骤：

* PR 自动触发 AI 代码审查（输出审查评论）
* 合并时自动生成变更日志草稿
* 测试失败时 AI 辅助分析失败原因

**注意**：AI 步骤只产出建议，不能作为流水线通过/失败的唯一判断依据。

***

## 工具采用流程

1. 对照四大核心原则进行评估
2. 记录使用场景和预期输出
3. 以明确的成功指标进行限时试用
4. 若采用：在本章节记录，并在 `04-prompt` 中创建相关提示
5. 若拒绝：记录原因，避免后续重复评估同一工具

***

## CLAUDE.md 标准模板

每个项目根目录的 `CLAUDE.md` 应包含以下结构：

```markdown
# [项目名称]

## 项目背景
[一段话：这个项目是什么，技术栈是什么]

## 目录结构
[关键目录的用途说明]

## 禁止自动修改的路径
- [路径1]：[原因]
- [路径2]：[原因]

## 代码约定
- 命名规范：[例如：组件使用 PascalCase，工具函数使用 camelCase]
- 禁用模式：[例如：不使用 any 类型，不直接操作 DOM]
- 提交规范：[例如：遵循 Conventional Commits]

## 常用任务入口
- 代码生成：04-prompt/code/code-generation.md
- PR 审查：04-prompt/review/pr-review.md
- 需求结构化：04-prompt/workflow/requirement-structuring.md
```

***

## Claude Code 使用规范

**上下文控制：**

* 单次对话聚焦单一任务；超过 3 个文件改动考虑拆分为独立对话
* 对话结束前让 AI 总结做了什么改动、为什么，便于 PR 描述填写
* 长对话中 AI 可能"遗忘"早期约束，重要约束应在每次关键任务前重申

**权限配置原则：**

```json
// .claude/settings.json 示例
{
  "permissions": {
    "allow": [
      "Bash(git diff:*)",
      "Bash(git log:*)",
      "Bash(npm test:*)"
    ],
    "deny": [
      "Bash(git push:*)",
      "Bash(rm -rf:*)"
    ]
  }
}
```

破坏性操作（删除、强制推送）不授予自动权限，每次由人工确认。

***

## 工具采用拒绝记录

| 工具   | 评估时间 | 拒绝原因 |
| ---- | ---- | ---- |
| （暂无） | —    | —    |

采用新工具时若经评估不符合标准，在此记录，避免重复评估。

***

## 本章节文档

| 文档                                                                            | 内容                               |
| ----------------------------------------------------------------------------- | -------------------------------- |
| [ai-context-in-project.md](/haiqing-docs/07-tooling/ai-context-in-project.md) | 为什么 AI 信息应和项目代码放在一起，以及跨项目共享的两种方式 |


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://zhouhao4221.gitbook.io/haiqing-docs/07-tooling.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.