@ 和 # 引用技巧学习记录

学习日期：2026-03-13
所属阶段：阶段一 - 基础掌握

---

工具概述

Claude Code 支持两种引用语法，让你在对话中精准指向文件和代码：

引用类型	语法	用途
@ 引用	@文件名	引用文件
# 引用	#符号名	引用代码符号（类、方法、变量）

---

@ 引用 - 文件引用

基本语法

@文件名              # 模糊匹配
@path/to/file.md    # 指定路径
@008                # 匹配 008-xxx.md

实践案例

案例 1：快速引用文件

操作：在对话中输入

请帮我检查 @008-Claude Code深入学习计划.md 的内容

效果：
- Claude Code 自动识别并加载文件
- 可以直接基于文件内容回答或修改

案例 2：模糊匹配

操作：

@008

效果：
- 显示所有以 008 开头的文件列表
- 可以选择具体的文件

案例 3：多文件对比

操作：

对比 @001.md 和 @002.md 的区别

效果：
- 同时加载两个文件
- 可以进行对比分析

---

# 引用 - 符号引用

基本语法

#类名               # 引用类定义
#方法名             # 引用方法定义
#变量名             # 引用变量

⚠️ 重要前提

# 引用只有在符号已加载到上下文中才有效！

符号加载方式：
1. 用 Read 读取过包含该符号的文件
2. 用 @ 引用过该文件
3. 对话中之前提到过该文件

实践案例

案例 1：创建示例代码文件

创建文件：sample-code.kt

package com.example

data class User(
    val id: Int,
    val name: String,
    val email: String
) {
    fun isValidEmail(): Boolean {
        return email.contains("@")
    }

    fun getDisplayName(): String {
        return "$name (ID: $id)"
    }
}

class UserManager {
    private val users = mutableListOf<User>()

    fun addUser(user: User) {
        users.add(user)
    }

    fun findUserById(id: Int): User? {
        return users.find { it.id == id }
    }
}

fun main() {
    val manager = UserManager()
    val user = User(1, "张三", "zhangsan@example.com")
    manager.addUser(user)
}

案例 2：加载符号

执行：

Read file_path="ClaudeCode/sample-code.kt"

效果：
- 文件内容加载到上下文
- 符号可以被 # 引用

案例 3：引用类

操作：在对话中输入

#User 类中的 #isValidEmail 方法有什么作用？

预期效果：
- 引用 User 类的定义（第 6-24 行）
- 引用 isValidEmail 方法（第 14-16 行）

案例 4：引用方法

操作：

请解释 #UserManager.addUser 的实现逻辑

预期效果：
- 引用 UserManager 类的 addUser 方法
- 基于具体代码进行解释

---

@ 与 # 引用对比

特性	@ 引用	# 引用
引用目标	文件	代码符号
语法	@文件名	#符号名
前提条件	无	符号必须先加载
适用场景	文档、代码文件	代码文件中的类/方法/变量
自动完成	✅ 有	✅ 有（加载后）

---

实际应用场景

场景 1：代码审查

@UserService.kt 中的 #createUser 方法有问题，
第 25 行的参数验证逻辑需要完善。

场景 2：跨文件对比

对比 @UserService.kt 和 @UserManager.kt 中
#getUserById 方法的实现差异。

场景 3：基于现有代码修改

参考 @sample-code.kt 中的 #User 类，
在 @UserRepository.kt 中添加类似的验证方法。

场景 4：文档查询

根据 @CLAUDE.md 的配置，
说明 #EnterPlanMode 的使用场景。

---

常见问题

Q1: # 引用无效怎么办？

原因：符号未加载到上下文

解决：

# 方法 1：先 Read 文件
Read file_path="file.kt"

# 方法 2：用 @ 引用文件
@file.kt

# 然后再使用 # 引用
#ClassName

Q2: @ 引用找不到文件？

原因：
1. 文件名拼写错误
2. 文件不在当前目录

解决：

# 使用完整路径
@ClaudeCode/filename.md

# 或使用 Glob 查找
Glob pattern="**/filename.md"

Q3: 符号名冲突怎么办？

解决：使用更完整的引用

# 使用类名限定
UserManager#addUser

# 或使用文件限定
@file.kt #addUser

---

最佳实践

✅ 推荐	❌ 避免
使用 @ 快速引用文件	完整写出文件路径
加载后再使用 # 引用	未加载就使用 # 引用
结合 @ 和 # 精准定位	只用模糊描述
使用简短文件名匹配	输入完整长文件名

---

学习检查点

• [x] 理解 @ 引用文件的方法
• [x] 理解 # 引用符号的方法
• [x] 掌握 # 引用的前提条件（符号必须先加载）
• [x] 能在对话中正确使用 @ 和 #

掌握度：⭐⭐⭐⭐

---

备注

• # 引用在代码文件中效果最好
• Markdown 文档中的代码块也可以被引用
• 使用引用可以大幅减少上下文描述的长度