Claude Code CLI 入门：/init、.claude 目录与 .claudeignore 配置指南

Claude Code CLI 是 Anthropic 推出的 AI 编码助手，直接在终端中工作。使用前，理解 /init 命令、.claude 目录结构和 .claudeignore 配置是基本功。

一、/init 命令

/init 是 Claude Code 的交互式命令，用于自动扫描整个项目并生成 CLAUDE.md。

当前限制

/init 不支持指定输出目录。它默认生成在两个位置之一：

1. 项目根目录 → ./CLAUDE.md
2. .claude/ 目录 → ./.claude/CLAUDE.md

想放 .claude 目录下怎么办？

手动创建即可。/init 扫描完项目后，把生成的 CLAUDE.md 内容复制到 .claude/CLAUDE.md 里，两处都生效，但 .claude/ 下的优先级更高。

二、.claude 目录结构

两个目录，不是同一个

层级	路径	用途	提交
项目级	.claude/	团队共享配置	提交到 Git
全局	~/.claude/	个人偏好、会话历史、自动记忆	不提交

完整目录结构

your-project/
├── CLAUDE.md                        # 项目指令（提交）
├── CLAUDE.local.md                  # 个人覆盖（被 gitignore）
└── .claude/
    ├── settings.json                # 权限 + 配置（提交）
    ├── settings.local.json          # 个人权限覆盖（被 gitignore）
    ├── .mcp.json                    # MCP 服务器配置
    ├── rules/                       # 模块化指令文件
    │   ├── code-style.md
    │   ├── testing.md
    │   └── api-conventions.md
    ├── commands/                    # 自定义斜杠命令
    │   ├── review.md                # 成为 /project:review
    │   └── fix-issue.md             # 成为 /project:fix-issue
    ├── skills/                      # 自动触发的工作流
    │   └── deploy/
    │       ├── SKILL.md
    │       └── deploy-config.md
    ├── agents/                      # 专用子代理
    │   ├── code-reviewer.md
    │   └── security-auditor.md
    └── hooks/                       # 事件驱动自动化脚本
        └── validate-bash.sh

~/.claude/
├── CLAUDE.md                        # 全局指令（所有项目）
├── settings.json                    # 全局权限
├── commands/                        # 个人命令（/user:cmd-name）
├── skills/                          # 个人技能
├── agents/                          # 个人代理
└── projects/                        # 会话历史 + 自动记忆
    └── project-hash/
        └── memory/
            └── MEMORY.md

CLAUDE.md 加载优先级

最高  CLAUDE.local.md（项目根目录，个人覆盖，被 gitignore）
  ↑   CLAUDE.md（项目根目录或 .claude/，团队指令，提交到 Git）
  ↑   ~/.claude/CLAUDE.md（全局偏好，所有项目生效）
最低  组织策略（IT 部署，不可覆盖）

所有层合并 → Claude 看到的是一个完整的系统提示。

三、.claudeignore 配置规则

是什么

.claudeignore 放在项目根目录，告诉 Claude 在构建上下文时跳过哪些文件/目录，语法与 .gitignore 完全一致。

核心作用

作用	说明
节省上下文 Token	排除大文件、构建产物，避免浪费
防止干扰	排除 WIP 文档、废弃代码，避免 Claude 误读
保护敏感文件	排除 .env、密钥文件等

重要警告

.claudeignore 不是安全机制！ 它只是一个上下文过滤器。如果用户明确要求 Claude 读取某个被 ignore 的文件，它仍能通过 Read 工具读到。保护敏感信息请用 settings.json 的 deny 规则，而不是 .claudeignore。

语法（同 .gitignore）

# 单行注释

# 忽略特定文件
.env
secrets.json

# 忽略目录
node_modules/
dist/
build/

# 通配符
*.log
*.tmp

# 忽略嵌套目录
**/__pycache__/

# 忽略特定扩展名
*.zip
*.tar.gz

推荐 .claudeignore

# 构建产物
node_modules/
dist/
build/
target/
out/
.next/
.nuxt/

# 包管理锁文件（内容太大，无关上下文）
package-lock.json
yarn.lock
pnpm-lock.yaml

# 大文件
*.zip
*.tar.gz
*.pdf
*.mp4
*.svgz

# 日志
*.log
logs/

# 临时文件
*.tmp
*.swp
.DS_Store
Thumbs.db

# 敏感文件（但更推荐在 settings.json 的 deny 里也加上）
.env
.env.*
!env.example
secrets/
credentials/

.claudeignore vs settings.json deny

机制	作用	安全性
.claudeignore	上下文过滤，不阻止显式读取	❌ 低
settings.json deny	真正阻止工具调用	✅ 高

推荐组合配置

// .claude/settings.json
{
  "permissions": {
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(./secrets/**)"
    ]
  }
}

.claudeignore 排除上下文噪音，settings.json deny 锁死安全边界，两者配合使用效果最佳。

四、总结

• /init 不能指定输出目录，手动放 .claude/ 下即可
• .claude/ 目录是 Claude Code 的配置中心，从 CLAUDE.md 到 hooks 一应俱全
• .claudeignore 语法同 .gitignore，用来省 Token 和防干扰
• 别用 .claudeignore 来保护敏感信息，那是 settings.json 的事