Claude Code Command、Subagent、Skills、Hooks 与 Qoder CLI 实战指南

Claude Code 这类终端 Agent 工具的核心价值，不只是“让大模型帮忙写代码”，而是把模型能力接入真实工程环境：它能读仓库、改文件、运行命令、调用工具、拆解任务，还能嵌入 CI/CD（持续集成/持续部署）、代码审查、运维诊断等流程。

要真正用好这类工具，需要先分清几个概念：

• Command：把常用提示词封装成一个快捷命令。
• Subagent：把复杂任务拆给独立上下文里的专用 Agent。
• Skills：把某类专业能力封装成可按需加载的知识包和脚本包。
• Hooks：在 Agent 生命周期的关键节点执行确定性脚本。
• Programmatic Tool Calling：让模型生成代码来调用和清洗工具结果，避免大量原始数据直接塞进上下文。

这些机制放在一起，构成了一个可扩展的终端 Agent 架构。

Claude Code 解决的不是“聊天”，而是工程自动化

Claude Code 有多种使用形态，不同形态面向不同集成深度。

Headless Mode 的调用形式类似这样：

claude --output-format=stream-json -p "检查当前仓库的未提交改动，并给出代码审查意见"

TUI 适合人和 Agent 协作，Headless Mode 适合机器调用 Agent，Agent SDK 则适合把 Claude Code 的能力封装进自己的产品或平台。

一个终端 Agent 的典型执行链路如下：

flowchart LR
    U[用户输入任务] --> A[主 Agent 理解目标]
    A --> P[拆解计划]
    P --> T[选择工具或 Subagent]
    T --> E[执行文件读写、命令、检索、外部工具]
    E --> O[观察执行结果]
    O --> J{任务完成了吗}
    J -- 否 --> P
    J -- 是 --> R[返回结果]

这个循环就是常说的 Agent Loop。Command、Subagent、Skills、Hooks 都是在这个循环上做工程化增强。

Command：把常用提示词变成 Slash Command

Command 可以理解成“预置提示词快捷方式”。用户输入一个 Slash Command，Claude Code 会把对应 Markdown 文件里的内容注入当前对话，让主 Agent 按预设流程执行任务。

Command 特别适合封装重复性强、流程稳定的任务，例如：

• 生成 API 文档；
• 按团队规范提交 Git；
• 执行发布前检查；
• 按固定格式写变更日志；
• 根据仓库代码生成测试计划。

Command 的文件结构

Command 通常是一个 Markdown 文件，文件开头用 frontmatter 定义名称、描述、可用工具等元信息，正文写具体执行规则。

---
name: api-document
description: Generate and maintain API documentation, OpenAPI specifications, SDK examples, authentication guides, and versioning materials.
tools: Read, Grep, Glob, Bash
---

You are responsible for generating API documentation.

When invoked, perform these tasks:

1. Inspect API routes, controllers, schemas, and request validators.
2. Generate an OpenAPI 3.0 specification.
3. Include request and response examples, covering success and error cases.
4. Document authentication methods, including token, OAuth, and API key.
5. Generate error code references and troubleshooting guidance.
6. Provide curl examples and common integration workflows.
7. Validate the documentation against actual API behavior when possible.

常见字段含义如下：

用 Command 固化 Git 提交流程

