核心定位

Claude Code 定位为开发者的智能编程伙伴，而非简单的代码补全工具。它具备以下核心能力：

最新版本为 v2.1.158，已在 Bedrock、Vertex 和 Foundry 平台为 Opus 4.7 和 Opus 4.8 提供 Auto mode 支持。

插件架构

Claude Code 采用模块化插件架构，允许开发者扩展核心功能。插件系统包含以下组件类型：

组件类型概览

插件结构示例

graph TD
    A[插件根目录] --> B[commands/]
    A --> C[skills/]
    A --> D[agents/]
    A --> E[hooks/]
    A --> F[MCP配置]
    A --> G[README.md]
    
    B --> B1[.md 命令文件]
    C --> C1[SKILL.md]
    C --> C2[references/]
    C --> C3[examples/]
    D --> D1[agent markdown]

内置插件

Claude Code 仓库包含多个官方插件，位于 plugins/ 目录下：

功能开发工作流

feature-dev 插件实现了标准化的 7 阶段开发流程：

graph LR
    A[Phase 1: Discovery<br/>理解需求] --> B[Phase 2: Exploration<br/>代码库探索]
    B --> C[Phase 3: Questions<br/>澄清问题]
    C --> D[Phase 4: Design<br/>架构设计]
    D --> E[Phase 5: Implementation<br/>实现]
    E --> F[Phase 6: Validation<br/>验证检查]
    F --> G[Phase 7: Documentation<br/>文档完善]

每个阶段都有明确的目标和交付物，确保功能开发的完整性和质量。

插件开发框架

plugin-dev 是官方提供的插件开发框架，包含以下开发技能：

钩子系统

Claude Code 支持事件驱动的钩子机制，主要类型包括：

钩子配置通过 hooks/hooks.json 管理，支持提示词模式和脚本模式。

代码审查功能

内置的代码审查功能包括：

• CLAUDE.md 合规检查：验证代码是否符合项目规范
• 测试覆盖分析：检查测试用例完整性
• 静默失败检测：识别 catch 块中的问题
• 类型设计审查：评估 TypeScript 类型使用
• 代码简化建议：识别可优化代码

安装与使用

全局安装

npm install -g @anthropic-ai/claude-code

项目级使用

在项目中安装后，通过以下方式使用：

# 进入项目目录
cd your-project

# 启动 Claude Code
claude

插件安装

/plugin install <plugin-name>@<source>

支持的插件来源包括官方 marketplace 和 GitHub 仓库。

社区热点问题

根据社区反馈，以下问题值得关注：

相关资源

• 官方文档：查看仓库中的 docs/ 目录
• 社区插件：awesome-claude-code 仓库收集第三方插件
• 问题反馈：通过 GitHub Issues 提交 bug 或功能请求

系统要求

Claude Code 对运行环境有以下基本要求：

额外依赖：

• GitHub CLI (gh) - 用于某些插件功能（如 PR 审查）
• Docker - 仅在使用 Dev Container 场景下需要

资料来源：README.md:1-50

全局安装

通过 npm 安装

Claude Code 提供全局 npm 包，可通过以下命令安装：

npm install -g @anthropic-ai/claude-code

安装完成后，在任意项目目录中运行以下命令启动 Claude Code：

claude

资料来源：README.md:1-30

验证安装

安装完成后，可通过以下命令验证版本：

npx @anthropic-ai/claude-code --version

确保使用最新版本以获得最新功能和安全修复。

插件系统安装

内置插件

Claude Code 仓库自带多个内置插件，这些插件位于 plugins/ 目录下。要使用这些插件：

1. 安装 Claude Code 全局包
2. 在项目中运行 claude
3. 使用 /plugin 命令安装所需插件

插件安装命令

/plugin install <plugin-name>

例如，安装代码审查插件：

/plugin install code-review

资料来源：plugins/README.md:1-50

可用插件列表

资料来源：plugins/README.md:50-150

开发环境配置

Dev Container 方式

Claude Code 支持通过 Docker Dev Container 运行，提供一致的开发环境。

#### 前置条件

1. 安装 Docker Desktop
2. 安装 VS Code Remote - Containers 扩展
3. 克隆 Claude Code 仓库

#### 启动 Dev Container

Windows (PowerShell)：

.\Script\run_devcontainer_claude_code.ps1

资料来源：Script/run_devcontainer_claude_code.ps1:1-50

#### Dockerfile 配置

Dev Container 使用以下基础镜像配置：

FROM node:20-slim

# 安装必要工具
RUN apt-get update && apt-get install -y \
    git \
    curl \
    gh

# 设置工作目录
WORKDIR /workspace

资料来源：.devcontainer/Dockerfile:1-30

工作流程图

graph TD
    A[开始安装] --> B{选择安装方式}
    B -->|npm 全局安装| C[npm install]
    B -->|Dev Container| D[克隆仓库]
    C --> E[运行 claude 命令]
    D --> F[运行 Dev Container 脚本]
    F --> G[VS Code 连接容器]
    E --> H[配置插件和设置]
    G --> H
    H --> I[开始使用 Claude Code]

项目级配置

初始化新项目

首次在项目中使用 Claude Code 时，会自动创建 .claude/ 配置目录：

project/
├── .claude/
│   └── settings.json      # 项目级设置
├── CLAUDE.md              # 项目指南 (可选)
└── ...

settings.json 配置

项目级设置文件示例：

{
  "permissions": {
    "defaultMode": "auto"
  },
  "plugins": []
}

CLAUDE.md 项目指南

在项目根目录创建 CLAUDE.md 文件，可定义项目特定的行为规范和约定。资料来源：plugins/README.md:1-20

身份验证配置

Anthropic API 密钥

Claude Code 需要有效的 Anthropic API 密钥才能运行。有两种配置方式：

``bash export ANTHROPIC_API_KEY=your-api-key ``

1. 环境变量：

首次运行时，Claude Code 会提示输入 API 密钥

1. 交互式输入：

GitHub CLI 身份验证

某些功能（如 PR 审查）需要 GitHub CLI：

gh auth login

资料来源：plugins/code-review/README.md:1-30

常见安装问题

问题：命令未找到

症状： 安装后运行 claude 提示命令不存在

解决方案：

# 确认安装位置
npm list -g @anthropic-ai/claude-code

# 检查 PATH
npm bin -g

问题：权限错误

症状： 写入配置目录时权限被拒绝

解决方案：

• Linux/macOS：确保配置目录存在且有写入权限
• Windows：以管理员身份运行或使用 PowerShell

问题：插件安装失败

症状： /plugin install 命令执行失败

解决方案：

1. 检查网络连接
2. 确认 npm 源配置正确
3. 尝试清除缓存：npm cache clean --force

资料来源：plugins/commit-commands/README.md:1-30

环境变量

可用环境变量

资料来源：README.md:50-100

Auto 模式启用

Auto 模式现已支持 Bedrock、Vertex 和 Foundry 平台。要启用：

export CLAUDE_CODE_ENABLE_AUTO_MODE=1

适用于 Opus 4.7 和 Opus 4.8 模型。

升级与维护

升级 Claude Code

npm update -g @anthropic-ai/claude-code

查看当前版本

claude --version

卸载

npm uninstall -g @anthropic-ai/claude-code

快速开始流程

graph LR
    A[安装 Node.js] --> B[npm 全局安装]
    B --> C[运行 claude 命令]
    C --> D{首次运行}
    D -->|未配置| E[输入 API 密钥]
    D -->|已配置| F[开始使用]
    E --> F
    F --> G[可选: 安装插件]
    G --> H[可选: 创建 CLAUDE.md]

