AI Coding 长文分享：如何真正把工具用起来，从原理到实践

本文系统讲解AI编程工具的底层原理与高效使用方法，涵盖Token计算、工具调用、代码库索引机制（含Merkle Tree）、对话质量优化策略及实际应用场景（如代码检索、绘图生成、问题排查），并推荐结合AI的编码最佳实践，包括文档规范、注释命名与安全合规，助力开发者提升开发效率。

一、引言

本文面向不同经验水平和对AI态度各异的开发者，旨在提供普适性指导：

• AI深度用户：可深入了解底层原理；
• 资深手写代码者：进一步提升编码及周边效率；
• 团队新人：快速上手项目，避免出错；

在AI编程实践中，常见疑问包括：一次性生成需求代码是否高效？AI的能力边界在哪？能否拓展至更多场景？作者基于长期探索，分享从原理到落地的完整经验。文章以Cursor为核心案例，同时针对国内环境推荐Qwen3-Coder等替代模型，并介绍Qwen Code、iFlow、Qoder等新兴工具。

二、从原理讲起，了解 AI 编程工具的能力和边界

2.1 Token计算机制

2.1.1 原理

不同模型具有上下文长度限制，一次请求的Token消耗由以下部分构成：

• 初始输入 = System Prompt + 用户问题 + Rules + 对话历史
• 用户问题：输入文字 + 主动添加的上下文（图片、文件、目录）
• Rules：项目规则（project rule）+ 用户规则（user rule）+ 记忆信息（memories）
• 工具调用结果：调用read_file、codebase_search等工具后返回的内容将累计计入总Token

2.1.2 示例：分析函数问题

用户提问“这个函数有什么问题？”并附带代码截图与相关文件。

[SystemPrompt] 你是一个专业的代码审查助手...
[用户问题] 这个函数有什么问题？
[图片] [代码截图]
[项目目录] /Users/KuBo/IdeaProjects/someproject/
[当前文件] somemodule/src/main/java/com/xxx/xxx/service/ExampleService.java
[Rules]
- 多模块Maven项目，使用Java 8
- 始终使用中文回复
- 单行不超过120字符
[对话历史]
用户: 你好，我想了解一下这个项目的结构
AI: 这是一个多模块的Maven项目...

[工具调用结果1] 文件内容:
public class ExampleService {
    public String processData(String input) {
        if (input == null) {
            return null; // 问题：应抛异常而非返回null
        }
        // ... 更多代码
    }
}

[工具调用结果2] 搜索结果:
异常处理最佳实践建议...

[工具调用结果3] 语法检查:
Line 5: 建议使用Objects.requireNonNull()进行空值检查

Token计算示例：

• 初始输入：System Prompt(500) + 用户问题(200) + Rules(800) + 历史(300) = 1800 tokens
• 工具调用结果：文件(2000) + 搜索(1500) + 检查(300) = 3800 tokens
• 总计：1800 + 3800 = 5600 tokens

2.2 工具调用

大语言模型本身无法直接访问私有代码库或执行操作，需通过“工具调用”（Function Call）实现交互。

2.2.1 搜索

用于语义或文本搜索代码库及相关网络信息。

2.2.2 编辑

支持对文件和代码库进行精确修改。

2.2.3 运行

可与终端交互，执行命令或运行程序。

2.2.4 MCP

通过配置的MCP服务器连接数据库或第三方API。

2.2.5 Browser

新版Cursor内置浏览器自动化功能，无需手动配置MCP，可辅助前端自动化任务。

2.3 代码库检索

2.3.1 为何要了解

AI理解代码仓库依赖Codebase Indexing，本质是为代码构建向量索引（RAG）。掌握其机制有助于：

• 编写更有效的提问提示词；
• 制定“模型友好”的代码规范。

2.3.2 工作原理

项目导入时，Cursor启动索引流程，主要步骤如下：

1. 安全同步工作区文件至服务器；
2. 按函数、类等逻辑单元拆分代码片段；
3. 使用AI模型将片段转为向量表示；
4. 存储向量至专用数据库，支持百万级代码高速检索；
5. 用户查询同样被转为向量；
6. 系统比对查询向量与代码向量；
7. 返回按语义相似度排序的代码片段及上下文。

2.3.3 更多细节

2.3.3.1 索引构建

初始化阶段：

• 扫描项目文件，建立清单；
• 计算Merkle树哈希，用于变更检测；
• 依据.gitignore和.cursorignore过滤文件；
• 执行初始Merkle树同步。

增量同步机制：

• 每10分钟检测一次变更；
• 通过哈希比较识别修改文件；
• 仅上传变更部分，实现增量更新。

服务器端处理：

• 分块处理同步文件；
• 计算向量表示；
• 并行存储至Turbopuffer数据库与AWS缓存。

2.3.3.2 用户查询流程

• 查询向量化：本地计算自然语言查询的向量；
• 相似度搜索：在Turbopuffer中查找最相关代码片段；
• 代码片段获取：客户端根据路径和行号读取本地代码；
• AI答案生成：将代码片段上传服务器，结合上下文生成回答。

2.3.3.3 极致速度：Merkle Tree 增量验证

