概述

Claude Code Project Template 是一个多智能体（Multi-Agent）项目模板，专为使用 VS Code Copilot 聊天机器人和基于 Python 的自动化场景而设计。该项目集成了 MCP（Model Context Protocol）服务器和 CLI 工具，可用于访问数据库和 API 服务。

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

项目目的与范围

核心目标

资料来源：CLAUDE.md:1-4

技术栈要求

资料来源：README.md:19-20

系统架构

目录结构

├── agents/              # Python 智能体脚本（运行时实现）
├── .claude/agents/      # 聊天智能体（.agent.md 用于 VS Code Copilot）
├── .claude/skills/      # 技能定义（按需工作流）
├── mcp/                 # MCP 服务器实现
├── tools/               # CLI 工具和独立脚本
├── config/              # 环境配置和连接设置
├── docs/                # 项目文档
└── tests/               # 测试套件

资料来源：README.md:9-17

架构流程图

graph TD
    A[用户/开发者] --> B[Claude Code CLI]
    B --> C[Chat Agent<br/>.claude/agents/]
    B --> D[Python Agent<br/>agents/]
    C --> E[Skills<br/>.claude/skills/]
    D --> F[MCP Server<br/>mcp/server.py]
    F --> G[External Services<br/>数据库/API/GitHub]
    D --> H[CLI Tools<br/>tools/]

智能体类型

本项目支持两种类型的智能体系统。

资料来源：AGENTS.md:11-12

Python 智能体

Python 智能体是可执行的 Python 脚本，用于独立任务、CI 流水线以及 MCP 集成。

资料来源：AGENTS.md:14-18

示例：Hello World 智能体

"""Agent that prints hello world."""

def run():
    print("hello world")

if __name__ == "__main__":
    run()

资料来源：agents/hello_world.py:1-8

配置文件示例

# Hello World Agent Configuration
name: hello_world
description: Agent that prints a hello world greeting

# Output settings
output:
  message: "hello world"

资料来源：config/hello_world.yaml:1-7

Chat 智能体

Chat 智能体是 VS Code Copilot 的角色定义，通过 @agent-name 在聊天中调用。

资料来源：AGENTS.md:24-30

内置 Chat 智能体

资料来源：README.md:62-66

MCP 服务器

MCP（Model Context Protocol）服务器用于向智能体暴露工具接口。

资料来源：mcp/README.md:1-3

设计原则

资料来源：mcp/README.md:4-7

MCP 交互流程

graph LR
    A[Claude Code CLI] -->|MCP Protocol| B[MCP Server]
    B --> C[GitHub API]
    B --> D[Database]
    B --> E[External APIs]

MCP 服务器管理命令

# 添加远程 MCP 服务器
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp"}'

# 添加本地 MCP 服务器
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=<TOKEN> -- docker run -i --rm ghcr.io/github/github-mcp-server

# 添加自定义项目 MCP 服务器
claude mcp add-json mytools '{"command": "python", "args": ["mcp/server.py"]}'

# 列出所有服务器
claude mcp list

# 检查服务器配置和健康状态
claude mcp get <server-name>

# 移除服务器
claude mcp remove <server-name>

资料来源：README.md:44-59

CLI 工具

tools/ 目录下的独立脚本可被智能体调用或独立运行。

资料来源：tools/README.md:1-3

设计规范

资料来源：tools/README.md:5-8

配置管理

所有外部连接（数据库、API）的配置集中在 config/ 目录。

资料来源：config/README.md:1-3

配置文件说明

资料来源：config/README.md:5-7

环境配置示例

# 安装依赖
pip install -r requirements.txt

# 配置环境变量
cp config/.env.example config/.env
# 编辑 .env 添加实际凭据

依赖项

项目依赖通过 requirements.txt 管理。

资料来源：requirements.txt:1-3

快速开始

安装步骤

# 克隆仓库
git clone <repo-url>
cd claude-code-project-template

# 安装依赖
pip install -r requirements.txt

# 配置环境
cp config/.env.example config/.env

# 启动 MCP 服务器
python mcp/server.py

# 运行 Python 智能体
python agents/sum_numbers.py 3 5

# 运行测试
pytest

资料来源：README.md:83-97

Claude Code CLI 使用方式

# 启动交互式会话
claude

# 非交互式执行单条指令
claude --p "Analyze the files in this directory"

# 预批准工具权限
claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash

# 运行特定聊天智能体
claude --p "What is 9 + 27" --agent calculating

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

扩展指南

添加新组件流程

资料来源：README.md:68-77

安全规范

资料来源：README.md:60-63

智能体执行规则

当通过 runSubagent 或其他方式委托给聊天智能体时，必须：

1. 读取并遵循 .agent.md 正文的完整行为指令
2. 不仅仅是使用描述进行路由
3. 包括：约束条件、步骤方法、技能检查程序、必需输出格式
4. 例如：当无技能匹配时使用 ⚠️ 前缀

资料来源：CLAUDE.md:32-39

项目概述

Claude Code Project Template 是一个多代理项目模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该项目专为 VS Code Copilot 聊天代理和基于 Python 的自动化场景设计。

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

系统架构

项目采用模块化架构，包含以下核心组件：

