Claude Code专业代理套件

Claude Code的专业AI代理、安全技能和开发工具的全面、生产就绪集合。

存储库： https://github.com/qepting91/claude-agent-suite 文档： https://qepting91.github.io/claude-agent-suite/

🎯 包含什么

15名专业代理

后端： Python、Go、Node.js、通用后端
前端： HTML/CSS、AstroJS、UX/UI设计
数据库： PostgreSQL、MySQL、MongoDB（带MCP集成）
安全： 安全工程、安全代码审查
基础设施： PowerShell自动化
应用： Streamlit开发
元：提示工程

安全与最佳实践

用于bash命令验证的预配置安全挂钩
Post工具使用钩子进行文件修改跟踪
具有最小权限默认值的权限系统
Trail of Bits安全技能集成指南
OWASP和CWE一致的安全模式

MCP服务器配置

PostgreSQL连接模板
MySQL连接模板
MongoDB连接模板
文件系统访问配置

全面文档

完整的代理商参考指南
安全技能集成指南
代理开发的最佳实践
工作流程建议

现代建筑系统

基于Jinja2的模板编译 具有可重用的技能组件
自动验证：令牌预算、bash语法、危险命令
全面的测试套件 覆盖率>90%（pytest）
CI/CD管道 在3个平台上，4个Python版本（GitHub操作）
质量保证：过梁（黑色、异色、片状8）、类型检查（mypy）

______________________________________________________________________

🔄 CI/CD和合规性

该项目包括具有自动测试、安全扫描和合规性审计的企业级CI/CD。

GitHub操作工作流

工作流	触发器	目的
`test.yml`	Push/PR	多平台测试（Ubuntu、Windows、macOS）
`security.yml`	推送/PR	安全扫描（Semgrep、Bandit、pip审计）
`release.yml`	标签（v\*）	构建、测试、打包和发布版本
`audit-log.yml`	发布后	将证据存档到不可变分支
`docs.yml`	推送到文档站点/	将文档构建并部署到GitHub页面

代码分析检查

每次推送和PR都会进行全面的代码分析：

静态分析：

Semgrep -SAST扫描安全漏洞（OWASP模式）
匪徒 -Python特定的安全linter
拉夫 -快速Python linter（取代flake8）

依赖安全：

pip审计 -扫描Python依赖项中的已知CVE
安全 -其他漏洞数据库检查

代码质量：

黑色 -代码格式
isort -导入排序
米皮 -类型检查
薄片8 -风格指南执行

构建验证：

代币预算执行（每个代理最多2500个代币）
代码块中的Bash语法验证
危险指令检测（rm-rf/、chmod 777等）
YAML前体验证

智力测试（Promptfoo）

在标记的发布中，代理会根据真实的AI模型进行测试：

# Run locally
make eval

# Configuration
eval/promptfoo.yaml         # Test configuration
eval/datasets/smoke-tests.jsonl  # Test cases

测试验证代理可以正确处理：

Python架构问题
安全代码审查场景
API设计最佳实践

自动发布

使用以下内容创建发布：

# Tag and push
git tag -a v0.0.6 -m "Release v0.0.6"
git push origin v0.0.6

# Or use Makefile helper
make release-tag V=0.0.6

发布工作流程：

✅ 从模板构建所有16个代理
✅ 运行完整的测试套件
✅ 运行智能测试（可选，如果设置了API密钥）
✅ 创造 claude-agents-vX.X.X.zip 包裹
✅ 发布到GitHub发布
✅ 档案审计证据

不可变审计跟踪

每次发布都会在上创建SHA256证据清单 evidence-audit 分支：

{
  "metadata": {
    "timestamp": "2026-02-05T21:00:00Z",
    "git_sha": "abc123...",
    "git_tag": "v0.0.5"
  },
  "artifacts": {
    "agents": [
      {"file": "python-architect.md", "sha256": "e3b0c44..."}
    ],
    "security_config": {
      "dangerous_commands_sha256": "..."
    }
  }
}

分支保护： 启用保护 evidence-audit （无强制推动，无删除）以确保合规性。

必需的秘密