Cursor通过离线索引与Merkle Tree实现高速检索：

• 导入：索引耗时约10分钟，一次建立长期有效；
• 查询：embedding与检索均在秒级完成；
• 增量导入：依赖Merkle Tree快速定位变更。

Merkle Tree（哈希树）结构：

• 叶子节点：存储数据块的哈希值；
• 非叶子节点：存储子节点哈希拼接后的哈希值。

Merkle Tree作用：

• 高效验证：验证复杂度O(log n)，远低于O(n)；
• 完整性保证：根哈希不变则数据未被篡改；
• 增量同步：快速定位变更数据块。

2.4 Cursor 调用 LLM 的 Prompt

以下是Cursor调用大模型的核心Prompt，包含角色定义、工具调用规则、代码修改与检索准则：

You are a powerful agentic AI coding assistant, powered by [some model]. You operate exclusively in [some IDE], the world's best IDE.
You are pair programming with a USER to solve their coding task.

<tool_calling>
Follow these rules regarding tool calls:
1. ALWAYS follow the tool call schema exactly.
2. NEVER call tools that are not explicitly provided.
3. **NEVER refer to tool names when speaking to the USER.**
4. Only call tools when necessary.
5. Before calling each tool, explain to the USER why you are calling it.
</tool_calling>

<making_code_changes>
When making code changes, NEVER output code to the USER unless requested. Instead use edit tools.
Key rules:
1. Group edits to the same file in a single tool call.
2. For new projects, create dependency files and README.
3. Ensure generated code is runnable.
4. NEVER generate long hashes or binary data.
5. Read file contents before editing, unless appending.
6. Fix linter errors up to 3 times, then ask user.
7. Reapply failed edits.
</making_code_changes>

<searching_and_reading>
Rules for search/read tools:
1. Prefer semantic search over grep.
2. Read larger sections at once.
3. Stop calling tools once sufficient info is found.
</searching_and_reading>

<functions>
... (function definitions for codebase_search, read_file, run_terminal_cmd, etc.)
</functions>

Answer using relevant tools if available. Use format ```startLine:endLine:filepath``` for code citations.

2.5 Claude Code CLI 工具基础原理

2.5.1 国内如何使用CLI工具

由于Claude模型在国内受限，可通过阿里云百炼平台的Qwen3 Coder模型实现替代。配置方式如下：

1. 获取百炼平台API Key：bailian.console.aliyun.com/?tab=model#/api-key
2. 设置环境变量：

export ANTHROPIC_BASE_URL=https://dashscope.aliyuncs.com/api/v2/apps/claude-code-proxy
export ANTHROPIC_AUTH_TOKEN="your_api_key"

其他CLI工具也可采用类似代理方案。

2.5.2 模型调用Prompt实例

Claude Code的系统提示词包含用户环境、任务管理（TODO）、代码风格遵循等上下文工程设计：

You are Claude Code, Anthropic's official CLI for Claude.
# Proactiveness
Balance between taking initiative and avoiding surprises.

# Following conventions
- Check existing libraries before using them.
- Mimic code style and naming patterns.
- Follow security best practices. Never commit secrets.

# Task Management
Use TodoWrite/TodoRead tools frequently to track progress.
Break complex tasks into steps. Mark todos as completed immediately.

# Tool usage policy
- Prefer Task tool for file search.
- Use Batch for parallel tool calls.
- Answer concisely (<4 lines) unless detailed response is requested.

<env>
Working directory: /Users/xxx/Projects/xxx
Platform: macos
Model: someModel
</env>

<context name="directoryStructure">
Project file structure snapshot...
</context>

2.6 话又说回来了

2.6.1 提升对话质量：合理利用上下文窗口

为最大化有限上下文价值，建议采取以下行动：

Action 1：清晰描述问题

提供具体的功能、文件名、方法名或代码块，帮助模型通过语义检索快速定位目标，减少无关信息干扰。

Action 2：把控上下文长度

多数工具会显示上下文占用比例（如18.0%）。超出后历史内容将被压缩，导致信息丢失。处理复杂问题时，建议选用上下文窗口更大的模型。

Action 3：善用Revert与新开对话

维持上下文简洁有助于提升回答质量。新问题若与历史无关，应开启新对话。多轮对话中若某步出错，应回退（Revert）至错误点，重新调整prompt，避免累积无效内容。

Action 4：提供多元化信息

除代码和图片外，可引入网页链接、Git历史、当前打开文件等作为上下文。IDE类工具对此支持较好，CLI工具有限但更灵活。

上下文进阶用法：高级用户可通过Markdown文本在多个工具间传递信息，实现自动化流水线，此为上下文工程的高阶应用。

2.6.2 关于Rule

Rule是一种可复用的上下文，用于固化通用规范，节约沟通成本。

2.6.2.1 Cursor 中的 Rule

Project Rule：与项目绑定，存放于项目根目录下的.cursor目录中，可通过`/Generate Cursor Rules`命令生成。

Always	始终包含在模型上下文中
Auto Attached	当引用匹配glob模式的文件时包含
Agent Requested	AI决定是否包含，需提供描述
Manual	仅当使用@ruleName明确提及