graph TD
    subgraph "客户端层"
        A["VS Code Copilot"] 
        B["Claude Code CLI"]
        C["Python 脚本"]
    end
    
    subgraph "代理层"
        D["Chat Agents<br/>.claude/agents/"]
        E["Python Agents<br/>agents/"]
    end
    
    subgraph "工具层"
        F["MCP Server<br/>mcp/"]
        G["CLI Tools<br/>tools/"]
    end
    
    subgraph "外部服务"
        H["Database/APIs"]
    end
    
    A --> D
    B --> E
    B --> F
    C --> E
    D --> F
    E --> G
    F --> H
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style F fill:#f3e5f5

资料来源：README.md:9-20

前置条件

环境要求

资料来源：README.md:22-23

必需依赖

项目依赖通过 requirements.txt 管理，核心依赖包括：

资料来源：requirements.txt:1-3

安装步骤

1. 克隆项目仓库

git clone <repo-url>
cd claude-code-project-template

2. 安装 Python 依赖

pip install -r requirements.txt

3. 配置环境变量

cp config/.env.example config/.env

然后编辑 config/.env 文件，填入实际的凭证信息。重要：.env 文件包含敏感信息，切勿提交到版本控制系统。

资料来源：README.md:84-91

4. 安装 Claude Code CLI（可选）

如果需要使用 Claude Code 命令行工具：

Windows 系统：

# 使用 winget 安装 Node.js
winget install OpenJS.NodeJS.LTS

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

Linux 系统：

curl -fsSL https://deb.nodesource.com/setup_lts.x | sudo -E bash -
sudo apt-get install -y nodejs
npm install -g @anthropic-ai/claude-code

资料来源：README.md:26-55

运行项目

启动 MCP 服务器

python mcp/server.py

运行 Python 代理

项目内置两个示例代理：

#### 运行 hello_world 代理

python agents/hello_world.py

输出结果：

hello world

资料来源：agents/hello_world.py:1-8

#### 运行 sum_numbers 代理

python agents/sum_numbers.py 3 5

代理类型详解

Python 代理

Python 代理是位于 agents/ 目录下的可执行脚本，用于独立任务、CI 流水线或 MCP 集成。

graph LR
    A["创建代理文件<br/>agents/<name>.py"] --> B["创建配置文件<br/>config/<name>.yaml"]
    B --> C["添加运行逻辑"]
    C --> D["测试运行<br/>python agents/<name>.py"]

每个 Python 代理对应一个 YAML 配置文件，配置结构如下：

资料来源：config/hello_world.yaml:1-6

Chat 代理

Chat 代理是 VS Code Copilot 的角色定义，位于 .claude/agents/ 目录，使用 Markdown 格式配合 YAML 前置元数据。

资料来源：README.md:106-112

配置管理

环境变量配置

项目配置遵循以下约定：

• 所有外部连接（数据库、API）的配置放在 config/ 目录
• 敏感信息存储在 .env 文件中
• .env 文件永不提交到版本控制

YAML 配置文件格式

# 代理配置示例
name: <代理名称>
description: <功能描述>

# 输出设置（可选）
output:
  message: "输出消息"

# 输入设置（可选）
input:
  a: 0
  b: 0

资料来源：config/sum_numbers.yaml:1-8

MCP 服务器配置

添加 MCP 服务器

Claude Code 支持添加本地和远程 MCP 服务器：

# 添加远程 MCP 服务器（如 GitHub）
claude mcp add-json github '{"type":"http","url":"https://api.githubcopilot.com/mcp","headers":{"Authorization":"Bearer <YOUR_GITHUB_PAT>"}}'

# 添加本地 MCP 服务器
claude mcp add github -e GITHUB_PERSONAL_ACCESS_TOKEN=<YOUR_GITHUB_PAT> -- docker run -i --rm -e GITHUB_PERSONAL_ACCESS_TOKEN ghcr.io/github/github-mcp-server

# 添加自定义项目 MCP 服务器
claude mcp add-json mytools '{"command": "python", "args": ["mcp/server.py"], "env": {}}'

MCP 服务器管理命令

作用域选项

资料来源：README.md:58-75

自动化执行

非交互式执行

使用 --p 参数执行单条指令：

claude --p "Analyze the files in this directory and write a short summary to SUMMARY.md"

预授权工具

在自动化流水线中使用 --approvedTool 预授权工具，避免交互确认：

claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash

指定代理执行

# 使用 calculating 代理计算
claude --p "What is 9 + 27" --agent calculating

# 使用 texting 代理打招呼
claude --p "Say hello to the world" --agent texting

# 使用 orchestrator 代理执行复合任务
claude --p "Calculate 5^2 then greet me" --agent orchestrator

资料来源：README.md:93-105

测试

运行项目测试套件：

pytest

添加新组件指南

新增 Python 代理

新增 Chat 代理

新增 MCP 工具

资料来源：README.md:113-125

最佳实践

1. 模块化设计：优先复用现有工具，避免重复造轮子
2. 配置分离：所有外部连接配置放在 config/ 目录
3. 敏感信息安全：凭证信息存储在 .env 文件，切勿提交
4. 工具描述清晰：MCP 工具需提供清晰的名称和文档字符串，便于代理发现
5. 独立测试：CLI 工具和 MCP 工具应能独立运行测试

资料来源：README.md:126-131

项目概述