很多团队都有固定的 Git 规范：分支名要符合 feature/*、bugfix/*、hotfix/*，提交信息要符合 Conventional Commits。与其每次手写长提示词，不如封装成 /git-commit。

---
name: git-commit
description: Automate Git branch validation, commit message generation, and push workflow based on current code changes.
tools: Bash, Read, Glob, Grep
---

You are a Git workflow automation expert.

When invoked:

1. Check current Git branch name and working tree status.
2. Inspect staged and unstaged changes.
3. Determine the change type:
   - bug fix
   - new feature
   - hotfix
   - refactor
   - docs
   - test
   - chore
4. Validate branch naming:
   - bugfix/[issue-id]-[short-description]
   - feature/[feature-name]
   - hotfix/[urgent-issue]
   - refactor/[scope]
   - docs/[area]
   - test/[scope]
   - chore/[task]
5. If the branch name does not match the change type, create a new branch from the current branch.
6. Generate a commit message using Conventional Commits:
   - fix: short bug fix description
   - feat: short feature description
   - refactor: short refactor description
7. Ask for confirmation before destructive operations.
8. Commit and push changes after confirmation.
9. Report the remote branch URL and commit hash.

Command 的关键不是“写一段提示词”，而是把日常开发里的 SOP（Standard Operating Procedure，标准操作流程）提炼成稳定、可复用、可审查的文本契约。

Subagent：把复杂任务交给独立上下文里的专用 Agent

Subagent 是 Claude Code 中用于处理特定任务的子 Agent。每个 Subagent 都有自己的：

• 独立上下文窗口；
• 系统提示词；
• 工具权限；
• 任务描述；
• 输出约束。

主 Agent 不需要亲自做所有细节，而是通过 Task 工具把某个子任务交给合适的 Subagent。

flowchart TB
    U[用户任务] --> M[主 Agent]
    M --> S1[代码检索 Subagent]
    M --> S2[API 审查 Subagent]
    M --> S3[测试生成 Subagent]
    S1 --> R[结果汇总]
    S2 --> R
    S3 --> R
    R --> M
    M --> U

Subagent 主要解决三个问题。

处理长程任务

大模型上下文窗口有限，复杂工程任务往往会涉及大量文件、日志、历史对话和工具返回结果。如果全部塞进主 Agent 的上下文，很容易造成上下文膨胀。

Subagent 可以把大任务拆成多个子任务，每个子任务在独立上下文中完成，主 Agent 只接收最终结果。

例如一次大型代码审查可以拆成：

并行处理任务

如果任务之间没有强依赖，主 Agent 可以同时唤起多个 Subagent。代码库搜索就是典型例子：不同 Subagent 分别检索不同目录，最终把结果汇总给主 Agent。

flowchart LR
    M[主 Agent] --> A[src/services 检索]
    M --> B[src/components 检索]
    M --> C[tests 检索]
    M --> D[docs 检索]
    A --> R[汇总结果]
    B --> R
    C --> R
    D --> R

并行不是为了让模型“更聪明”，而是减少主上下文负担，并让任务拆分更清晰。

做领域定制

Subagent 可以配置专门的提示词和工具权限。比如 API 审查 Agent 只允许读文件和搜索，不允许写文件；发布 Agent 可以运行构建命令，但不能执行危险删除命令。

一个 RESTful API 审查 Subagent 可以这样定义：

---
name: api-reviewer
description: Review API designs for RESTful compliance, endpoint structure, HTTP methods, status codes, resource naming, and developer experience.
tools: Read, Grep, Glob
---

You are an expert API design reviewer specializing in RESTful architecture.

When reviewing APIs, focus on:

1. Resource naming
   - Use nouns instead of verbs.
   - Use plural resource names, such as /users instead of /user.
   - Keep naming style consistent.

2. HTTP methods
   - GET retrieves resources.
   - POST creates resources or triggers non-idempotent actions.
   - PUT replaces full resources.
   - PATCH updates partial resources.
   - DELETE removes resources.

3. Status codes
   - 200 for successful reads or updates.
   - 201 for successful creation.
   - 204 for successful deletion without response body.
   - 400 for validation errors.
   - 401 and 403 for authentication and authorization failures.
   - 404 for missing resources.
   - 409 for conflicts.
   - 500 for server errors.

4. URL structure
   - Use hierarchical URLs for relationships, such as /users/123/orders.
   - Use query parameters for filtering, sorting, and pagination.
   - Use versioning through /api/v1 or headers.

When providing feedback:

1. Identify violations.
2. Explain why they are problematic.
3. Provide concrete alternatives.
4. Consider scalability and long-term maintainability.

Subagent 的调用方式

Subagent 只能由主 Agent 调用，用户不能直接和 Subagent 建立独立对话。常见调用方式有三种。

显式指定：

请使用 api-reviewer subagent 审查当前仓库的 REST API 设计。

让主 Agent 自动选择：

请帮我审查当前仓库的 API 设计是否符合 RESTful 规范。

串联多个 Subagent：

先设计实现方案，再生成代码，完成后使用 code-review subagent 审查改动。

主 Agent 和 Subagent 如何共享上下文

Claude Code 通过 Task 工具调用 Subagent。调用参数一般包括：

{
  "description": "review REST APIs",
  "prompt": "Review API route definitions in the current repository and report RESTful design issues.",
  "subagent_type": "api-reviewer"
}

关键点在 prompt。主 Agent 会把具体任务写入 prompt，Subagent 把它作为第一条输入消息执行。Subagent 完成后，最后一条回复会作为 Task 工具结果返回给主 Agent。

sequenceDiagram
    participant User as 用户
    participant Main as 主 Agent
    participant Task as Task 工具
    participant Sub as Subagent

    User->>Main: 审查 API 设计
    Main->>Task: description + prompt + subagent_type
    Task->>Sub: 创建独立上下文并执行 prompt
    Sub-->>Task: 返回最终审查结果
    Task-->>Main: 工具调用结果
    Main-->>User: 汇总后的审查报告

主 Agent 不关心 Subagent 的完整执行过程，只关心结果。这种隔离能避免上下文污染，但也带来一个代价：Subagent 之间不会天然共享大量中间状态。

需要共享更多数据时，推荐把中间结果写入文件，再传递文件路径。例如：

flowchart LR
    A[架构分析 Subagent] --> F[(docs/architecture-analysis.md)]
    F --> B[实现 Subagent]
    B --> G[(docs/implementation-plan.md)]
    G --> C[代码审查 Subagent]
    C --> R[审查结果]

文件路径比大段上下文更稳定，也更适合 Spec Driven Development（规格驱动开发）这类工作流。

Skills：把专业能力打包成按需加载的知识包

Skill 是 Claude Code 中用于封装专业能力的机制。它不是简单的提示词片段，而是一个目录，里面可以包含说明文档、参考资料、示例、脚本、模板。

一个 Skill 的目录结构通常是：

pdf/
├── SKILL.md
├── forms.md
├── reference.md
├── examples.md
├── scripts/
│   ├── check_fillable_fields.py
│   ├── extract_form_field_info.py
│   └── fill_pdf_form_with_annotation.py
└── templates/
    └── form-output-template.txt

核心文件是 SKILL.md：

---
name: pdf
description: Process, generate, analyze, merge, split, and fill PDF documents.
allowed-tools: Read, Write, Bash
---

# PDF Processing Guide

Use this Skill when working with PDF files.

For advanced PDF manipulation, read reference.md.

If the task is to fill a PDF form, read forms.md first and follow the instructions there.

渐进式披露：只在需要时加载细节

Skill 的关键设计是 Progressive Disclosure（渐进式披露）。

Claude Code 不会一开始就把所有 Skill 的全部内容塞进上下文，而是先读取 Skill 名称和简短描述。只有任务匹配某个 Skill 时，才加载对应 Skill 的详细说明；如果详细说明又引用了其他文件或脚本，再按需读取。

flowchart TB
    A[启动会话] --> B[加载 Skill 名称和描述]
    B --> C{当前任务匹配某个 Skill 吗}
    C -- 否 --> D[不加载详细内容]
    C -- 是 --> E[加载 SKILL.md]
    E --> F{需要参考资料或脚本吗}
    F -- 是 --> G[读取 reference.md / scripts]
    F -- 否 --> H[按 SKILL.md 执行]

这种设计能节省 Token，因为模型不需要一次性读完所有专业资料。

以 PDF 表单填写为例，SKILL.md 只需要告诉 Agent：

如果需要填写 PDF 表单，先阅读 forms.md。

forms.md 再告诉 Agent：

先运行 scripts/check_fillable_fields.py 检查 PDF 是否包含可填写字段。
如果包含可填写字段，再运行 scripts/extract_form_field_info.py 导出字段信息。

这样 Agent 不需要临时想办法写 PDF 解析代码，而是直接使用 Skill 里已经准备好的脚本和流程。节省的不只是上下文，还有推理步骤和试错成本。

Skill 和 Command 的关系

Skill 的加载效果和 Command 有相似之处：都是把预设指令扩展到上下文中。差异在于使用意图不同。

Command 更像“发任务”，Skill 更像“查操作手册”，Subagent 更像“找专人干活”。

Hooks：给 Agent 执行过程加确定性控制点

大模型会根据上下文自行决定下一步，但工程系统不能把所有关键行为都交给模型自由判断。格式化、权限校验、审计日志、安全拦截、通知推送，这些动作应该是确定发生的。

Hooks 就是 Claude Code 生命周期中的脚本插槽。它允许用户在指定事件点执行 Shell、Python、Node.js 等脚本。

PostToolUse：工具执行后自动格式化

下面的 Hook 会在 Edit 或 Write 工具执行后触发。如果写入的是 TypeScript 文件，就自动执行 Prettier。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | { read file_path; if echo \"$file_path\" | grep -q '\\.ts$'; then npx prettier --write \"$file_path\"; fi; }"
          }
        ]
      }
    ]
  }
}

Hook 脚本会从标准输入接收事件 JSON，例如：

{
  "session_id": "abc123",
  "transcript_path": "/Users/demo/.claude/projects/session.jsonl",
  "cwd": "/Users/demo/project",
  "permission_mode": "default",
  "hook_event_name": "PostToolUse",
  "tool_name": "Write",
  "tool_input": {
    "file_path": "/path/to/file.ts",
    "content": "const a=1"
  },
  "tool_response": {
    "filePath": "/path/to/file.ts",
    "success": true
  },
  "tool_use_id": "toolu_01ABC123"
}

脚本可以读取工具名、文件路径、执行结果，然后执行外部逻辑。

Hook 也可以阻止或改写流程

某些 Hook 可以通过标准输出返回 JSON，影响 Agent 后续行为。例如在用户提交 prompt 前追加上下文，或在工具执行前阻止危险命令。

{
  "decision": "block",
  "reason": "The command tries to remove a protected directory.",
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Do not operate on production directories."
  }
}

decision 为 block 时可以阻止当前行为，reason 用于向用户说明原因，hookSpecificOutput 用于给特定 Hook 返回附加信息。

常见 Hook 事件

Hooks 的定位很清晰：凡是必须确定发生、必须可审计、必须能接入外部系统的逻辑，都适合放到 Hooks。

Command、Subagent、Skills、Hooks 如何选

这些机制都和上下文、提示词、工具有关，容易混用。可以用下面的表来判断。

几个常见判断：

• “我每次都要输入同一段任务说明” → 用 Command。
• “这个任务需要一个专门角色在独立上下文里处理” → 用 Subagent。
• “这个领域有一套文档、脚本、模板，需要按需加载” → 用 Skill。
• “项目长期规则，每轮都应该遵守” → 放 CLAUDE.md 或 AGENTS.md。
• “这个动作必须发生，不能依赖模型想不想做” → 用 Hooks。

Cursor Rules 和 Claude Code 机制的对应关系

Cursor 也有 Rules、Command、Agent 相关能力。Cursor Rules 的几种加载模式，可以大致映射到 Claude Code 的机制。

两类产品的概念命名不同，但目标类似：控制模型在什么时机加载什么上下文，以及允许它做什么。

高级工具调用：为什么需要新的 Tool Use 机制

工具是 Agent 连接外部世界的桥梁。问题在于，工具太多或工具结果太大，都会迅速吃掉上下文窗口。

上下文膨胀通常来自两类原因：

MCP（Model Context Protocol，模型上下文协议）让外部工具接入更方便，但也让工具数量快速膨胀。Anthropic 提出的 Tool Search Tool、Programmatic Tool Calling、Tool Use Examples，都是围绕工具上下文优化展开的。

Tool Search Tool：工具也可以按需发现

传统方式是把所有工具定义直接传给模型：

{
  "tools": [
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {}
    },
    {
      "name": "github.listIssues",
      "description": "List repository issues",
      "input_schema": {}
    }
  ]
}

当工具数量达到几百个时，这种方式会占用大量上下文。

Tool Search Tool 的思路是：只把工具搜索能力放进上下文，大量具体工具先延迟加载。模型需要某类工具时，先搜索，再加载匹配工具。

{
  "tools": [
    {
      "type": "tool_search_tool_regex_20251119",
      "name": "tool_search_tool_regex"
    },
    {
      "name": "github.createPullRequest",
      "description": "Create a pull request",
      "input_schema": {},
      "defer_loading": true
    }
  ]
}

执行流程如下：

sequenceDiagram
    participant Model as 模型
    participant Search as Tool Search Tool
    participant Registry as 工具注册表
    participant Tool as 具体工具

    Model->>Search: 搜索 "create pull request"
    Search->>Registry: 查询匹配工具
    Registry-->>Search: 返回 github.createPullRequest 定义
    Search-->>Model: 加载工具 schema
    Model->>Tool: 调用 createPullRequest
    Tool-->>Model: 返回结果

这和 Skills 的渐进式披露很像：先暴露目录，需要时再加载细节。

Programmatic Tool Calling：让代码清洗工具结果

很多工具返回的原始结果不适合直接给模型。比如：

• 网页抓取工具返回大量 HTML、CSS、脚本；
• 日志查询工具返回几万行日志；
• 数据查询工具返回完整明细，但用户只需要汇总统计；
• 企业系统返回大列表，但用户只关心异常项。

Programmatic Tool Calling（程序化工具调用，简称 PTC）的做法是：模型先生成一段代码，由代码调用允许的工具，并在代码里清洗、聚合、过滤结果。模型最终只接收处理后的精简数据。

工具配置大致如下：

{
  "tools": [
    {
      "type": "code_execution_20250825",
      "name": "code_execution"
    },
    {
      "name": "get_team_members",
      "description": "Get all members of a department",
      "input_schema": {},
      "allowed_callers": ["code_execution_20250825"]
    },
    {
      "name": "get_expenses",
      "description": "Get expenses",
      "input_schema": {},
      "allowed_callers": ["code_execution_20250825"]
    }
  ]
}

allowed_callers 表示这个工具允许被 code_execution 调用。这样模型不是直接调用 get_team_members，而是生成代码：

{
  "type": "server_tool_use",
  "id": "srvtoolu_abc",
  "name": "code_execution",
  "input": {
    "code": "team = get_team_members('engineering')\nexpenses = get_expenses(team)\nresult = summarize_by_level(expenses)\nprint(result)"
  }
}

执行链路如下：

sequenceDiagram
    participant User as 用户
    participant Model as 模型
    participant Code as code_execution
    participant Tool as 业务工具
    participant Model2 as 模型二次处理

    User->>Model: 统计工程部门不同级别的报销金额
    Model->>Code: 生成代码
    Code->>Tool: get_team_members('engineering')
    Tool-->>Code: 返回成员明细
    Code->>Tool: get_expenses(team)
    Tool-->>Code: 返回报销明细
    Code->>Code: 聚合、过滤、排序
    Code-->>Model2: 返回精简统计结果
    Model2-->>User: 输出分析结论

PTC 的核心收益是减少无用上下文。模型仍然负责规划和生成代码，但大量机械的数据处理交给程序执行。

使用 PTC 时要注意安全边界：

Tool Use Examples：用示例提升工具参数准确性

工具 schema 只能说明字段类型，无法完整表达业务习惯。

例如一个创建工单工具：

{
  "name": "create_ticket",
  "input_schema": {
    "properties": {
      "title": { "type": "string" },
      "priority": {
        "enum": ["low", "medium", "high", "critical"]
      },
      "labels": {
        "type": "array",
        "items": { "type": "string" }
      },
      "due_date": { "type": "string" }
    },
    "required": ["title"]
  }
}

模型知道 due_date 是字符串，但不知道团队约定的日期格式；知道 labels 是字符串数组，但不知道常用标签风格。

input_examples 可以给模型几个高质量样例：

{
  "name": "create_ticket",
  "input_schema": {},
  "input_examples": [
    {
      "title": "Login page returns 500 error",
      "priority": "critical",
      "labels": ["bug", "authentication", "production"],
      "due_date": "2024-11-06"
    },
    {
      "title": "Add dark mode support",
      "priority": "medium",
      "labels": ["feature-request", "ui"]
    },
    {
      "title": "Update API documentation",
      "priority": "low",
      "labels": ["docs"]
    }
  ]
}

这类示例能让模型更准确地生成参数，尤其适合：

• 参数结构很深；
• 字符串有固定格式；
• 枚举字段有业务偏好；
• 工具参数组合存在隐含约定。

从 Agent 结构理解 Claude Code 的设计

Agent 可以概括为：能感知环境、根据目标做决策、并采取行动的智能实体。

工程化 Agent 通常由四部分组成：

flowchart TB
    LLM[LLM / 多模态模型] --> Plan[Planning 规划]
    LLM --> Memory[Memory 记忆]
    LLM --> Tool[Tool Use 工具调用]
    Plan --> Loop[Agent Loop]
    Memory --> Loop
    Tool --> Loop
    Loop --> Result[执行结果]

Claude Code 的很多机制都能放进这个框架：

主子 Agent 是规划能力的工程化表达

人类做复杂任务时也会拆工：架构设计、编码实现、测试、审查、发布。Subagent 把这种拆工映射到多个独立上下文里，让每个上下文只处理一类问题。

短期看，Subagent 仍需要人工设计；长期看，更高级的 Agent 系统可能会按任务自动生成临时子系统，对外仍表现为一个统一 Agent，对内动态组织多个能力模块。

上下文管理就是 Agent 的记忆系统

Claude Code 通过多种方式管理记忆：

好的上下文管理不是“把所有东西都给模型”，而是让模型在正确时机看到正确内容。

Hooks 是旁路逻辑的产品化

很多工程逻辑不应该混进主 Agent 推理链路：

• 针对特定模型行为的修正；
• 工具调用审计；
• 危险命令拦截；
• 企业租户的安全要求；
• CI/CD 触发；
• 通知系统集成；
• 日志和指标采集。

Hooks 把这些旁路逻辑变成可配置机制，主流程保持清晰，外部系统也能获得控制点。

Headless Mode 为什么重要

图形界面适合人用，但不适合大规模自动化评估。Headless Mode 把 Agent 变成可脚本调用的命令行能力，直接带来两个好处。

更容易集成

CI/CD 中可以直接调用：

claude -p "审查本次 Pull Request 的代码变更，输出阻塞问题和建议问题"

批处理任务中可以直接调用：

claude -p "读取 logs/app.log，找出过去 1 小时内频率最高的 10 类错误"

内部平台中可以通过 SDK 调用，把 Agent 能力嵌入研发流程。

更容易评估

评估系统需要稳定输入、可解析输出、可重复运行环境。Headless Mode 避开 GUI 操作的不确定性，更适合 Terminal Bench 这类面向终端 AI 工具的基准测试。

一个评估闭环可以这样组织：

flowchart LR
    Dataset[标准任务集] --> Runner[Headless Runner]
    Runner --> Agent[Claude Code / CLI Agent]
    Agent --> Sandbox[隔离执行环境]
    Sandbox --> Output[结构化输出]
    Output --> Judge[自动评分]
    Judge --> Report[评估报告]

对 Agent 产品来说，能被自动化评估，就能更快发现回归问题，也更容易比较不同模型、不同提示词、不同工具配置的效果。

Qoder CLI：终端 Agent 在日常开发中的落地方式

Qoder CLI 和 Claude Code 一样属于终端 Agent 工具。它可以在本地仓库、远端服务器、容器、Kubernetes 环境中运行，也可以通过标准协议接入编辑器。

适合用 Qoder CLI 的场景包括：

安装通常是一行命令，具体命令应以当前官方文档为准。安装后，可以在代码仓库目录中启动 CLI，并通过自然语言或 Slash Command 发起任务。

Qoder CLI 做 Vibe Coding 和规格驱动开发

Vibe Coding 更强调快速把想法变成可运行原型。CLI 形态的优势是它天然贴近文件系统和命令行环境，可以直接创建文件、安装依赖、运行测试、修复报错。

典型任务可以这样描述：

基于当前仓库生成一个最小可运行的后台管理页面，包含用户列表、搜索框、分页和新增用户弹窗。保持现有技术栈和目录结构，不要引入新的 UI 框架。

如果团队采用规格驱动开发，可以把需求沉淀成规格文件，再让 CLI 按规格推进实现。

读取 specs/user-management.md，根据其中的接口、页面和状态流转说明生成实现计划。先不要写代码，只输出需要修改的文件列表和实现步骤。

规格驱动开发的流程更适合团队协作：

flowchart LR
    Req[需求描述] --> Spec[规格文件]
    Spec --> Plan[实现计划]
    Plan --> Code[代码生成]
    Code --> Test[测试生成与执行]
    Test --> Review[代码审查]
    Review --> Merge[合并]

OpenSpec、spec-kit 这类开源实现都可以作为规格层基础设施，让 Agent 不再只围绕聊天上下文工作，而是围绕稳定的工程文档工作。

Qoder CLI 做本地 Code Review

本地代码审查适合在提交前执行。进入仓库后，修改代码，再运行：

/review

这个命令会针对当前仓库未提交的改动进行审查。审查重点一般包括：

• 逻辑错误；
• 边界条件；
• 类型问题；
• 安全风险；
• 性能问题；
• 测试缺失；
• 与项目规范不一致的实现。

本地审查适合开发者自查，能在提交前发现明显问题。

Qoder CLI 接入 GitHub 和 GitLab 审查流程

团队协作中，代码审查最好发生在 Pull Request 或 Merge Request 阶段。Qoder CLI 可以接入 GitHub Action，也可以集成到 GitLab CI。

自动化审查流程通常是：

sequenceDiagram
    participant Dev as 开发者
    participant Git as Git 平台
    participant CI as CI 流水线
    participant Qoder as Qoder CLI
    participant MR as PR/MR 评论区

    Dev->>Git: 提交 Pull Request / Merge Request
    Git->>CI: 触发流水线
    CI->>Qoder: 运行代码审查任务
    Qoder->>Git: 读取 diff 和上下文
    Qoder-->>CI: 输出审查结果
    CI-->>MR: 写入评论或检查结果

和本地 /review 相比，CI 审查有两个优势：

在企业环境中，要额外注意：

• 不要把敏感密钥输出到审查日志；
• 给 CI Token 最小权限；
• 区分阻塞问题和建议问题；
• 对自动评论设置去重，避免重复刷屏；
• 审查结果要能追踪到 commit 和 pipeline。

ACP：让 CLI Agent 接入 IDE

ACP（Agent Client Protocol，Agent 客户端协议）是一种用于连接 Agent 和客户端的协议。它的目标是让 CLI Agent 可以被 IDE、编辑器或其他客户端调用，而不是只能在终端里使用。

Qoder CLI 实现 ACP 后，可以接入支持 ACP 的客户端，例如 Zed 等编辑器。

关系可以这样理解：

flowchart LR
    IDE[IDE / 编辑器] --> ACP[ACP 协议]
    ACP --> CLI[Qoder CLI]
    CLI --> Model[模型]
    CLI --> Repo[代码仓库]
    CLI --> Tools[MCP / Shell / 文件工具]

ACP 的价值在于解耦：

• IDE 负责交互体验；
• CLI Agent 负责推理、工具调用和任务执行；
• 协议负责消息、上下文、工具能力的标准化传递。

这比每个 IDE 单独适配每个 Agent 更容易扩展。

Qoder CLI 用于 ECS 和云上运维

CLI Agent 不只能写业务代码，也适合在远端机器上做运维辅助。只要它能运行在服务器、容器或沙箱环境中，就能读取日志、执行命令、分析网络请求和诊断应用。

ECS 环境搭建

普通用户可以直接用自然语言描述部署目标：

参考 https://github.com/nextcloud/docker，在这台机器上安装并启动 Nextcloud。执行前先说明需要安装的软件、端口占用和数据目录。

Agent 应该完成：

1. 检查系统环境；
2. 判断 Docker 是否安装；
3. 生成部署命令；
4. 启动服务；
5. 检查容器状态；
6. 输出访问地址和后续维护命令。

线上错误分析

开发者可以把错误堆栈交给 CLI：

帮我分析下面的错误堆栈，定位可能原因，并给出验证命令和修复建议。

[错误堆栈信息]

更好的提问方式是同时给出：

• 应用语言和框架；
• 最近变更；
• 部署环境；
• 错误发生时间；
• 相关日志路径；
• 期望行为和实际行为。

网络抓包分析

运维场景中，可以让 CLI 生成并解释抓包命令：

监听 8004 端口上的 HTTP 请求，只关注来源地址为 4.4.4.4 的流量。先给出命令，再解释每个参数含义。

Agent 可能会使用 tcpdump、ss、lsof、curl 等工具，但危险命令和长时间运行命令最好通过 Hooks 或权限确认进行控制。

Qoder CLI 用于 Kubernetes 运维

Qoder CLI 可以结合 Kubernetes MCP 工具运行在远端 Pod 或有集群访问权限的环境中，帮助排查 ACK（Alibaba Cloud Container Service for Kubernetes）或其他 Kubernetes 集群问题。

典型问题：

分析 default 命名空间下 user-service Pod 为什么没有启动成功，要求检查事件、日志、镜像拉取、探针配置和资源限制。

Agent 的诊断路径通常是：

flowchart TB
    A[用户描述 Pod 异常] --> B[kubectl get pod]
    B --> C[kubectl describe pod]
    C --> D{异常类型}
    D -- ImagePullBackOff --> E[检查镜像地址和凭证]
    D -- CrashLoopBackOff --> F[查看容器日志]
    D -- Pending --> G[检查资源、调度、PVC]
    D -- Probe Failed --> H[检查 liveness/readiness probe]
    E --> R[输出原因和修复建议]
    F --> R
    G --> R
    H --> R

修复类任务要特别谨慎。比较稳妥的模式是让 Agent 先输出修复计划，再由用户确认是否执行：

根据诊断结果生成修复方案。不要直接修改集群资源，先输出将要执行的 kubectl 命令和风险说明。

Qoder CLI 用于日志分析和反馈归因

CLI Agent 很适合做日志分析，因为它能同时处理：

• 用户反馈内容；
• 客户端环境信息；
• 配置文件；
• 错误日志；
• 最近版本变更；
• 已知问题库；
• 相关代码路径。

一个反馈归因流程可以这样设计：

flowchart LR
    F[用户反馈] --> N[问题归一化]
    E[环境信息] --> N
    L[日志文件] --> N
    C[配置文件] --> N
    N --> A[Agent 分析]
    A --> R[根因候选]
    R --> V[验证命令或证据]
    V --> S[处理建议]

适合自动分析的问题包括：

如果要把日志分析接入企业流程，需要对日志做脱敏，避免把 Token、手机号、邮箱、内网地址、业务数据直接传入模型上下文。

实际使用中的注意事项

Command 不要放太多长期规则

Command 适合任务入口，不适合承载所有项目规范。长期规则应该放在 CLAUDE.md 或 AGENTS.md，否则每个 Command 都会复制一份规则，后续维护容易不一致。

User 级配置要谨慎

用户级 Command、Skill、Hook 会影响所有项目。适合放通用能力，不适合放某个项目的特殊规范。

Subagent 的上下文隔离既是优点也是限制

隔离能减少污染，但也意味着 Subagent 不知道主 Agent 的全部上下文。给 Subagent 分配任务时，prompt 要包含足够明确的目标、范围、输入文件和输出格式。

Skill 要拆得足够细

一个 Skill 不应该变成巨大的知识库。更好的做法是：

• SKILL.md 只放入口说明；
• 详细内容拆到 reference.md；
• 示例放到 examples.md；
• 可执行逻辑放到 scripts/；
• 输出格式放到 templates/。

Hooks 要可观测、可回滚

Hook 运行在 Agent 执行链路上，写错可能影响所有任务。生产环境建议：

• 给 Hook 脚本加日志；
• 设置超时；
• 对失败行为做降级；
• 先在项目级测试，再推广到用户级或团队级；
• 对危险拦截逻辑写清楚 reason。

Programmatic Tool Calling 必须控制权限

PTC 很适合处理大结果，但代码执行能力必须受控。推荐做法：

• 只允许 code_execution 调用明确白名单工具；
• 限制网络访问；
• 限制文件系统访问范围；
• 设置执行时间和内存上限；
• 对工具结果做脱敏；
• 记录代码和工具调用审计日志。

一个可落地的终端 Agent 工作流

把这些能力组合起来，可以形成一套完整开发流程：

flowchart TB
    A[需求输入] --> B[/plan Command 生成实现计划]
    B --> C[写入 specs/implementation.md]
    C --> D[主 Agent 分配任务]
    D --> E[实现 Subagent 编码]
    D --> F[测试 Subagent 生成测试]
    E --> G[运行测试和格式化 Hooks]
    F --> G
    G --> H[/review 或 code-review Subagent]
    H --> I{是否通过}
    I -- 否 --> D
    I -- 是 --> J[/git-commit Command]
    J --> K[CI 中 Qoder CLI 自动审查 PR/MR]
    K --> L[合并]

这套流程里，各组件职责清楚：

• Command 负责发起固定任务；
• Subagent 负责拆分复杂工作；
• Skills 负责提供专业知识和脚本；
• Hooks 负责确定性工程控制；
• Headless Mode 负责自动化集成；
• Qoder CLI 负责把本地开发、代码审查、IDE 集成、云上运维串起来。

终端 Agent 的重点不是替代所有工程流程，而是接入现有流程，把重复、繁琐、需要上下文切换的工作交给可控的自动化节点。Command、Subagent、Skills、Hooks 和高级工具调用机制，正是让这个节点可管理、可扩展、可审计的基础。