相关资源

• 官方文档：Anthropic Claude Code
• GitHub 仓库：anthropics/claude-code
• 插件市场：社区开发的插件可在 awesome-claude-code 找到
• Claude Code 安全审查工具：claude-code-security-review

概述

Claude Code 是 Anthropic 官方推出的命令行工具，旨在帮助开发者通过 AI 辅助完成编码任务。作为一款终端集成开发环境，Claude Code 能够理解代码库结构、执行文件操作、运行命令，并与各种开发工具链无缝协作。

本快速上手指南将帮助新用户：

• 完成 Claude Code 的初始配置
• 理解基本工作流程
• 掌握核心命令和功能
• 使用插件扩展功能
• 了解常见问题的解决方案

环境要求与安装

系统要求

Claude Code 支持主流操作系统，包括 macOS、Linux 和 Windows。

安装方式

Claude Code 通过 npm 全局安装：

npm install -g @anthropic-ai/claude-code

安装完成后，运行 claude 命令启动：

claude

资料来源：README.md:1-10

首次启动配置

身份验证

首次启动时，Claude Code 会引导完成 Anthropic API 密钥配置：

1. 系统会提示输入 ANTHROPIC_API_KEY
2. 可从 Anthropic Console 获取密钥
3. 密钥会自动保存到配置文件

权限模式配置

Claude Code 提供三种权限模式控制工具使用范围：

可通过 ~/.claude/settings.json 配置默认模式：

{
  "defaultMode": "auto"
}

⚠️ 已知问题：auto 权限模式不会在新会话中继承，且无法在会话中途设置。详情参见 GitHub Issue #55558。

资料来源：plugins/README.md:50-80

基本工作流程

会话生命周期

graph TD
    A[启动 Claude Code] --> B[创建新会话]
    B --> C[发送请求/任务]
    C --> D{Claude 分析请求}
    D -->|需要更多信息| E[提问澄清]
    E --> C
    D -->|执行工具| F[读写文件/运行命令]
    F --> G{操作完成?}
    G -->|否| C
    G -->|是| H[返回结果]
    H --> I[结束会话]

核心交互模式

Claude Code 支持多种交互方式：

直接对话模式

claude
> 帮我创建一个用户登录功能

文件参考模式

> 审查这个文件的代码质量
@src/auth/login.ts

命令模式

/help
/model
/agent

工具使用

Claude Code 可调用多种工具完成任务：

资料来源：plugins/feature-dev/commands/feature-dev.md:1-30

项目级配置

CLAUDE.md 文件

在项目根目录创建 CLAUDE.md 文件，可以为 Claude Code 提供项目特定的指令和上下文：

# 项目指南

## 技术栈
- 前端框架：React 18
- 后端：Node.js + Express
- 数据库：PostgreSQL

## 代码规范
- 使用 TypeScript strict 模式
- 组件文件首字母大写
- 优先使用函数式组件

## 常用命令
- 开发服务器：`npm run dev`
- 运行测试：`npm test`
- 构建生产版本：`npm run build`

配置文件位置

Claude Code 按以下优先级读取配置：

1. ./.claude/ - 项目级配置
2. ~/.claude/ - 用户级配置
3. 系统默认配置

⚠️ 已知问题：CLAUDE.md 规则不会传递给 Agent 子代理，且在上下文压缩后会弱化。详情参见 GitHub Issue #59309。

插件系统

插件架构

Claude Code 采用插件化架构，允许用户扩展核心功能：

graph TD
    A[Claude Code Core] --> B[Commands 命令]
    A --> C[Skills 技能]
    A --> D[Agents 代理]
    A --> E[Hooks 钩子]
    A --> F[MCP 服务器]
    
    B --> B1[/slash commands]
    C --> C1[Auto-triggered guidance]
    D --> D1[Specialized subagents]
    E --> E1[Event-driven automation]
    F --> F1[External integrations]

官方插件列表

资料来源：plugins/README.md:1-50

安装和使用插件

方式一：使用 /plugin 命令

/plugin
# 选择 marketplace 中的插件进行安装

方式二：手动配置

在项目的 .claude/settings.json 中添加：

{
  "plugins": [
    "feature-dev",
    "code-review",
    "hookify"
  ]
}

功能开发工作流

使用 feature-dev 插件可以遵循系统化的 7 阶段开发流程：

# 启动功能开发工作流
/feature-dev 添加用户认证功能

资料来源：plugins/feature-dev/README.md:1-80

常见工作场景

代码审查

使用 code-review 插件进行自动化 PR 审查：

# 本地审查，输出到终端
/code-review

# 发布为 PR 评论
/code-review --comment

该插件会并行启动多个代理分析：

• CLAUDE.md 合规性
• Bug 检测
• 历史上下文分析
• PR 历史分析
• 代码注释分析

Git 工作流

Claude Code 内置 Git 命令简化常见操作：

问题分类

使用 /triage-issue 命令自动分类 GitHub Issue：

/triage-issue
# 输入 Issue 链接或内容
# 自动分类：bug/feature/docs 等

故障排除

常见问题

#### 1. 模型加载超时

症状：/model 命令显示 "Loading models..." 无响应。

解决方案：

• 检查网络连接
• 验证 API 密钥有效性
• 尝试重启 Claude Code

详情参见 GitHub Issue #59646

#### 2. 终端渲染异常 (Windows)

症状：TUI 视图线条重叠或堆叠。

解决方案：

• 使用最新版本 Windows Terminal
• 尝试切换到 PowerShell 7.6+
• 更新 Claude Code 到最新版本

详情参见 GitHub Issue #58579

#### 3. 速率限制问题

症状：操作被限制，提示达到使用上限。

解决方案：

• 检查 API 使用量
• 等待限制重置（注意：实际周期约 24 小时，而非文档所述 7 天）

详情参见 GitHub Issue #52921

#### 4. MCP 服务器崩溃

症状：插件市场列表操作崩溃，显示 "Illegal instruction"。

解决方案：

• Bun 构建版本问题，需要更新
• 切换到 Node.js 运行时

详情参见 GitHub Issue #59645

日志和调试

Claude Code 运行时可添加调试标志：

CLAUDE_DEBUG=1 claude

日志文件位置：

• macOS/Linux：~/.claude/logs/
• Windows：%USERPROFILE%\.claude\logs\

最佳实践

提高响应质量

1. 提供清晰的任务描述

• 明确说明期望结果
• 提供相关文件路径
• 说明约束条件

1. 使用文件引用

• 使用 @ 引用相关文件
• 提供代码片段作为上下文

1. 分步骤执行复杂任务

• 将大任务分解为小步骤
• 每步完成后确认结果

安全注意事项

1. 敏感信息处理

• 不要在对话中分享 API 密钥
• 使用环境变量存储敏感配置
• 利用 security-guidance 插件监控危险操作

1. 权限控制

• 生产环境使用 review 模式
• 定期审查已批准的权限请求

性能优化

1. 上下文管理

• 大型代码库使用 /compact 命令压缩上下文
• 定期清理不必要的对话历史

1. 插件管理

• 按需启用插件，避免加载过多未使用的组件
• 使用 hookify 插件防止不必要的重复操作

下一步

熟悉基础操作后，建议深入学习：

``bash /plugin-dev ``

1. 插件开发 - 使用 plugin-dev 插件创建自定义功能