本项目是一个基于 Claude Code 的多智能体系统模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该模板专为 VS Code Copilot 聊天智能体和基于 Python 的自动化场景设计。

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

整体架构

系统采用模块化分层架构，各组件职责清晰分离：

graph TD
    subgraph "表现层"
        A["VS Code Copilot Chat"]
        B["Claude Code CLI"]
        C["终端/命令行"]
    end

    subgraph "智能体层"
        D["Chat Agents<br/>(.claude/agents/)"]
        E["Python Agents<br/>(agents/)"]
    end

    subgraph "工具层"
        F["Skills<br/>(.claude/skills/)"]
        G["MCP Servers<br/>(mcp/)"]
        H["CLI Tools<br/>(tools/)"]
    end

    subgraph "配置层"
        I["配置文件<br/>(config/)"]
        J["环境变量<br/>(.env)"]
    end

    A --> D
    B --> D
    B --> E
    C --> E
    D --> F
    D --> G
    E --> G
    E --> H
    G --> K["外部服务"]
    H --> K
    I --> D
    I --> E
    J --> G
    J --> H

资料来源：README.md:18-28

目录结构

核心组件

1. Python 智能体

Python 智能体是可直接执行的 Python 脚本，用于独立任务、CI 流水线、MCP 集成等场景。

graph LR
    A["配置文件<br/>config/<name>.yaml"] --> B["Python 脚本<br/>agents/<name>.py"]
    B --> C["终端执行<br/>python agents/<name>.py"]

特点：

• 每个智能体对应一个 Python 文件
• 配置信息存储在 config/ 目录下的 YAML 文件中
• 可通过命令行参数或配置文件进行参数传递

资料来源：AGENTS.md:18-23

配置示例：

# config/sum_numbers.yaml
name: sum_numbers
description: 计算两个数字之和的智能体

input:
  a: 0
  b: 0

资料来源：config/sum_numbers.yaml:1-7

代码实现示例：

# agents/hello_world.py
"""Agent that prints hello world."""

def run():
    print("hello world")

if __name__ == "__main__":
    run()

资料来源：agents/hello_world.py:1-8

2. Chat 智能体

Chat 智能体是 VS Code Copilot 的角色定义，通过 @agent-name 在聊天中调用。

graph TD
    A["用户输入<br/>@agent-name"] --> B["VS Code Copilot"]
    B --> C["解析 .agent.md"]
    C --> D["执行技能/工具"]
    D --> E["返回结果"]

特点：

• 使用 Markdown 格式定义，包含 YAML 前置元数据
• 元数据中定义工具列表、模型配置等
• 可通过 Skills 定义斜杠命令

资料来源：AGENTS.md:24-32

Chat 智能体类型：

3. MCP 服务器

MCP 服务器实现 Model Context Protocol 标准，向智能体暴露各种工具。

graph LR
    A["Claude Code CLI"] --> B["MCP Server<br/>(mcp/server.py)"]
    B --> C["外部服务<br/>(GitHub, DB, API)"]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e8

功能：

• 暴露工具供智能体发现和调用
• 提供数据库、API 等外部服务访问能力
• 支持本地和远程 MCP 服务器配置

资料来源：README.md:25-26

服务器管理命令：

4. CLI 工具

独立脚本，可独立运行或被智能体调用。

特点：

• 独立可测试
• 可接受配置参数
• 返回结构化输出（优先使用 JSON）

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

配置管理

配置架构

graph TD
    A[".env.example"] -->|模板| B[".env"]
    B --> C["环境变量"]
    D["<name>.yaml"] -->|智能体配置| E["运行时参数"]
    
    C --> F["MCP Servers"]
    C --> G["CLI Tools"]
    E --> H["Python Agents"]
    
    style B fill:#ffcdd2
    style D fill:#c8e6c9

配置文件位置： config/ 目录

资料来源：config/README.md:1-6

安全规范

• 所有外部连接（数据库、API）在 config/ 中配置
• 敏感信息存储在 .env 文件中
• .env 和 .mcp.json 必须添加到 .gitignore

资料来源：README.md:51-52

智能体执行流程

Python 智能体执行

sequenceDiagram
    participant User
    participant CLI
    participant Agent
    participant Config
    participant External

    User->>CLI: python agents/<name>.py [args]
    CLI->>Agent: 加载脚本
    Agent->>Config: 读取 config/<name>.yaml
    Config-->>Agent: 返回配置参数
    Agent->>External: 访问服务/API
    External-->>Agent: 返回数据
    Agent-->>User: 输出结果

Chat 智能体执行

sequenceDiagram
    participant User
    participant Copilot
    participant Agent
    participant Skills
    participant MCP

    User->>Copilot: @agent-name <指令>
    Copilot->>Agent: 加载 .agent.md
    Agent->>Agent: 解析元数据和行为规则
    Agent->>Skills: 检查技能匹配
    Agent->>MCP: 调用工具
    MCP-->>Agent: 工具返回结果
    Agent-->>Copilot: 格式化输出
    Copilot-->>User: 显示结果

资料来源：CLAUDE.md:38-47

开发规范

添加新组件

命名和文档规范

• MCP 工具必须具有清晰、描述性的名称和文档字符串
• 文档字符串用于智能体发现
• 优先组合现有工具而非创建新工具