机密	必填	目的
`GITHUB_TOKEN`	Auto	由GitHub提供，用于发布
`ANTHROPIC_API_KEY`	可选	用于Promptfoo智能测试

文档网站

文档是用Docusaurus构建的，并自动部署到GitHub Pages：

现场： https://qepting91.github.io/claude-agent-suite/

在本地运行：

cd docs-site
npm install
npm start        # Opens http://localhost:3000

生成代理库：

node scripts/doc-gen.mjs

______________________________________________________________________

🚀 快速开始

先决条件

Claude 代码命令行界面 （最新版本）

   # Check if installed
   claude --version

   # If not installed:
   # Windows: irm https://claude.ai/install.ps1 | iex
   # Mac/Linux: curl -fsSL https://claude.ai/install.sh | bash

Git （用于克隆此存储库）

Node.js/npm （用于语言服务器和MCP）

   node --version
   npm --version

语言服务器二进制文件 （可选，用于代码智能）

   # Python
   npm install -g pyright

   # TypeScript/JavaScript
   npm install -g typescript-language-server typescript

   # Go
   go install golang.org/x/tools/gopls@latest

______________________________________________________________________

💻 系统要求

最低要求

磁盘空间： 主目录中有2MB可用空间（包括备份空间）
权限： 写入访问权限 ~/.claude 目录
操作系统支持：

- Linux：Ubuntu 20.04+、Debian 11+、RHEL 8+ - macOS：12.0（蒙特利）+ - Windows:10/11使用PowerShell 5.1+

软件依赖关系

必修的： Claude Code CLI（最新版本），Git 2.20+
可选： Node.js 18+和npm 9+（用于MCP数据库服务器）

兼容性说明

窗户： 建议使用PowerShell 7+（最低5.1）
macOS： 完全支持苹果硅（M1/M2/M3）
WSL： 通过支持Linux的Windows子系统 install.sh

______________________________________________________________________

📥 安装

自动安装（推荐）

Windows（PowerShell）

# Clone this repository
git clone https://github.com/qepting91/claude-agent-suite.git
cd claude-agent-suite

# Run installation script
.\install.ps1

Linux/Mac（Bash）

# Clone this repository
git clone https://github.com/qepting91/claude-agent-suite.git
cd claude-agent-suite

# Make script executable and run
chmod +x install.sh
./install.sh

安装脚本将：

✅ 备份您现有的 .claude 配置
✅ 将代理复制到 ~/.claude/agents/
✅ 复制文档文件
✅ 合并设置（保留现有配置）
✅ 验证安装

手动安装

如果您更喜欢手动控制：

克隆存储库：

   git clone https://github.com/qepting91/claude-agent-suite.git
   cd claude-agent-suite

备份现有配置：

   # Windows (PowerShell)
   Copy-Item -Recurse $HOME\.claude $HOME\.claude.backup.$(Get-Date -Format 'yyyyMMdd-HHmmss')

   # Linux/Mac
   cp -r ~/.claude ~/.claude.backup.$(date +%Y%m%d-%H%M%S)

生成代理（手动安装时需要）：

   # Install build dependencies
   pip install -r requirements.txt

   # Compile templates to production agents
   python scripts/build.py --verbose