``bash # 参考 plugins/agent-sdk-dev 文档 ``

1. Agent 开发 - 创建专门的子代理处理特定任务

``bash # 创建 .mcp.json 配置 ``

1. MCP 集成 - 连接外部服务和数据库

1. 自动化工作流 - 结合 GitHub Actions 实现 CI/CD 集成

版本信息

当前最新版本：v2.1.158

最新特性：

• Auto mode 现已支持 Bedrock、Vertex 和 Foundry 平台的 Opus 4.7 及 Opus 4.8
• 通过设置 CLAUDE_CODE_ENABLE_AUTO_MODE=1 启用

概述

斜杠命令（Slash Commands）是 Claude Code 中用于触发特定工作流程的用户命令。以 / 开头，用户可以通过斜杠命令快速调用预设的功能、工作流或自动化任务。斜杠命令系统是 Claude Code 插件体系的核心组件之一，与技能（Skills）、代理（Agents）、钩子（Hooks）和 MCP 服务器共同构成了完整的插件扩展生态。

斜杠命令采用 Markdown 格式定义，结合 YAML frontmatter 元数据配置，使得命令的开发、维护和分发变得简单直观。开发者无需编写复杂的代码，只需按照约定的格式创建 Markdown 文件即可定义新的命令。资料来源：plugins/plugin-dev/skills/command-development/README.md:1-15

架构设计

核心组件

斜杠命令系统的架构包含以下核心组件：

资料来源：plugins/plugin-dev/skills/command-development/SKILL.md:1-30

命令执行流程

graph TD
    A[用户输入 /command-name] --> B[解析命令名称]
    B --> C{查找命令定义}
    C -->|找到| D[加载命令文件]
    C -->|未找到| E[返回 Unknown skill 错误]
    D --> F[解析 Frontmatter]
    F --> G[替换变量占位符]
    G --> H[执行命令逻辑]
    H --> I[返回执行结果]

命令文件结构

基本格式

每个斜杠命令由一个 Markdown 文件定义，文件结构如下：

概述

Agent（代理）是 Claude Code 中用于执行特定任务的自主子程序。通过 Agent 系统，Claude Code 能够将复杂任务分解为多个专门化的子任务，每个子任务由专门的代理处理。这种设计模式使得系统能够处理多维度、高复杂度的开发工作流程，同时保持代码质量和一致性。

Agent 系统是 Claude Code 插件架构的核心组件之一，与 Commands（命令）、Hooks（钩子）、Skills（技能）和 MCP（模型上下文协议）共同构成完整的插件生态系统。 资料来源：plugins/plugin-dev/README.md:1-20

核心概念

Agent 与 Subagent 的区别

在 Claude Code 中，"Agent" 通常指用户级别的代理配置，而 "Subagent" 则指在父代理内部创建的子代理实例。根据社区反馈，CLAUDE.md 规则不会自动传播到 Subagent，这是一个已知的限制问题。 资料来源：社区 Issue #59309

Agent 的生命周期

Agent 的完整生命周期包含以下阶段：

graph TD
    A[用户触发 Agent] --> B{检查触发条件}
    B -->|匹配| C[加载 Agent 配置]
    B -->|不匹配| D[返回主会话]
    C --> E[初始化 System Prompt]
    E --> F[分配工具和资源]
    F --> G[执行任务]
    G --> H{任务完成?}
    H -->|是| I[返回结果]
    H -->|否| J[继续执行]
    J --> G
    I --> K[结果整合]

Agent 文件结构

Agent 通过 Markdown 文件定义，采用 YAML 前置元数据（frontmatter）加 Markdown 正文的结构。

文件格式

概述

Hooks 是 Claude Code 中的事件驱动自动化机制，允许开发者在特定操作执行前或执行后插入自定义逻辑。通过 Hooks，系统可以在关键时间点拦截、验证或修改行为，实现安全控制、行为提醒、自动化工作流等功能。

graph TD
    A[用户操作] --> B{Hook 触发点}
    B -->|工具执行前| C[PreToolUse Hook]
    B -->|工具执行后| D[PostToolUse Hook]
    B -->|会话停止| E[Stop Hook]
    B -->|上下文压缩| F[Compact Hook]
    
    C -->|允许| G[执行工具]
    C -->|阻止| H[显示警告]
    C -->|修改| I[工具参数]
    
    G --> D
    D --> J[结果处理]
    
    style C fill:#e1f5fe
    style D fill:#e8f5e8

核心能力：

• 在工具执行前进行验证和拦截
• 记录操作历史并分析行为模式
• 提供交互式确认提示
• 修改工具执行参数
• 自动化重复性检查任务

资料来源：plugins/plugin-dev/skills/hook-development/SKILL.md

钩子类型

Claude Code 支持多种类型的 Hook，每种类型对应不同的触发时机和用途。

资料来源：plugins/plugin-dev/skills/hook-development/references/patterns.md

PreToolUse 钩子

PreToolUse 是最常用的钩子类型，在任何工具调用之前触发。它可以：

• 验证工具参数：检查文件路径、命令安全性
• 阻止危险操作：如 rm -rf 等高风险命令
• 要求确认：向用户展示操作详情并请求确认
• 修改参数：在执行前调整工具参数

# pretooluse.py 示例 - Hookify 插件
def hook_pre_tool_use(tool_name, tool_input):
    """
    预工具使用钩子 - 在工具执行前检查
    """
    # 检查危险命令
    if tool_name == "Bash" or tool_name == "bash__":
        command = tool_input.get("command", "")
        
        # 检测 rm -rf 命令
        if "rm -rf" in command or "rm -fr" in command:
            return {
                "action": "ask",
                "message": f"⚠️ 检测到危险删除命令: {command}\n是否继续?"
            }
    
    # 检测其他危险操作
    dangerous_patterns = [
        (r"chmod\s+777", "过于宽松的文件权限"),
        (r":\(\)\{\s*:\|\:&\s*;\s*:\;\s*\}", "Fork 炸弹"),
        (r"curl.*\|.*sh", "管道执行远程脚本"),
    ]
    
    for pattern, description in dangerous_patterns:
        import re
        if re.search(pattern, command):
            return {
                "action": "reject",
                "message": f"❌ 检测到危险操作: {description}"
            }
    
    return {"action": "accept"}

资料来源：plugins/hookify/hooks/pretooluse.py

PostToolUse 钩子

PostToolUse 在工具执行完成后触发，适用于：

• 结果分析：检查命令输出中的潜在问题
• 日志记录：记录操作历史用于审计
• 后续处理：基于执行结果执行额外操作

# posttooluse.py 示例 - Hookify 插件
def hook_post_tool_use(tool_name, tool_input, tool_output):
    """
    后工具使用钩子 - 在工具执行后分析结果
    """
    # 分析 Bash 命令输出
    if tool_name == "Bash" or tool_name == "bash__":
        output = tool_output.get("content", "")
        
        # 检测潜在的敏感信息泄露
        sensitive_patterns = [
            (r"password\s*=", "密码硬编码"),
            (r"api[_-]?key\s*=", "API Key 暴露"),
            (r"-----BEGIN.*PRIVATE KEY-----", "私钥泄露"),
            (r"ghp_[a-zA-Z0-9]{36}", "GitHub Token"),
        ]
        
        warnings = []
        for pattern, description in sensitive_patterns:
            import re
            if re.search(pattern, output, re.IGNORECASE):
                warnings.append(description)
        
        if warnings:
            return {
                "action": "warn",
                "messages": [f"⚠️ 检测到: {w}" for w in warnings]
            }
    
    return {"action": "continue"}