资料来源：README.md:64-66

依赖关系

项目依赖

pytest>=7.0
python-dotenv>=1.0
pyyaml>=6.0

资料来源：requirements.txt:1-3

运行时依赖

• Python 3.10+
• Node.js 和 npm（用于 Claude Code CLI）
• VS Code 及 GitHub Copilot 扩展（用于聊天智能体）

资料来源：README.md:31-33

技术栈总结

概述

claude-code-project-template 是一个多智能体项目模板，集成了 MCP 服务器（Model Context Protocol）和 CLI 工具，用于访问数据库和 API。该项目专为 VS Code Copilot 聊天智能体和基于 Python 的自动化场景设计，支持交互式和自动化流水线执行。

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

整体架构

项目采用分层架构设计，各模块职责明确，通过标准协议实现解耦。

graph TD
    A[用户/自动化系统] --> B[Claude Code CLI]
    B --> C[Chat Agents<br/>.claude/agents/]
    B --> D[Python Agents<br/>agents/]
    D --> E[MCP Server<br/>mcp/]
    E --> F[External Services<br/>GitHub, DB, APIs]
    C --> G[Skills<br/>.claude/skills/]
    D --> H[CLI Tools<br/>tools/]
    I[Config<br/>config/] --> D
    I --> E

资料来源：CLAUDE.md:1-20

目录结构详解

目录一览表

资料来源：README.md:12-22

概述

Python智能体（Python Agents）是本项目中的可执行Python脚本，用于处理独立任务、CI/CD流程、自动化管道以及MCP集成。智能体采用"一个智能体一个文件"的设计原则，每个智能体对应agents/目录下的一个.py文件，并配有config/目录下的对应YAML配置文件。

资料来源：AGENTS.md:1-6

架构设计

智能体类型分类

本项目支持两种类型的智能体：

资料来源：AGENTS.md:14-26

Python智能体架构图

graph TD
    A[用户/系统] --> B[终端/命令行]
    B --> C[python agents/<name>.py]
    C --> D[config/<name>.yaml]
    C --> E[run 函数]
    E --> F[业务逻辑处理]
    F --> G[输出结果]
    G --> H[返回值/打印输出]
    
    style A fill:#e1f5fe
    style C fill:#fff3e0
    style D fill:#f3e5f5

目录结构规范

标准目录布局

├── agents/              # Python智能体脚本（运行时实现）
├── config/              # YAML配置文件
└── docs/                # 文档说明

• agents/：存放所有Python智能体实现，每个智能体一个.py文件
• config/：存放对应的YAML配置文件，采用智能体名称.yaml命名

资料来源：AGENTS.md:7-11

智能体实现规范

基本结构要求

每个Python智能体必须满足以下结构规范：

1. 入口函数：必须定义run()函数作为主入口
2. 直接执行：在if __name__ == "__main__":块中调用run()函数
3. 参数解析：使用argparse模块处理命令行参数（可选）
4. 返回值：run()函数可返回处理结果供调用方使用

资料来源：agents/hello_world.py:1-8

配置规范

智能体配置采用YAML格式，包含以下标准字段：

name: 智能体名称
description: 智能体功能描述

# 根据智能体类型添加相应配置
output:
  message: "输出消息"

资料来源：config/hello_world.yaml:1-6config/sum_numbers.yaml:1-11

开发示例

示例一：简单消息输出智能体

#### 源代码

"""Agent that prints hello world."""


def run():
    print("hello world")


if __name__ == "__main__":
    run()

资料来源：agents/hello_world.py:1-8

#### 配置文件

# Hello World Agent Configuration
name: hello_world
description: Agent that prints a hello world greeting

# Output settings
output:
  message: "hello world"

资料来源：config/hello_world.yaml:1-6

#### 运行方式

python agents/hello_world.py

输出结果：hello world

示例二：带参数的计算智能体

#### 源代码

"""Agent that calculates the sum of two numbers."""

import argparse


def run(a: float, b: float) -> float:
    result = a + b
    print(f"{a} + {b} = {result}")
    return result


if __name__ == "__main__":
    parser = argparse.ArgumentParser(description="Sum two numbers")
    parser.add_argument("a", type=float, help="First number")
    parser.add_argument("b", type=float, help="Second number")
    args = parser.parse_args()
    run(args.a, args.b)

资料来源：agents/sum_numbers.py:1-19

#### 配置文件

# Sum Numbers Agent Configuration
name: sum_numbers
description: Agent that calculates the sum of two numbers

# Input settings
input:
  a: 0
  b: 0

资料来源：config/sum_numbers.yaml:1-9

#### 运行方式

python agents/sum_numbers.py 3 5

输出结果：3.0 + 5.0 = 8.0

#### 参数说明

智能体执行流程

graph LR
    A[启动命令] --> B[参数解析]
    B --> C[加载配置]
    C --> D[执行业务逻辑]
    D --> E{是否成功}
    E -->|成功| F[返回结果]
    E -->|失败| G[错误处理]
    F --> H[输出到终端]
    G --> I[输出错误信息]
    
    style A fill:#e1f5fe
    style D fill:#fff3e0
    style F fill:#e8f5e9
    style G fill:#ffebee

新增智能体开发指南

开发步骤

资料来源：AGENTS.md:52-57