User Rule：全局规则，影响所有项目，规则文件位于用户根目录。更新非实时生效，推测后台使用RAG索引。

常用User Rule示例：

• 遇争议或不确定时，必须主动告知用户决策；
• 需补充信息时应询问，而非自行修改；
• 不生成测试文件、文档、日志等，除非明确要求；
• 每次改动遵循最小范围原则。

2.6.2.2 Claude Code / CodeX 中的 Rule

Claude Code已将常见痛点（如避免生成过多单测）写入系统提示词，体现对用户体验的深度优化。

项目级规则通过`/init`指令生成Markdown文件（CLAUDE.md或AGENT.md），存放于项目根目录，并在对话中完整加载。用户可自定义内容，如“永远使用中文”。

生成规则的过程本质是Prompt+工具调用，自动将大量上下文注入对话。例如CodeX使用以下Prompt生成AGENT.md：

Generate a file named AGENTS.md that serves as a contributor guide...
Document Requirements:
- Title: "Repository Guidelines"
- Use Markdown headings
- Keep concise (200-400 words)
- Provide examples where helpful

Recommended Sections:
- Project Structure & Module Organization
- Build, Test, and Development Commands
- Coding Style & Naming Conventions
- Testing Guidelines
- Commit & Pull Request Guidelines

2.6.3 采用渐进式开发，而非大需求一口气生成

不建议让AI基于完整方案一次性生成全部代码（极小需求除外），因需求越大代码质量越差。推荐采用“结对编程”模式：

1. 与AI讨论具体方案与最佳实践；
2. 拆解需求，人工控制每个代码块的生成；
3. 生成后咨询代码是否优雅、有无重构空间，并按需调整。

优势：

• 小粒度任务在有限上下文中完成度更高；
• 便于分步进行代码审查。

该方式虽较费脑，但质量可控。梭哈式开发可通过SPEC工作流或多智能体实现自动化，但属另一课题。最终应以结果为导向，选择最适合自身的方式。

三、讲讲应用

以下结合具体场景，展示AI编程工具的实际应用，帮助落地前述原则，并拓展使用边界。

3.1 快速熟悉项目 & 自然语言检索代码

利用自然语言提问，快速理解项目结构与代码位置：

讲解一下这个项目的每个module都是用来做什么的，并且给出包依赖关系图。
我希望实现一个「用户登录」功能，需要修改的部分包括「认证服务」和「前端页面」，我的代码放在哪个包/目录下比较合适？请分析项目结构并说明理由。
我在找「订单超时关闭」功能的实现，请帮我在仓库里搜寻，并给出核心代码位置和片段，附上简洁说明。

3.2 PlantUML / Mermaid 文本绘图生成

结合截图与需求描述，让AI生成流程图。

用户提供接口请求截图，并说明：“请根据此截图生成前后端交互流程图，忽略与‘支付回调’无关的接口”。

AI经分析后输出准确的流程图。

3.3 问题排查

对于不熟悉的项目，可借助AI快速定位问题。

用户提供执行流程图，指出“左侧节点输出异常”，请求协助排查。

AI成功定位问题代码并给出详细分析与解决方案，验证准确有效。

3.4 补充网页信息到上下文

Web搜索是易被忽视但强大的功能，可通过@Web或直接粘贴链接添加。

注意：需权限认证的内网页面无法读取。

直接粘贴链接，AI可总结网页内容或基于其进行问答。

四、推荐的 Coding 方式

4.1 rule 的制定和优化

项目规则应包含技术栈、依赖版本及编码规范。

注：统一使用Cursor的Rule需团队共识。使用其他工具时，可维护项目规则文档并在对话时手动添加。

4.2 文档

在项目根目录维护以下文件：

• README.md：简介、特性、快速开始、文档索引；
• CHANGELOG.md：适用于发版项目，记录新增功能、Bug修复、破坏性变更等；
• ARCHITECTURE.md：适用于复杂架构项目，包含整体架构、模块划分、核心流程图。

建立/docs目录，内容兼顾实用性、准确性与可维护性，可包含：

• 错误码体系（格式、分类、场景）；
• 异常处理指南（重试策略、抛出原则、日志要求、案例）；
• 常用工具类说明。

注：以上为推荐框架，需根据项目实际情况调整。

4.3 注释和命名

1. 方法、参数注释应语义清晰、内容完整；
2. 可补充调用方使用场景；
3. 适当添加行内注释，说明分支逻辑；
4. 命名需清晰、无歧义；
5. AI生成代码占比＞80%的文件，建议添加@author AI Assistant标识。

4.4 安全合规问题

需严格遵守公司关于数据安全与合规使用的相关规定。

4.5 推广方式

团队内部创建示例仓库，持续优化推广内容：

• 范围确定：梳理核心代码库；区分面向人与LLM的文档；
• Docs资产：按项目定制markdown内容，由应用负责人初始化；
• Project Rule：按项目定制，产出为markdown并存于仓库，由负责人初始化；
• User Rule：产出团队通用规约，内容简洁，不放仓库；通过脚本在各应用间一键同步。