资料来源：plugins/hookify/hooks/posttooluse.py

安全提醒钩子

security-guidance 插件提供了专业的安全检查钩子：

# security_reminder_hook.py - 安全提醒钩子
SECURITY_PATTERNS = [
    ("Command Injection", [
        r"\$\([^)]+\)",           # $(command)
        r"`[^`]+`",               # `command`
        r"\|\s*sh\b",             # | sh
    ]),
    ("XSS", [
        r"innerHTML\s*=",         # innerHTML赋值
        r"document\.write",        # document.write
        r"eval\s*\(",             # eval()
    ]),
    ("Dangerous Deserialization", [
        r"pickle\.loads?",        # pickle.load/loads
        r"unpickle",              # unpickle
    ]),
    ("OS Command Injection", [
        r"os\.system\s*\(",        # os.system()
        r"os\.popen\s*\(",         # os.popen()
        r"subprocess\.call\s*\(",  # subprocess.call()
    ]),
]

资料来源：plugins/security-guidance/hooks/security_reminder_hook.py

钩子配置

hooks.json 配置结构

每个插件通过 hooks/hooks.json 文件定义钩子配置：

{
  "hooks": {
    "PreToolUse": [
      {
        "name": "security-reminder",
        "description": "提醒潜在的安全问题",
        "path": "hooks/security_reminder_hook.py"
      }
    ],
    "PostToolUse": [
      {
        "name": "operation-logger",
        "description": "记录操作历史",
        "path": "hooks/post_tool_logger.py"
      }
    ]
  }
}

配置字段说明：

资料来源：plugins/plugin-dev/skills/hook-development/references/patterns.md

钩子脚本位置规范

plugin-name/
├── hooks/
│   ├── hooks.json           # 钩子配置
│   ├── pretooluse.py        # PreToolUse 钩子实现
│   ├── posttooluse.py       # PostToolUse 钩子实现
│   └── examples/            # 示例脚本（非执行代码）
│       └── sample_check.py

重要规范：

• 钩子脚本应放置在 hooks/ 目录或子目录中
• 示例代码放置在 examples/ 目录
• 使用 ${CLAUDE_PLUGIN_ROOT} 确保路径可移植性

资料来源：plugins/plugin-dev/skills/hook-development/SKILL.md

钩子返回值

PreToolUse 返回值

graph TD
    A[PreToolUse 执行] --> B{返回 action}
    B -->|accept| C[✅ 允许工具执行]
    B -->|reject| D[❌ 阻止执行]
    B -->|ask| E[❓ 请求用户确认]
    B -->|modify| F[✏️ 修改参数后执行]
    
    E -->|用户同意| C
    E -->|用户拒绝| D
    
    style accept fill:#c8e6c9
    style reject fill:#ffcdd2
    style ask fill:#fff9c4

PostToolUse 返回值

钩子开发工作流

graph LR
    A[1. 加载 hook-development 技能] --> B[2. 创建 hooks/hooks.json]
    B --> C[3. 编写钩子脚本]
    C --> D[4. 放置到 hooks/ 目录]
    D --> E[5. 使用验证脚本测试]
    E --> F{验证结果}
    F -->|通过| G[✅ 钩子就绪]
    F -->|失败| H[🔧 修复问题]
    H --> C

开发步骤详解

步骤 1：加载技能

使用 Skill 工具加载 hook-development 技能

步骤 2：创建配置 在 hooks/hooks.json 中定义钩子元数据

步骤 3：实现钩子逻辑

钩子函数签名：

def hook_pre_tool_use(tool_name, tool_input):
    """
    Args:
        tool_name: 被调用的工具名称 (如 "Bash", "Read", "Write")
        tool_input: 工具输入参数字典
    Returns:
        dict: 包含 action 和可选 message 的字典
    """
    # 编写检查逻辑
    return {"action": "accept"}

def hook_post_tool_use(tool_name, tool_input, tool_output):
    """
    Args:
        tool_name: 被调用的工具名称
        tool_input: 工具输入参数
        tool_output: 工具执行结果
    Returns:
        dict: 包含 action 的字典
    """
    # 编写后续处理逻辑
    return {"action": "continue"}

步骤 4：验证钩子

# 验证 hooks.json 语法
./scripts/validate-hook-schema.sh

# 测试钩子脚本
./scripts/test-hook.sh <hook-type> <test-input>

资料来源：plugins/plugin-dev/skills/hook-development/SKILL.md

实际应用示例

Hookify 插件

hookify 插件展示了钩子的高级用法——通过对话分析自动创建规则：

# 从用户反馈中学习
/hookify 不要使用 console.log

# 分析最近对话自动创建规则
/hookify

工作流程：

1. 分析用户最近的纠正行为
2. 创建对应的钩子规则文件
3. 规则立即生效，无需重启

规则文件格式 (.claude/hookify.*.local.md)：

1. 系统概述

1.1 插件系统的设计理念

Claude Code 插件系统遵循以下核心设计原则：

• 渐进式披露：插件文档分为元数据层、核心文档层和资源层，用户按需获取信息
• 组件化架构：每个插件由多个独立但可协作的组件构成
• 声明式配置：使用 YAML frontmatter 和 Markdown 格式声明组件行为
• 可移植性：通过 ${CLAUDE_PLUGIN_ROOT} 环境变量实现路径可移植
• 安全优先：默认启用 HTTPS 验证，无硬编码凭证

1.2 插件与项目的集成关系

插件在 Claude Code 中的加载和执行层级如下：

graph TD
    A[Claude Code 核心] --> B[已安装插件]
    B --> C[项目级配置: .claude/settings.json]
    B --> D[用户级配置: ~/.claude/settings.json]
    C --> E[CLAUDE.md / CLAUDE.local.md]
    D --> F[插件组件]
    F --> G[Skills]
    F --> H[Commands]
    F --> I[Agents]
    F --> J[Hooks]
    F --> K[MCP Servers]

资料来源：plugins/plugin-dev/skills/plugin-structure/README.md

2. 插件目录结构

2.1 标准目录布局

每个插件遵循统一的目录结构，便于 Claude Code 自动发现和加载组件：

plugin-name/
├── manifest.json          # 插件清单（必需）
├── README.md              # 插件文档
├── SKILL.md               # 插件级技能（可选）
├── commands/              # 斜杠命令目录
│   ├── command-name.md
│   └── namespace/
│       └── command-name.md
├── skills/                # 技能目录
│   ├── skill-name/
│   │   ├── SKILL.md
│   │   └── references/
│   │       └── detail.md
│   └── another-skill/
├── agents/                # 子代理目录
│   └── agent-name.md
├── hooks/                 # 钩子配置
│   ├── hooks.json
│   └── hook-scripts/
│       └── hook-script.sh
├── mcp/                   # MCP 服务器配置
│   └── .mcp.json
└── examples/              # 示例文件（不会被加载）

资料来源：plugins/plugin-dev/skills/plugin-structure/references/component-patterns.md

2.2 清单文件 (manifest.json)

每个插件必须包含 manifest.json 作为入口点，定义插件的基本信息和组件位置：

{
  "name": "plugin-name",
  "version": "1.0.0",
  "description": "插件功能描述",
  "author": "作者信息",
  "homepage": "https://github.com/..."
}

资料来源：plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md

3. 组件类型详解