开发检查清单

• [ ] 智能体文件放在agents/目录下
• [ ] 配置文件放在config/目录下，文件名与智能体名一致
• [ ] 定义了run()函数作为入口
• [ ] 配置文件中包含name和description字段
• [ ] 已测试命令行执行
• [ ] 错误处理完善（适用于复杂智能体）

与其他组件的集成

MCP集成架构

Python智能体可与MCP（Model Context Protocol）服务器集成，实现更强大的工具调用能力：

graph TD
    A[Python智能体] --> B[MCP服务器]
    B --> C[MCP工具]
    C --> D[外部服务]
    C --> E[数据库]
    C --> F[API]
    
    style A fill:#e1f5fe
    style B fill:#fff3e0
    style C fill:#e8f5e9

子进程调用模式

在自动化管道中，Python智能体可通过subprocess模块被调用：

import subprocess

def run_agent(agent_script: str, args: list) -> str:
    command = ["python", agent_script] + args
    result = subprocess.run(
        command,
        capture_output=True,
        text=True,
        check=True
    )
    return result.stdout

开发最佳实践

代码规范

1. 单一职责：每个智能体只完成一个特定任务
2. 清晰的函数命名：使用描述性的函数名
3. 完整的文档字符串：为模块和函数添加docstring
4. 参数验证：对输入参数进行必要的验证

配置管理

• 所有外部连接配置放在config/目录
• 敏感信息使用.env文件管理，绝不提交到版本控制
• 配置文件采用YAML格式，便于读取和维护

资料来源：agents/README.md:1-5

总结

Python智能体是本项目的重要组成部分，采用简洁的文件结构和标准化配置。每个智能体通过统一的run()函数接口实现，配置通过YAML文件管理，便于维护和扩展。智能体支持独立命令行执行、子进程调用以及MCP协议集成，为构建复杂的AI自动化系统提供了灵活的基础架构。

概述

聊天智能体（Chat Agent）是该多智能体项目模板中的核心组件之一，专为 VS Code Copilot 聊天界面设计的对话式 AI 角色。与 Python 代理不同，聊天智能体通过自然语言交互的方式工作，用户可以在 Copilot 聊天窗口中通过 @agent-name 语法直接调用特定的智能体。

聊天智能体的主要特点包括：

• 通过 Markdown 文件加 YAML 前置元数据定义
• 与 VS Code Copilot 深度集成
• 支持技能（Skills）扩展，通过斜杠命令触发
• 可实现多智能体协作和委派机制

资料来源：CLAUDE.md

智能体类型对比

该项目支持两种类型的智能体，理解它们的区别对于正确选择和开发至关重要。

资料来源：AGENTS.md

目录结构

聊天智能体统一存放在项目根目录的 .claude/agents/ 目录下，采用 Markdown 格式定义。

.claude/
├── agents/                      # 聊天智能体目录
│   ├── calculating.agent.md     # 计算智能体
│   ├── texting.agent.md         # 文本处理智能体
│   └── orchestrator.agent.md    # 编排智能体
└── skills/                      # 技能目录
    └── <skill-name>/
        └── SKILL.md            # 技能定义文件

资料来源：CLAUDE.md

智能体配置与定义

文件格式规范

聊天智能体采用 Markdown 文件格式，文件扩展名为 .agent.md。每个文件包含两部分：

1. YAML 前置元数据 - 定义智能体的名称、描述、可用工具、模型等配置
2. Markdown 正文 - 定义智能体的行为指令、约束条件和输出格式要求

YAML 前置元数据字段

正文行为规范

智能体的 Markdown 正文定义了严格的运行时行为规范，包括：

• 约束条件（Constraints）- 智能体必须遵守的规则
• 执行步骤（Approach/Steps）- 完成任务的推荐流程
• 技能检查程序（Skill-checking procedures）- 何时调用技能
• 输出格式要求（Output formats）- 返回结果的格式规范

概述

技能（Skill）是 Claude Code 项目模板中的一种可复用工作流机制，允许聊天代理按需调用预定义的功能模块。技能以 slash 命令（/skill-name）的形式暴露给用户和 AI 代理，实现标准化的任务执行流程。

在多代理系统架构中，技能是连接聊天代理与具体业务逻辑的桥梁。当用户在 VS Code Copilot 聊天中输入 /hello-world 或 /sum 时，系统会触发对应的技能定义执行相应操作。资料来源：AGENTS.md

技能在架构中的位置

┌─────────────────────────────────────────────────────────────┐
│                    Claude Code CLI                          │
└─────────────────────────┬───────────────────────────────────┘
                          │
┌─────────────────────────▼───────────────────────────────────┐
│                  VS Code Copilot Chat                        │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │ @texting    │  │@calculating │  │@orchestrator│          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          ▼                ▼                ▼
    ┌─────────────────────────────────────────────────┐
    │              技能层 (Skills)                     │
    │  ┌──────────────┐  ┌──────────────┐            │
    │  │ /hello-world │  │    /sum      │   ...      │
    │  └──────────────┘  └──────────────┘            │
    └─────────────────────────────────────────────────┘
                          │
                          ▼
    ┌─────────────────────────────────────────────────┐
    │              工具层 (Tools)                      │
    │              CLI 脚本和独立工具                   │
    └─────────────────────────────────────────────────┘