复制已编译的代理：

   # Windows (PowerShell)
   Copy-Item -Recurse dist\agents\* $HOME\.claude\agents\

   # Linux/Mac
   cp -r dist/agents/* ~/.claude/agents/

复制文档：

   # Windows (PowerShell)
   Copy-Item docs\* $HOME\.claude\

   # Linux/Mac
   cp docs/* ~/.claude/

合并设置（小心）：

- 审查 config/settings.json 来自此存储库 - 手动将挂钩和权限合并到您的 ~/.claude/settings.json - 不要覆盖整个设置文件！

______________________________________________________________________

🔧 安装后配置

1.验证代理安装

打开克劳德代码并运行：

/agents

您应该看到列出的所有15个代理。

2.安装代码智能插件（推荐）

# In Claude Code
/plugin install pyright-lsp@claude-plugins-official
/plugin install typescript-lsp@claude-plugins-official
/plugin install gopls-lsp@claude-plugins-official

3.配置MCP数据库连接（可选）

对于特定于项目的数据库： 创建 .mcp.json 在项目根目录中：

{
  "mcpServers": {
    "postgresql": {
      "type": "stdio",
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@modelcontextprotocol/server-postgres", "postgresql://user:pass@localhost:5432/dbname"]
    }
  }
}

看 AGENT_TEAM_GUIDE.md 了解详细的MCP配置说明。

4.安装比特安全技能追踪（强烈推荐）

# In Claude Code
/plugin marketplace add trailofbits/skills

# Install essential security skills
/plugin install trailofbits/skills/plugins/differential-review
/plugin install trailofbits/skills/plugins/audit-context-building
/plugin install trailofbits/skills/plugins/variant-analysis

看 integrate-trailofbits.md 完整的安全技能设置。

______________________________________________________________________

📚 文档

安装后，这些指南可在 ~/.claude/:

AGENT_TEAM_GUIDE.md -完整的代理参考
集成式轨道钻头.md -安全技能整合

______________________________________________________________________

🎓 使用示例

安全代码审查

/secure-code-reviewer @path/to/file.py

后端开发

/backend-engineer "Design a RESTful API for user management"
/python-architect @api/users.py

前端设计

/ux-ui-designer "Review the checkout flow for accessibility"
/frontend-architect @components/checkout.html

使用MCP进行数据库操作

/postgres-dba "Find slow queries and suggest indexes"

______________________________________________________________________

🔒 安全特性

PreToolUse挂钩： 验证bash命令的安全性
PostTool使用挂钩： 跟踪文件修改
安全代理： 威胁建模和漏洞检测
Bits集成之路： 专业安全技能

______________________________________________________________________

🛠️ 定制

添加自己的代理

创建 ~/.claude/agents/my-agent.md:

---
name: my-agent
description: When to use this agent
tools: Read, Grep, Glob
model: sonnet
---

Your agent instructions here

刷新： /agents refresh

______________________________________________________________________

🔄 更新中

标准更新

cd claude-agent-suite
git pull origin main
./install.sh  # or install.ps1 on Windows

⚠️ 重要提示：定制代理

安装程序会覆盖所有默认代理。 如果您定制了15个包含的代理中的任何一个：

首先备份自定义代理：

   # Linux/Mac
   cp ~/.claude/agents/[your-modified-agent].md ~/backup/

   # Windows (PowerShell)
   Copy-Item $HOME\.claude\agents\[your-modified-agent].md $HOME\backup\

运行更新：

   ./install.sh  # or install.ps1 on Windows

还原或合并自定义更改：

   # Option 1: Restore your version (overwrites update)
   cp ~/backup/[agent].md ~/.claude/agents/

   # Option 2: Manually merge changes
   diff ~/backup/[agent].md ~/.claude/agents/[agent].md

最佳实践： 为定制代理使用唯一的名称（例如。， my-python-expert.md)以避免更新过程中的覆盖。

______________________________________________________________________

🐛 故障排除

安装问题

错误：“找不到代理目录”

原因： 存储库下载为ZIP而不是git clone。

解决方案：

删除下载的ZIP目录
正确克隆： git clone https://github.com/qepting91/claude-agent-suite.git
重新运行安装脚本

错误：“权限被拒绝”

原因： 主目录权限不足。

解决方案（Linux/Mac）：

sudo chown -R $USER:$USER ~/.claude
chmod 755 ~/.claude

解决方案（Windows）： 以管理员身份运行PowerShell

警告：“不是git仓库”

影响： 未来更新通过 git pull 不会工作。

预防： 始终使用git克隆存储库，而不是以ZIP格式下载。

问题：安装后“代理计数：0”

诊断：

# Check if files actually exist
ls ~/.claude/agents/  # Linux/Mac
dir $HOME\.claude\agents\  # Windows

解决方案： 重新运行安装程序。如果问题仍然存在，请检查磁盘空间和权限。

错误：“代理计数不匹配”

原因： 存储库下载损坏或安装中断。

解决方案：

删除存储库目录
新鲜克隆： git clone https://github.com/qepting91/claude-agent-suite.git
重新运行安装程序

运行时问题

代理未显示在/代理列表中

诊断和解决方案：

跑 /agents refresh 克劳德代码
验证文件是否存在： ls ~/.claude/agents/*.md （应显示15个文件）
检查frontmatter语法： head -5 ~/.claude/agents/python-architect.md （应该从 ---)
完全重新启动Claude代码

MCP数据库连接失败

诊断：

/mcp
claude mcp list

常见问题和解决方案：

数据库凭据不正确→ 检查中的连接字符串 .mcp.json
npx 不在PATH中→ 验证Node.js安装： node --version
端口已在使用中→ 与核对 netstat -an | grep 5432 （调整端口）
未安装MCP服务器→ Run npx -y @modelcontextprotocol/server-postgres --version

回滚和恢复

恢复以前的配置

安装程序创建带时间戳的备份。要还原，请执行以下操作：

# Find your backup
ls -d ~/.claude.backup.*

# Restore (replace timestamp with yours)
rm -rf ~/.claude
mv ~/.claude.backup.20260202-143022 ~/.claude

窗户：

# Find backup
Get-ChildItem $HOME\.claude.backup.*

# Restore
Remove-Item -Recurse $HOME\.claude
Move-Item $HOME\.claude.backup.20260202-143022 $HOME\.claude

完全卸载

# Backup first (optional)
cp -r ~/.claude ~/.claude.manual-backup

# Remove everything
rm -rf ~/.claude

窗户：

Copy-Item -Recurse $HOME\.claude $HOME\.claude.manual-backup
Remove-Item -Recurse $HOME\.claude

诊断命令

# Verify installation
/agents                           # List all agents
/doctor                          # Run diagnostics
claude --version                 # Check CLI version

# Check file counts
ls ~/.claude/agents/*.md | wc -l # Should be 15

# Validate agent format
head -10 ~/.claude/agents/python-architect.md

______________________________________________________________________

❓ 常见问题

安装

Q：这会影响我目前的经纪人吗？ A：否。安装程序在进行任何更改之前会创建一个带时间戳的备份。您的原始配置将保留。

Q：需要多少磁盘空间？ A：总计约2MB（代理+文档+备份空间）。

Q：我可以自定义包含的代理吗？ A：是的，但请注意，更新将覆盖您的更改。 推荐解决方案： 将代理复制到具有唯一名称的新文件中（例如。， my-python-architect.md)并定制该版本。

Q：我需要全部15名特工吗？ A：不需要。安装后，您可以从中删除任何不需要的代理 ~/.claude/agents/.

Q：我可以安全地重新运行安装程序吗？ A：是的。安装程序是幂等的，每次都会创建一个新的带时间戳的备份。

Q：安装后我需要重新启动Claude Code吗？ A：不，但你应该跑 /agents refresh 以重新加载代理列表。

Q：如果安装中途失败怎么办？ A：安装程序将尝试自动回滚到您的备份。如果失败，您可以从手动还原 ~/.claude.backup.[timestamp].

配置

Q：如何添加我自己的代理？ A：创建一个 .md 归档 ~/.claude/agents/ 使用YAML frontmatter。有关所需格式，请参阅CONTRIBUTING.md指南。

Q：我可以修改安全挂钩吗？ A：是的。编辑 ~/.claude/settings.json 要自定义 hooks 部分。看 config/settings.json 例如。

Q：如何配置MCP数据库连接？ A：创建 .mcp.json 在项目根目录中或在中配置 ~/.claude.json 用于用户范围的设置。有关详细说明，请参阅AGENT_TEAM_GUIDE.md。

更新

Q：如何在不丢失自定义设置的情况下进行更新？ A.

备份任何自定义代理： cp ~/.claude/agents/[modified-agent].md ~/backup/
运行安装程序： ./install.sh
还原自定义设置： cp ~/backup/[agent].md ~/.claude/agents/

或者为定制代理使用唯一的文件名（例如。， my-custom-python.md)以避免冲突。

Q：如果 git pull 以“不是git存储库”失败？ A：存储库以ZIP文件的形式下载。删除目录并正确克隆：

git clone https://github.com/qepting91/claude-agent-suite.git

Q：我应该多久更新一次？ A：每周检查存储库中的安全补丁和新功能。订阅GitHub发布以获取通知。

安全

Q：安全挂钩的作用是什么？ A： PreToolUse钩子在执行之前验证bash命令（检查破坏性操作、凭据暴露等）。PostToolUse挂钩跟踪文件修改。看 config/settings.json 了解详情。

Q：我可以禁用安全挂钩吗？ A：是的，但不推荐。移除 hooks 部分从 ~/.claude/settings.json 禁用。

Q：这些药物使用安全吗？ A：是的。所有代理都遵循最小特权原则——他们只能访问所需的最小工具。默认情况下，安全代理是只读的。

用法

Q：我应该使用哪个代理来执行\[任务\]？ A：使用 /agents 查看带有描述的完整列表。路由器将根据您的请求自动选择最佳代理。

Q：我可以同时使用多个代理吗？ A：是的。您可以为任务的不同部分调用不同的代理，也可以将一个代理的输出作为另一个的输入。

Q：数据库代理是否要求数据库运行？ A： postgres-dba、mysql专家和mongo架构师代理需要MCP服务器连接。其他代理在没有任何外部依赖的情况下工作。

______________________________________________________________________

📊 安装什么

安装过程编译模板并安装生产代理：

Build Process:
  src/agents/*.md.j2 → [scripts/build.py] → dist/agents/*.md → ~/.claude/agents/

~/.claude/
├── agents/                          # 15 compiled agents
│   ├── python-architect.md          # From dist/agents/ (compiled from src/agents/python-architect.md.j2)
│   ├── go-expert.md
│   ├── node-engineer.md
│   ├── backend-engineer.md
│   ├── frontend-architect.md
│   ├── astro-expert.md
│   ├── ux-ui-designer.md
│   ├── streamlit-expert.md
│   ├── powershell-automator.md
│   ├── postgres-dba.md
│   ├── mysql-expert.md
│   ├── mongo-architect.md
│   ├── security-engineer.md
│   ├── secure-code-reviewer.md
│   └── prompt-engineer.md
│
├── AGENT_TEAM_GUIDE.md             # Complete reference
├── integrate-trailofbits.md        # Security skills guide
└── settings.json                    # Hooks merged (preserves existing config)

备注：用户从接收已编译的代理 dist/agents/，不是来自的源模板 src/agents/.

______________________________________________________________________

🧪 开发与测试

项目架构

此项目使用 基于模板的构建系统 编译专门的AI代理：

架构概述:

Development Flow:
  src/agents/*.md.j2  →  scripts/build.py  →  dist/agents/*.md  →  ~/.claude/agents/
  (edit these)           (compiler)           (generated)         (user installation)

目录结构:

src/agents/          # Source templates (edit these) - Jinja2 templates with includes
src/skills/          # Reusable components - Shared patterns via {% include %}
scripts/build.py     # Build system - Jinja2 compiler + validation
dist/agents/         # Compiled output (generated) - Production-ready agents
agents/              # Legacy (will be removed) - Old static files
tests/               # Test suite - Pytest unit + integration tests
config/              # Build configuration - Validation rules, dangerous commands

构建系统

构建系统编译模板并验证输出：

# Build all agents from templates
python scripts/build.py

# Build with verbose output
python scripts/build.py --verbose

# Validate templates without building
python scripts/build.py --validate-only

构建系统的功能是什么:

在中查找模板 src/agents/*.md.j2
渲染带有变量的Jinja2模板，并包含
验证frontmatter（必填字段，有效模型）
强制令牌预算（每个代理最多2500个令牌）
验证代码块中的bash语法
检测危险的命令模式（rm-rf/、chmod 777等）
将生产代理写入 dist/agents/*.md
报告统计数据和错误

运行测试

# Install test dependencies
pip install -r requirements.txt

# Run all tests
pytest

# Run with coverage report
pytest --cov=scripts --cov-report=html

# View coverage report
open htmlcov/index.html

使用Make（Linux/Mac）

# Show all available commands
make help

# Run tests
make test

# Build agents
make build

# Run code linters
make lint

看 tests/README.md 获取详细的测试文档。

🤝 贡献

克隆该仓库
创建要素分支
通过文档添加您的代理/技能
运行测试: pytest （所有测试必须通过）
验证构建: python scripts/build.py --validate-only
提交拉取请求

代理开发工作流程

重要：始终在中编辑源模板 src/agents/，从不编译输出 dist/agents/.

编辑模板: src/agents/*.md.j2 （Jinja2模板）
创造技能 （可选）： src/skills/category/module.md （可重复使用的组件）
构建: python scripts/build.py --verbose （编译模板）
测试输出：评论 dist/agents/*.md （编辑代理人）
本地测试 （可选）： cp dist/agents/agent-name.md ~/.claude/agents/
运行测试: pytest （所有测试必须通过）
验证构建: python scripts/build.py --validate-only
仅提交来源: git add src/agents/ （永远不要承诺 dist/ 目录）
提交PR：GitHub操作将验证您的更改

承诺什么

一定要承诺:

✅ src/agents/*.md.j2 （源模板）
✅ src/skills/**/*.md （可重复使用的组件）
✅ tests/**/*.py （测试文件）
✅ scripts/build.py （构建系统更改）
✅ 文档更新（README、CLAUDE.md等）