3.1 组件类型总览

资料来源：plugins/plugin-dev/skills/plugin-structure/SKILL.md

3.2 Skills（技能）

Skills 是插件的核心知识单元，包含特定领域的专业知识和行为指导。

结构规范：

skills/skill-name/
├── SKILL.md           # 必需：包含 YAML frontmatter 和核心指令
└── references/        # 可选：详细参考文档
    ├── reference-1.md
    └── reference-2.md

SKILL.md 格式：

插件系统概述

Claude Code 的插件系统采用模块化架构，每个插件可以包含以下组件类型：

资料来源：plugins/README.md:1-15

核心开发插件

plugin-dev：插件开发框架

plugin-dev 是官方提供的插件开发框架，提供结构化的 7 阶段工作流程，引导开发者从概念到完整插件实现。

graph TD
    A[Phase 1: Discovery<br>理解需求] --> B[Phase 2: Planning<br>组件规划]
    B --> C[Phase 3: Architecture<br>架构设计]
    C --> D[Phase 4: Structure<br>结构创建]
    D --> E[Phase 5: Implementation<br>组件实现]
    E --> F[Phase 6: Validation<br>质量验证]
    F --> G[Phase 7: Testing<br>测试验证]
    G --> H[Phase 8: Documentation<br>文档完善]

关键功能：

• 自动技能加载：每个阶段自动加载相关技能（skill），如 plugin-structure、command-development、agent-development
• AI 辅助生成：使用 agent-creator agent 自动生成子代理代码
• 验证工具：提供 validate-agent.sh、validate-hook-schema.sh 等验证脚本
• 渐进式披露：详细文档存储在 references/ 和 examples/ 目录，按需加载

使用方式：

/plugin-dev:create-plugin [可选描述]

# 示例：
/plugin-dev:create-plugin
/plugin-dev:create-plugin 数据库迁移管理插件

资料来源：plugins/plugin-dev/README.md:1-80

feature-dev：功能开发工作流

feature-dev 专注于结构化的功能开发流程，强调在编写代码之前深入理解代码库。

7 阶段流程：

核心原则：

• 在理解代码库后再开始编写代码
• 提出具体、明确的问题，而非假设
• 优先考虑可读性和可维护性
• 使用 TodoWrite 跟踪所有进度

资料来源：plugins/feature-dev/README.md:1-60

代码质量插件

code-review：代码审查工具

code-review 插件通过 GitHub CLI 自动执行 PR 审查，检查 CLAUDE.md 合规性、代码质量和潜在 bug。

工作流程：

graph LR
    A[创建 PR] --> B[/code-review]
    B --> C[启动审查 agents]
    C --> D[分析代码质量]
    C --> E[检查 CLAUDE.md 合规]
    C --> F[识别 bug 和问题]
    D --> G[输出审查报告]
    E --> G
    F --> G
    G --> H[可选：发布为 PR 评论]

使用方法：

# 本地审查（输出到终端）
/code-review

# 发布为 PR 评论
/code-review --comment

前置条件：

• Git 仓库
• GitHub CLI (gh) 已安装并认证
• 可选：项目包含 CLAUDE.md 文件

资料来源：plugins/code-review/README.md:1-80

pr-review-toolkit：PR 审查代理套件

pr-review-toolkit 是一套 6 个专业化审查 agent，每个专注于代码质量的特定方面。

使用方式： 直接提出相关问题，Claude 会自动触发对应的 agent：

"检查测试是否覆盖所有边界情况" → 触发 pr-test-analyzer
"审查 API 客户端的错误处理" → 触发 silent-failure-hunter

资料来源：plugins/pr-review-toolkit/README.md:1-80

security-guidance：安全提醒钩子

security-guidance 提供 PreToolUse 钩子，在执行潜在危险操作前发出安全警告。

监控的安全模式（9 种）：

资料来源：plugins/security-guidance/README.md:1-20

Git 工作流插件

commit-commands：提交命令集

commit-commands 提供三个命令，简化 Git 提交和 PR 创建流程。

工作流集成示例：

graph TD
    A[编写代码] --> B[/commit]
    B --> C[更多更改]
    C --> D[/commit]
    D --> E[准备创建 PR]
    E --> F[/commit-push-pr]
    F --> G[审查 PR 描述]
    G --> H[合并后]
    H --> I[/clean_gone]
    I --> J[清理完成]

前置条件：

• Git 已安装并配置
• 对于 /commit-push-pr：GitHub CLI (gh) 已安装并认证
• 仓库必须是一个 git 仓库并有 remote

资料来源：plugins/commit-commands/README.md:1-60

自动化工作流插件

ralph-wiggum：迭代循环开发

ralph-wiggum 插件实现自引用 AI 循环，Claude 在同一任务上重复工作直到完成。

核心功能：

• 自主迭代：Claude 持续处理任务，无需每次手动触发
• 中断拦截：Stop 钩子阻止意外退出，询问是否继续
• 状态保持：维护迭代状态直到任务完成或手动取消

使用方式：

/ralph-loop  开始自主迭代
/cancel-ralph  取消迭代循环

资料来源：plugins/ralph-wiggum/README.md:1-40

hookify：自定义钩子创建

hookify 简化了自定义钩子的创建过程，无需编辑复杂的 hooks.json 文件。

核心特性：

• 对话分析：自动分析对话模式识别不良行为
• Markdown 配置：使用 YAML frontmatter 定义规则
• 正则匹配：支持强大的正则表达式模式
• 即时生效：无需重启，下次工具使用即生效

快速开始：

# 基于指令创建规则
/hookify 警告我使用 rm -rf 命令

# 分析对话自动创建规则
/hookify

# 列出所有规则
/hookify:list

# 交互式配置
/hookify:configure

创建的规则文件： 规则存储在 .claude/hookify.warn-*.local.md 文件中

资料来源：plugins/hookify/README.md:1-60

插件安装与配置

安装方式

从 marketplace 安装：

/plugin install plugin-name@claude-code-marketplace

开发模式使用：

cc --plugin-dir /path/to/plugin-dev

全局安装后使用：

# 全局安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 进入项目目录
cd my-project
claude

# 使用 /plugin 命令安装插件
/plugin install pr-review-toolkit

资料来源：plugins/README.md:40-55

项目级配置

插件配置通常存储在项目根目录的 .claude/settings.json 中：

{
  "plugins": ["code-review", "commit-commands", "pr-review-toolkit"]
}

本地设置可使用 .claude/plugin-name.local.md 文件模式

社区关注与已知问题

相关社区讨论

根据社区反馈，以下问题与插件使用相关：

使用建议

1. CLAUDE.md 规则传递：在复杂的多 agent 工作流中，确保 CLAUDE.md 规则在每个 agent 上下文中明确传递
2. 插件兼容性：在 Windows AVX-only CPU 环境下注意插件 marketplace 可能的兼容性问题
3. 速率限制：对于长时间运行的自动化任务，考虑使用 hookify 创建提醒机制

插件开发技能体系

plugin-dev 提供了完整的技能开发指南：

每个技能包含：

• 核心 SKILL.md：基本概念和用法
• References/：详细规范文档
• Examples/：实际工作示例

资料来源：plugins/plugin-dev/README.md:80-140

最佳实践

组件设计原则

开发流程

1. 规划阶段：明确插件目标和所需组件类型
2. 结构创建：使用 plugin-structure skill 建立目录
3. 组件实现：按技能指南实现每个组件
4. 验证测试：运行验证脚本确保质量
5. 文档完善：编写清晰的 README 和使用说明