技能层位于聊天代理与底层工具之间，提供了一层抽象，使得代理能够以统一的方式调用各种功能。资料来源：CLAUDE.md

技能类型

项目中的技能按调用方式可分为以下两类：

资料来源：AGENTS.md

技能目录结构

每个技能占用一个独立目录，采用统一的文件命名规范：

.claude/skills/
└── <skill-name>/
    └── SKILL.md          # 技能定义文件（必须）

命名规范

• 目录名称应使用 kebab-case（小写字母，单词间用连字符分隔）
• 目录名称即 slash 命令名称（如 hello-world 目录对应 /hello-world 命令）
• SKILL.md 文件名必须全大写

资料来源：README.md

SKILL.md 文件结构

技能定义文件采用 Markdown 格式，包含以下核心组成部分：

基本结构

# 技能名称

简短描述技能的功能和用途。

## 触发条件

描述何时应该调用此技能。

## 执行步骤

1. 步骤一说明
2. 步骤二说明
3. 步骤三说明

## 输出格式

描述技能的返回结果格式。

技能执行流程

graph TD
    A[用户输入 /skill-name] --> B{技能定义解析}
    B -->|找到 SKILL.md| C[读取技能指令]
    B -->|未找到| D[返回错误提示]
    C --> E[执行预定义步骤]
    E --> F[格式化输出结果]
    F --> G[返回给调用方]

创建新技能

操作步骤

资料来源：README.md

技能定义示例：hello-world

以下是一个简单技能的完整定义：

# Hello World 技能

打印一条问候世界的信息。

## 触发条件

用户请求打印问候语或测试系统响应时调用。

## 执行步骤

1. 输出标准问候语 "hello world"
2. 返回执行成功状态

## 输出格式

纯文本字符串：hello world

技能定义示例：sum

以下是一个带参数的技能定义：

# Sum 技能

计算两个数字的和。

## 触发条件

用户请求计算两个数的加法时调用。

## 输入参数

| 参数名 | 类型 | 必填 | 说明 |
|-------|------|------|------|
| a | number | 是 | 第一个加数 |
| b | number | 是 | 第二个加数 |

## 执行步骤

1. 解析输入的两个数字
2. 执行加法运算：a + b
3. 返回计算结果

## 输出格式

JSON 对象：
{
  "result": <sum>,
  "input": { "a": <a>, "b": <b> }
}

技能与聊天代理的关系

技能可以被聊天代理（.agent.md）引用和使用。代理的前置元数据（YAML frontmatter）可以声明其可用的技能列表：

概述

MCP（Model Context Protocol，模型上下文协议）服务器是本项目的核心组件之一，负责为AI代理提供与外部服务和数据源交互的能力。通过MCP服务器，Claude Code CLI可以安全地访问GitHub、数据库、API等外部资源。

graph TD
    A[Agent 代理] --> B[Claude Code CLI]
    B --> C[MCP Server MCP服务器]
    C --> D[External Service 外部服务]
    C --> E[Database 数据库]
    C --> F[API 接口]
    
    style C fill:#e1f5fe
    style D fill:#fff3e0
    style E fill:#fff3e0
    style F fill:#fff3e0

作用域范围： MCP服务器配置支持三种作用域级别，分别用于不同的共享范围和使用场景。

资料来源：README.md:92

概述

CLI自动化工具是本项目的核心能力之一，通过命令行接口实现任务的自动化执行。系统支持三种主要的CLI自动化模式：Claude Code CLI命令执行、Python子进程管道调用、以及独立的命令行脚本工具。这些组件共同构成了从简单脚本到复杂多步骤自动化流程的完整工具链。

项目架构中，tools/目录存放独立的CLI工具脚本，agents/目录包含Python agent实现，而Claude Code CLI则提供与大语言模型交互的桥梁。资料来源：README.md:1-10

Claude Code CLI工具

Claude Code CLI是Anthropic提供的命令行工具，支持与Claude大语言模型进行交互式或自动化对话。该工具需要Node.js和npm环境支持，安装后可通过claude命令直接调用。资料来源：README.md:18-35

交互式与非交互式模式

Claude Code CLI提供两种基本运行模式。交互式模式启动完整的对话会话，用户可在REPL环境中与AI进行实时对话：

claude

非交互式模式（管道模式）允许通过命令行参数直接传递指令，适合自动化脚本和CI/CD流程：

claude --p "Analyze the files in this directory and write a short summary to SUMMARY.md"

参数-p（或--print）表示非交互式执行，指令完成后自动退出而非停留在REPL状态。资料来源：README.md:88-96

工具权限预批准机制

在自动化流水线中，没有人工实时响应确认提示，因此Claude Code提供了--approvedTool参数来预批准特定工具的使用权限：

claude --p "Refactor utils.py" --approvedTool edit --approvedTool bash

该机制允许指定白名单内的工具（如edit、bash、read等）可以直接执行而无需人工确认。预批准工具是实现完全无人值守执行的关键配置。资料来源：README.md:97-101

指定Agent执行

Claude Code支持运行预定义的chat agent，通过--agent参数指定：

claude --p "What is 9 + 27" --agent calculating
claude --p "Say hello to the world" --agent texting
claude --p "Calculate 5^2 then greet me" --agent orchestrator