不要承诺:

❌ dist/agents/*.md （生成的文件，忽略git）
❌ .coverage, htmlcov/ （测试输出，忽略git）
❌ __pycache__/, *.pyc （Python缓存，忽略git）

为什么？ 这 dist/ 目录包含可以从源代码重新生成的构建工件。提交它们会打乱git历史记录并导致合并冲突。

______________________________________________________________________

📄 许可证

MIT许可证

______________________________________________________________________

🙏 致谢

Anthropic -克劳德代码平台
比特的踪迹 -安全技能市场
MCP社区 -数据库服务器实现

______________________________________________________________________

📞 支持

文档： 看 AGENT_TEAM_GUIDE.md
克劳德代码文档： https://code.claude.com/docs
问题： https://github.com/qepting91/claude-agent-suite/issues

______________________________________________________________________

版本： 0.0.5 最后更新时间： 2026-02-02 状态： ✅ 生产就绪

______________________________________________________________________

⭐ 如果您觉得此存储库有用，请将其标记为星号！

由...制作❤️ Claude Code社区 @qepting91

Claude Agent Suite

快速接入

详细介绍

Claude Code专业代理套件

🎯 包含什么

15名专业代理

安全与最佳实践

MCP服务器配置

全面文档

现代建筑系统

🔄 CI/CD和合规性

GitHub操作工作流

代码分析检查

智力测试（Promptfoo）

自动发布

不可变审计跟踪

必需的秘密

文档网站

🚀 快速开始

先决条件

💻 系统要求

最低要求

软件依赖关系

兼容性说明

📥 安装

自动安装（推荐）

Windows（PowerShell）

Linux/Mac（Bash）

手动安装

🔧 安装后配置

1.验证代理安装

2.安装代码智能插件（推荐）

3.配置MCP数据库连接（可选）

4.安装比特安全技能追踪（强烈推荐）

📚 文档

🎓 使用示例

安全代码审查

后端开发

前端设计

使用MCP进行数据库操作

🔒 安全特性

🛠️ 定制

添加自己的代理

🔄 更新中

标准更新

⚠️ 重要提示：定制代理

🐛 故障排除

安装问题

错误：“找不到代理目录”

错误：“权限被拒绝”

警告：“不是git仓库”

问题：安装后“代理计数：0”

错误：“代理计数不匹配”

运行时问题

代理未显示在/代理列表中

MCP数据库连接失败

回滚和恢复

恢复以前的配置

完全卸载

诊断命令

❓ 常见问题

安装

配置

更新

安全

用法

📊 安装什么

🧪 开发与测试

项目架构

构建系统

运行测试

使用Make（Linux/Mac）

🤝 贡献

代理开发工作流程

承诺什么

📄 许可证

🙏 致谢

📞 支持

目录标签

接入字段