资料来源：plugins/plugin-dev/skills/command-development/README.md:80-120

配置架构概述

Claude Code 采用分层配置架构，支持从全局默认值到项目特定设置的渐进式覆盖。

graph TD
    A[用户主目录 ~/.claude/settings.json] --> B[项目级 .claude/settings.json]
    B --> C[环境变量配置]
    C --> D[运行时配置]
    E[插件级设置 .claude/plugin-name.local.md] --> D

配置优先级从高到低依次为：

1. 环境变量
2. 项目级配置文件
3. 用户主目录全局配置
4. Claude Code 默认值

全局设置管理

配置文件位置

Claude Code 全局配置存储在用户主目录的 ~/.claude/settings.json 文件中。

核心配置选项

Claude Code 支持多种配置选项来定制行为：

权限模式配置

根据社区反馈，defaultMode 设置在某些场景下可能不会正确继承到新会话中。 资料来源：社区 Issue #55558

{
  "defaultMode": "auto",
  "permissionMode": "auto"
}

注意：当 defaultMode 设置为 "auto" 时，该配置不会自动继承到新打开的会话中，这是已知的限制。 资料来源：社区 Issue #55558

环境变量配置

Claude Code 通过环境变量支持高级配置选项：

Auto 模式配置

最新版本 v2.1.158 在 Bedrock、Vertex 和 Foundry 平台上为 Opus 4.7 和 Opus 4.8 模型启用了 Auto 模式。 资料来源：最新发布说明

启用方式：

export CLAUDE_CODE_ENABLE_AUTO_MODE=1

插件设置管理

设置文件结构

插件使用 .claude/plugin-name.local.md 模式存储项目特定配置。 资料来源：plugins/plugin-dev/skills/plugin-settings/SKILL.md

.claude/
├── plugin-name.local.md    # 插件本地配置
└── settings.json           # 通用设置

配置格式

插件设置文件采用 YAML frontmatter + Markdown 内容的结构：

概述

Claude Code 支持企业级托管部署，通过移动设备管理（MDM）解决方案实现跨平台策略管理。管理员可以使用标准化的企业配置工具在 macOS 和 Windows 设备上统一部署和配置 Claude Code，覆盖权限管理、使用限制、安全策略等多个方面。

该功能使组织能够在保护敏感数据的同时，保持对开发工具的集中控制，确保所有团队成员使用一致的配置运行 Claude Code。

平台支持

Claude Code 的企业托管设置覆盖两大主流桌面操作系统：

目录结构

MDM 配置示例的完整目录结构如下：

examples/mdm/
├── README.md
├── macos/
│   ├── com.anthropic.claudecode.mobileconfig
│   └── com.anthropic.claudecode.plist
└── windows/
    ├── ClaudeCode.admx
    └── Set-ClaudeCodePolicy.ps1

macOS 配置

MobileConfig 配置文件

macOS 平台使用 Apple 的 mobileconfig 格式，这是一种 XML 格式的配置文件，用于描述配置概要（Configuration Profile）。com.anthropic.claudecode.mobileconfig 文件定义了 Claude Code 在 macOS 设备上的企业策略。

mobileconfig 文件的核心结构包括：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "...">
<plist version="1.0">
<dict>
    <key>PayloadContent</key>
    <array>
        <!-- 配置项定义 -->
    </array>
</dict>
</plist>

Property List 配置

com.anthropic.claudecode.plist 是标准的 macOS 属性列表文件，定义了 Claude Code 的具体配置参数。Property List 通常用于存储应用程序的偏好设置，可以通过以下方式部署：

1. 通过 MDM 推送：由 MDM 解决方案自动部署到托管设备
2. 手动安装：用户双击配置文件进行安装
3. 命令行工具：使用 defaults 命令读取和写入配置

配置 Payload 结构

macOS 配置文件中的关键 Payload 包括：

Windows 配置

ADMX 策略定义

Windows 平台使用 ADMX（Administrative Template XML）格式定义组策略。ClaudeCode.admx 文件是组策略管理模板，允许管理员通过 Active Directory 或本地组策略编辑器配置 Claude Code。

ADMX 文件的主要组成部分：

<policyDefinitions>
    <policyNamespaces>
        <target prefix="claudecode" namespace="..." />
    </policyNamespaces>
    <supersededAdmFileName />
    <categories>
        <category name="..." />
    </categories>
    <policies>
        <policy ...>
            <elements>...</elements>
        </policy>
    </policies>
</policyDefinitions>

PowerShell 部署脚本

Set-ClaudeCodePolicy.ps1 是 Windows 平台的 PowerShell 部署脚本，用于自动化应用配置策略。该脚本支持：

• 静默部署：无需用户交互即可应用配置
• 批量操作：通过网络策略服务器批量应用到多台设备
• 配置验证：部署后验证策略是否正确应用

ADMX 策略类别

Windows 策略通常按功能分类组织，便于管理员在组策略编辑器中查找和配置：

托管策略详解

权限管理模式

企业托管设置支持配置 Claude Code 的权限模式，这是社区中用户关注的一个配置项。根据社区反馈，默认权限模式设置为 "auto" 时不会在新会话中继承，且无法在会话中途更改。

托管策略可以预先配置以下权限模式：

注意：根据社区 Issue #55558，当 defaultMode 设置为 "auto" 时，该设置不会自动继承到新会话。建议通过 MDM 统一配置以确保所有会话使用一致的权限策略。

使用限制配置

企业托管设置允许管理员配置使用限制策略，包括：

• 每周使用上限：限制每个用户的每周请求配额
• 会话超时：设置空闲会话自动断开时间
• 并发会话数：限制同一用户的并发会话数量

已知问题：根据社区 Issue #52921，每周限制计数器约每 24 小时重置一次，而非文档所述的 7 天周期。管理员在配置使用限制时应考虑这一行为差异。

部署工作流

graph TD
    A[准备配置文件] --> B{选择目标平台}
    B -->|macOS| C[生成 mobileconfig 或 plist]
    B -->|Windows| D[准备 ADMX 或 PowerShell 脚本]
    C --> E[上传到 MDM 服务器]
    D --> E
    E --> F{MDM 服务器类型}
    F -->|Jamf Pro| G[创建配置文件并分配]
    F -->|Intune| H[创建应用配置策略]
    F -->|其他| I[使用通用部署方法]
    G --> J[分配目标设备/用户]
    H --> J
    I --> J
    J --> K{验证部署}
    K -->|成功| L[配置生效]
    K -->|失败| M[排查问题]
    M --> E

常见配置项

API 密钥管理

托管环境通常需要集中管理 API 密钥：

网络和代理设置

日志和诊断

故障排除

macOS 部署问题

Windows 部署问题

安全考虑

数据保护

企业托管设置应遵循以下安全最佳实践：

1. 密钥管理：使用企业密钥管理解决方案存储敏感配置
2. 传输安全：确保配置文件通过加密通道传输
3. 访问控制：限制 MDM 控制台访问权限
4. 审计日志：启用配置变更审计以便追踪

合规性

根据组织合规要求，可能需要配置以下设置：

• 数据驻留：配置使用区域性 API 端点
• 遥测控制：在受监管行业中可能需要禁用遥测
• 日志保留：配置合规的日志保留策略

参考资料

• MDM 配置示例目录
• macOS mobileconfig 配置
• macOS plist 配置
• Windows ADMX 策略定义
• Windows PowerShell 部署脚本