预定义的chat agent包括@texting（文本生成）、@calculating（数学运算）和@orchestrator（任务编排）。agent通过.claude/agents/目录下的.agent.md文件定义。资料来源：README.md:102-107

MCP服务器管理命令

Claude Code集成了MCP（Model Context Protocol）协议，支持通过CLI管理MCP服务器：

# 列出所有MCP服务器
claude mcp list

# 查看特定服务器的配置和健康状态
claude mcp get <server-name>

# 移除服务器
claude mcp remove <server-name>

MCP服务器可以是远程HTTP服务或本地Docker容器，支持添加JSON配置或命令式配置。资料来源：README.md:56-83

Python自动化管道

除了直接调用CLI命令，项目还提供了Python封装接口，通过subprocess模块实现Claude Code的编程式调用。这种方式适合需要与Python应用深度集成的自动化场景。资料来源：README.md:111-130

核心实现函数

项目定义了run_claude_pipeline函数作为Python与Claude Code之间的桥梁：

import subprocess
import os

def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
    env = os.environ.copy()
    command = [
        "claude", "--p", prompt_text,
        "--approvedTool", "edit",
        "--approvedTool", "bash",
        "--approvedTool", "read",
    ]
    if agent:
        command.extend(["--agent", agent])

    try:
        result = subprocess.run(
            command,
            capture_output=True,
            text=True,
            check=True,
            env=env
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        return e.stderr

该函数接受提示文本和可选的agent名称参数，返回命令的标准输出。错误信息通过stderr捕获并返回。资料来源：README.md:111-130

环境变量传递

函数使用os.environ.copy()复制当前环境变量，确保Python进程的环境配置（如API密钥、路径设置）能够传递给子进程。这种模式保持了环境的一致性，同时允许在需要时添加或覆盖特定变量。资料来源：README.md:113

独立CLI工具

tools/目录下的CLI工具是独立运行的脚本，具有两个关键特性：可以独立通过命令行执行，也可以被agents调用。这种设计确保了工具的灵活性和可复用性。资料来源：tools/README.md:1-10

设计原则

每个CLI工具应满足以下设计要求：

CLI工具优先使用JSON作为输出格式，因为结构化数据更易于被AI agent解析和处理。资料来源：tools/README.md:7-9

Python Agents的命令行接口

Python agents作为独立脚本运行时采用简单直接的设计模式。以hello_world.py为例：

"""Agent that prints hello world."""

def run():
    print("hello world")

if __name__ == "__main__":
    run()

每个agent包含一个run()函数作为入口点，if __name__ == "__main__"块确保模块既可独立运行也可被导入使用。运行agent只需执行Python脚本并传入所需参数。资料来源：agents/hello_world.py:1-10

Agent配置管理

Python agents的配置通过config/目录下的YAML文件管理。例如sum_numbers.yaml定义了求和agent的输入参数：

name: sum_numbers
description: Agent that calculates the sum of two numbers

input:
  a: 0
  b: 0

配置文件采用标准YAML格式，包含agent名称、描述和输入参数定义。这种配置与代码分离的设计允许在不修改源码的情况下调整agent行为。资料来源：config/sum_numbers.yaml:1-8

工具组合与工作流

CLI自动化工具支持多种组合方式以适应不同场景：

graph TD
    A[人工触发/定时任务] --> B[Claude Code CLI]
    A --> C[Python subprocess]
    A --> D[直接运行Python Agent]
    
    B --> E[Chat Agents]
    B --> F[MCP Servers]
    
    C --> G[run_claude_pipeline函数]
    G --> E
    G --> F
    
    D --> H[Python Agent执行]
    H --> I[调用CLI工具]
    I --> J[返回结构化结果]
    
    E --> K[响应输出]
    F --> L[外部服务集成]
    J --> K

典型使用场景

环境配置与安全

CLI工具涉及敏感信息（如API密钥、访问令牌），项目制定了严格的安全规范。所有密钥必须存储在.env文件中，且.env和.mcp.json必须添加到.gitignore禁止提交到版本控制。资料来源：README.md:85

配置文件的分离设计确保了本地开发环境与生产环境的安全隔离：

# 安装依赖
pip install -r requirements.txt

# 配置环境
cp config/.env.example config/.env
# 编辑.env填入实际凭证

依赖项包括python-dotenv（环境变量加载）、pyyaml（配置解析）和pytest（测试框架）。资料来源：requirements.txt:1-4

扩展CLI工具

向项目中添加新的CLI工具需遵循既定的文件组织规范：

添加CLI工具时应确保其可独立测试，这是集成到自动化流程前的质量保障。资料来源：AGENTS.md:47-52

概述

Python自动化管道（Python Automated Pipeline）是claude-code-project-template项目中的核心组件之一，它通过Python的subprocess模块实现对Claude Code CLI的非交互式程序化调用。该管道允许开发者在Python应用程序或CI/CD流程中自动化执行Claude Code任务，无需人工干预即可完成代码分析、编辑和执行操作。

此功能的主要价值在于将Claude Code强大的AI辅助能力集成到现有的Python工作流中，使得批量处理、自动化测试和持续集成场景下的代码任务执行成为可能。资料来源：README.md:1-10

架构设计

组件交互关系

Python自动化管道采用分层架构，各组件之间通过标准输入/输出流进行通信：

graph TD
    A[Python应用] --> B[run_claude_pipeline 函数]
    B --> C[subprocess.run]
    C --> D[Claude Code CLI]
    D --> E[--p 参数<br/>非交互模式]
    D --> F[--approvedTool<br/>预授权工具]
    D --> G[--agent<br/>指定代理]
    G --> H[Chat Agent<br/>.claude/agents/]
    H --> I[@calculating]
    H --> J[@texting]
    H --> K[@orchestrator]

管道执行流程

flowchart TD
    A[启动run_claude_pipeline] --> B{agent参数<br/>是否指定?}
    B -->|是| C[添加--agent参数]
    B -->|否| D[跳过agent配置]
    C --> E[构建command列表]
    D --> E
    E --> F[复制环境变量]
    F --> G[执行subprocess.run]
    G --> H{执行成功?}
    H -->|是| I[返回stdout输出]
    H -->|否| J[捕获CalledProcessError]
    J --> K[打印错误诊断信息]
    K --> L[返回空字符串]

核心函数

run_claude_pipeline

该函数是Python自动化管道的入口点，负责构建和执行Claude Code命令。

函数签名：

def run_claude_pipeline(prompt_text: str, agent: str = None) -> str

参数说明：

返回值：

源码实现：

# 资料来源：[README.md:120-150]()

def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
    env = os.environ.copy()
    command = [
        "claude", "--p", prompt_text,
        "--approvedTool", "edit",
        "--approvedTool", "bash",
        "--approvedTool", "read",
    ]
    if agent:
        command.extend(["--agent", agent])

    try:
        result = subprocess.run(
            command,
            capture_output=True,
            text=True,
            check=True,
            env=env
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Pipeline error status code: {e.returncode}")
        print(f"Error Diagnostic Info:\n{e.stderr}")
        return ""

预授权工具

管道默认预授权以下三个工具，确保Claude Code在自动化执行过程中不会因等待用户确认而阻塞：

资料来源：README.md:132-134

使用示例

示例一：执行默认Claude任务

最基本的用法，无需指定代理：

import subprocess
import os

def run_claude_pipeline(prompt_text: str, agent: str = None) -> str:
    env = os.environ.copy()
    command = [
        "claude", "--p", prompt_text,
        "--approvedTool", "edit",
        "--approvedTool", "bash",
        "--approvedTool", "read",
    ]
    if agent:
        command.extend(["--agent", agent])

    try:
        result = subprocess.run(
            command,
            capture_output=True,
            text=True,
            check=True,
            env=env
        )
        return result.stdout
    except subprocess.CalledProcessError as e:
        print(f"Pipeline error status code: {e.returncode}")
        print(f"Error Diagnostic Info:\n{e.stderr}")
        return ""

if __name__ == "__main__":
    output = run_claude_pipeline("Review python script syntax errors in the current directory.")
    print(f"Output:\n{output}")

资料来源：README.md:150-170

示例二：调用特定聊天代理

通过agent参数指定具体的聊天代理执行任务：

if __name__ == "__main__":
    # 调用calculating代理执行数学运算
    output = run_claude_pipeline("What is 9 + 27", agent="calculating")
    print(f"Agent Output:\n{output}")

可用的聊天代理包括：

资料来源：README.md:55-65

环境配置

环境变量处理

管道通过os.environ.copy()复制当前进程的环境变量，确保Claude Code能够访问必要的系统配置：

env = os.environ.copy()

这种方法的优势在于：

• 保留所有现有的环境变量
• 允许在env字典中添加或覆盖特定变量
• 避免修改父进程的环境状态

执行环境要求

资料来源：CLAUDE.md:1-15

错误处理机制

管道实现了健壮的错误处理策略，通过捕获subprocess.CalledProcessError异常来诊断执行失败：

except subprocess.CalledProcessError as e:
    print(f"Pipeline error status code: {e.returncode}")
    print(f"Error Diagnostic Info:\n{e.stderr}")
    return ""

错误处理流程：

集成应用场景

CI/CD流水线集成

Python自动化管道可无缝集成到持续集成/持续部署流程中：

# 示例：CI配置文件
stages:
  - code-review
  
code-review:
  script:
    - python -c "
        from agents.sum_numbers import run
        run(3, 5)
      "

批量任务处理

通过循环调用实现批量代码分析：

files_to_analyze = ["utils.py", "helpers.py", "models.py"]

for file in files_to_analyze:
    result = run_claude_pipeline(f"Analyze {file} for potential bugs")
    process_result(result)

多代理协同工作

利用orchestrator代理协调多个专家代理完成任务：

result = run_claude_pipeline(
    "Calculate 5^2 then greet me",
    agent="orchestrator"
)

最佳实践

安全考虑

性能优化

• 批量处理：将多个相关任务合并为单一提示
• 环境缓存：避免重复创建环境变量副本
• 超时控制：为长时间运行的任务设置适当超时

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

相关模块

资料来源：CLAUDE.md:10-20

扩展阅读

• Claude Code安装与使用文档
• MCP服务器配置指南
• 项目主README

Pitfall Log / 踩坑日志

项目：chonlim92/claude-code-project-template

摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

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

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

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

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

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

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

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

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

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

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

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

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

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

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