Pitfall Log / 踩坑日志

项目：anthropics/claude-code

摘要：发现 39 个潜在踩坑项，其中 16 个为 high/blocking；最高优先级：安装坑 - 来源证据：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session。

1. 安装坑 · 来源证据：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：Extended thinking: signed thinking block 'cannot be modified' (400) permanently wedges session
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_6fd2423d8dd840ad898450c124291027 | https://github.com/anthropics/claude-code/issues/63335 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

2. 安装坑 · 来源证据：[BUG] Old sessions do not open, also cannot start new sessions

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安装相关的待验证问题：[BUG] Old sessions do not open, also cannot start new sessions
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_abbd745212d743c6b17ef3e919d49b0d | https://github.com/anthropics/claude-code/issues/64109 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

3. 配置坑 · 来源证据：Feature Request: Cross-device session sync between desktop and mobile

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Feature Request: Cross-device session sync between desktop and mobile
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_cd5af4117b394f29bd45302db852a9e9 | https://github.com/anthropics/claude-code/issues/61298 | 来源类型 github_issue 暴露的待验证使用条件。

4. 配置坑 · 来源证据：Session titles generated in English despite locale set to ko-KR

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Session titles generated in English despite locale set to ko-KR
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e75af4578a6c41e8820a88e1e8b8d617 | https://github.com/anthropics/claude-code/issues/64111 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

5. 配置坑 · 来源证据：Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellat…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_262f6cbca571401884333f86087e0ddd | https://github.com/anthropics/claude-code/issues/64095 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

6. 配置坑 · 来源证据：[Bug] Anthropic API Error: Cannot modify thinking blocks in assistant messages

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：[Bug] Anthropic API Error: Cannot modify thinking blocks in assistant messages
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_9c64894658eb475f9ad68245eed8d2f5 | https://github.com/anthropics/claude-code/issues/64094 | 来源讨论提到 linux 相关条件，需在安装/试用前复核。

7. 能力坑 · 来源证据：Shift+Enter to Control+J in Terminal

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个能力理解相关的待验证问题：Shift+Enter to Control+J in Terminal
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_e0c0e16324d045f38cb9237f7f4dfff6 | https://github.com/anthropics/claude-code/issues/64115 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

8. 运行坑 · 来源证据：[FEATURE] Continue when the session limit reached

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个运行相关的待验证问题：[FEATURE] Continue when the session limit reached
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_a1a5923e7779438ca2f53dafbaf38d00 | https://github.com/anthropics/claude-code/issues/13354 | 来源类型 github_issue 暴露的待验证使用条件。

9. 安全/权限坑 · 失败模式：security_permissions: Remote Control (/remote-control) disconnects frequently

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: Remote Control (/remote-control) disconnects frequently
• 对用户的影响：Developers may expose sensitive permissions or credentials: Remote Control (/remote-control) disconnects frequently
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Remote Control (/remote-control) disconnects frequently. Context: Observed when using windows, macos, linux
• 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/33041
• 证据：failure_mode_cluster:github_issue | fmev_9c4c7261c368bad5ca3425e0acae9cca | https://github.com/anthropics/claude-code/issues/33041 | Remote Control (/remote-control) disconnects frequently

10. 安全/权限坑 · 失败模式：security_permissions: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating...

• 严重度：high
• 证据强度：source_linked
• 发现：Developers should check this security_permissions risk before relying on the project: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
• 对用户的影响：Developers may expose sensitive permissions or credentials: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux). Context: Observed when using node, linux
• 防护动作：Do not recommend enabling privileged or credential-bearing paths until the source-backed risk is reviewed: https://github.com/anthropics/claude-code/issues/50423
• 证据：failure_mode_cluster:github_issue | fmev_8458acfcfab9d6641fe4696ba1202131 | https://github.com/anthropics/claude-code/issues/50423 | [BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)

11. 安全/权限坑 · 来源证据：Model fabricates tool output (and even a user instruction) when a parallel batch is partially cancelled / appears empty

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Model fabricates tool output (and even a user instruction) when a parallel batch is partially cancelled / appears empty
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_1448fd32254e42c7a13bb07c4d4b376e | https://github.com/anthropics/claude-code/issues/63538 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

12. 安全/权限坑 · 来源证据：Remote Control (/remote-control) disconnects frequently

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Remote Control (/remote-control) disconnects frequently
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_88549375cbdc40f5b59125e4fbda8e11 | https://github.com/anthropics/claude-code/issues/33041 | 来源讨论提到 windows 相关条件，需在安装/试用前复核。

13. 安全/权限坑 · 来源证据：[BUG] API Error: Usage credits required for 1M context

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] API Error: Usage credits required for 1M context
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_87e11d1be1a941db9b9a16f57f0303ef | https://github.com/anthropics/claude-code/issues/64117 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

14. 安全/权限坑 · 来源证据：[BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_79e2cfaaa0d840d0ad2301e7fdee0458 | https://github.com/anthropics/claude-code/issues/64112 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

15. 安全/权限坑 · 来源证据：[BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linu…

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[BUG] VS Code extension doesn't load Chrome browser tools in chat panel despite docs stating @browser should work (Linux)
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_ff2e3e5c8d8544f49fb33923239ce9ae | https://github.com/anthropics/claude-code/issues/50423 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

16. 安全/权限坑 · 来源证据：[MODEL] Opus 4.8 starts hallucinating results before parallel tasks finish

• 严重度：high
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：[MODEL] Opus 4.8 starts hallucinating results before parallel tasks finish
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源问题仍为 open，Pack Agent 需要复核是否仍影响当前版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_72142433607342c683efa2dfd91727e1 | https://github.com/anthropics/claude-code/issues/63884 | 来源讨论提到 api key 相关条件，需在安装/试用前复核。

17. 安装坑 · 失败模式：installation: [BUG] Old sessions do not open, also cannot start new sessions

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this installation risk before relying on the project: [BUG] Old sessions do not open, also cannot start new sessions
• 对用户的影响：Developers may fail before the first successful local run: [BUG] Old sessions do not open, also cannot start new sessions
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Old sessions do not open, also cannot start new sessions. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_369baf02a3bc53ab601dee041b939afe | https://github.com/anthropics/claude-code/issues/64109 | [BUG] Old sessions do not open, also cannot start new sessions

18. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 建议检查：列出会写入的配置文件、目录和卸载/回滚步骤。
• 防护动作：涉及宿主配置目录时必须给回滚路径，不能只给安装命令。
• 证据：capability.host_targets | github_repo:937253475 | https://github.com/anthropics/claude-code | host_targets=claude, claude_code

19. 配置坑 · 失败模式：configuration: Feature Request: Cross-device session sync between desktop and mobile

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Feature Request: Cross-device session sync between desktop and mobile
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Feature Request: Cross-device session sync between desktop and mobile
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Feature Request: Cross-device session sync between desktop and mobile. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_283825ec99bcea39a11f0a6e6c298804 | https://github.com/anthropics/claude-code/issues/61298 | Feature Request: Cross-device session sync between desktop and mobile

20. 配置坑 · 失败模式：configuration: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the i...

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24). Context: Observed during installation or first-run setup.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_a856115bae11a139a2c97e4617737eed | https://github.com/anthropics/claude-code/issues/64080 | Harness silently executes duplicated parallel tool_use blocks: subagent fan-out runs N× the intended count (6 → 24)

21. 配置坑 · 失败模式：configuration: Session titles generated in English despite locale set to ko-KR

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: Session titles generated in English despite locale set to ko-KR
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: Session titles generated in English despite locale set to ko-KR
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Session titles generated in English despite locale set to ko-KR. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_0388434519fd0a36700613913cb137e0 | https://github.com/anthropics/claude-code/issues/64111 | Session titles generated in English despite locale set to ko-KR

22. 配置坑 · 失败模式：configuration: [FEATURE] Multi-account switching in Claude Mobile app without shared email

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this configuration risk before relying on the project: [FEATURE] Multi-account switching in Claude Mobile app without shared email
• 对用户的影响：Developers may misconfigure credentials, environment, or host setup: [FEATURE] Multi-account switching in Claude Mobile app without shared email
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Multi-account switching in Claude Mobile app without shared email. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_13a40dd6b5f966f8cf8d81e22aa64f3e | https://github.com/anthropics/claude-code/issues/36151 | [FEATURE] Multi-account switching in Claude Mobile app without shared email

23. 配置坑 · 来源证据：Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port…

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个配置相关的待验证问题：Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
• 对用户的影响：可能增加新用户试用和生产接入成本。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_d98a409f57c74c26a5ba696527e6c1b0 | https://github.com/anthropics/claude-code/issues/64110 | 来源讨论提到 node 相关条件，需在安装/试用前复核。

24. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 建议检查：将假设转成下游验证清单。
• 防护动作：假设必须转成验证项；没有验证结果前不能写成事实。
• 证据：capability.assumptions | github_repo:937253475 | https://github.com/anthropics/claude-code | README/documentation is current enough for a first validation pass.

25. 运行坑 · 失败模式：runtime: [FEATURE] Continue when the session limit reached

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this runtime risk before relying on the project: [FEATURE] Continue when the session limit reached
• 对用户的影响：Developers may hit a documented source-backed failure mode: [FEATURE] Continue when the session limit reached
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [FEATURE] Continue when the session limit reached. Context: Source discussion did not expose a precise runtime context.
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_0940bbcf61d4a9404571f32848072c7d | https://github.com/anthropics/claude-code/issues/13354 | [FEATURE] Continue when the session limit reached

26. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 建议检查：补 GitHub 最近 commit、release、issue/PR 响应信号。
• 防护动作：维护活跃度未知时，推荐强度不能标为高信任。
• 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | last_activity_observed missing

27. 安全/权限坑 · 下游验证发现风险项

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：下游已经要求复核，不能在页面中弱化。
• 建议检查：进入安全/权限治理复核队列。
• 防护动作：下游风险存在时必须保持 review/recommendation 降级。
• 证据：downstream_validation.risk_items | github_repo:937253475 | https://github.com/anthropics/claude-code | no_demo; severity=medium

28. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 建议检查：把风险写入边界卡，并确认是否需要人工复核。
• 防护动作：评分风险必须进入边界卡，不能只作为内部分数。
• 证据：risks.scoring_risks | github_repo:937253475 | https://github.com/anthropics/claude-code | no_demo; severity=medium

29. 安全/权限坑 · 来源证据：Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

• 严重度：medium
• 证据强度：source_linked
• 发现：GitHub 社区证据显示该项目存在一个安全/权限相关的待验证问题：Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
• 对用户的影响：可能影响授权、密钥配置或安全边界。
• 建议检查：来源显示可能已有修复、规避或版本变化，说明书中必须标注适用版本。
• 防护动作：不得脱离来源链接放大为确定性结论；需要标注适用版本和复核状态。
• 证据：community_evidence:github | cevd_2cc9f1b9f9da461b8ec530dcb1cdf6fa | https://github.com/anthropics/claude-code/issues/64106 | 来源讨论提到 macos 相关条件，需在安装/试用前复核。

30. 能力坑 · 失败模式：capability: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of e...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI). Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_2933d9f47cbf4f5f4fb221bac31ceb7d | https://github.com/anthropics/claude-code/issues/64108 | Tool calls intermittently emitted as literal text (stray 'court' + raw <invoke>) instead of executing — mostly Edit/Read (Opus, CLI)

31. 能力坑 · 失败模式：capability: Tool-result envelope injected into tool-call input channel during parallel tool batches (corr...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
• 对用户的影响：Developers may hit a documented source-backed failure mode: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation). Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_c36dedf952efb0b87258d9add70eb890 | https://github.com/anthropics/claude-code/issues/64095 | Tool-result envelope injected into tool-call input channel during parallel tool batches (corruption + cascade cancellation)

32. 能力坑 · 失败模式：capability: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
• 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited. Context: Observed when using windows
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_f149428db4eaf50a33b3d1a869e10e0a | https://github.com/anthropics/claude-code/issues/53915 | [BUG] API Error: Server is temporarily limiting requests (not your usage limit) · Rate limited

33. 能力坑 · 失败模式：capability: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session —...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
• 对用户的影响：Developers may hit a documented source-backed failure mode: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped. Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_90aaa75e00b64d60d6925606deeeac09 | https://github.com/anthropics/claude-code/issues/64112 | [BUG] Repeated malformed tool-call markup (stray count before <invoke>) within one session — commands silently dropped

34. 能力坑 · 失败模式：capability: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this capability risk before relying on the project: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
• 对用户的影响：Developers may hit a documented source-backed failure mode: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests
• 建议检查：Before packaging this project, run the relevant install/config/quickstart check for: [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests. Context: Observed when using macos
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_74b4a063bf7b78b902bf847b1e15998c | https://github.com/anthropics/claude-code/issues/64101 | [Bug] Anthropic API Error: Server Rate Limiting on Recurring Requests

35. 能力坑 · 失败模式：conceptual: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
• 对用户的影响：Developers may hit a documented source-backed failure mode: Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_c47900c3ee637585906fc588a2c5cca4 | https://github.com/anthropics/claude-code/issues/63192 | Cancelling a parallel tool-call batch corrupts thinking blocks -> 400 "thinking blocks cannot be modified" permanently wedges the session

36. 能力坑 · 失败模式：conceptual: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on...

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
• 对用户的影响：Developers may hit a documented source-backed failure mode: Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_412c2e9812e680366a198d368bc09d58 | https://github.com/anthropics/claude-code/issues/64110 | Opus (CLI) took down a node's DNS by deploying a k8s LoadBalancer on :53, after dismissing on-screen evidence the port was the host resolver

37. 能力坑 · 失败模式：conceptual: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this conceptual risk before relying on the project: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
• 对用户的影响：Developers may hit a documented source-backed failure mode: Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8
• 建议检查：复核 source-backed failure mode cluster，并把适用版本和验证路径写入资产。
• 防护动作：State this as source-backed community evidence, not as Doramagic reproduction.
• 证据：failure_mode_cluster:github_issue | fmev_fae94d46beb702ecb9e71f49ebeb7268 | https://github.com/anthropics/claude-code/issues/64106 | Tool calls leak as raw text ('call' + args) instead of executing — frequent on Opus 4.8

38. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 建议检查：抽样最近 issue/PR，判断是否长期无人处理。
• 防护动作：issue/PR 响应未知时，必须提示维护风险。
• 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | issue_or_pr_quality=unknown

39. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 建议检查：确认最近 release/tag 和 README 安装命令是否一致。
• 防护动作：发布节奏未知或过期时，安装说明必须标注可能漂移。
• 证据：evidence.maintainer_signals | github_repo:937253475 | https://github.com/anthropics/claude-code | release_recency=unknown