Agent Config Doctor

Agent Config Doctor 快速入门

一句话卖点: Agent 配置文件越多越容易出错——Config Doctor 一键扫描所有配置，找出不一致和潜在问题

这是什么?适合谁?

Agent Config Doctor 是本地优先的 AI 编码 Agent 配置扫描器——自动扫描 Agent 配置、MCP 文件、Skills、提示词和工作流权限，诊断配置错误和不一致。

核心理念：Agent 生态中配置文件越来越多（CLAUDE.md、AGENTS.md、MCP 配置、Skill 定义、工作流权限），配置错误或不一致会导致 Agent 行为异常——但手动检查这些配置既繁琐又容易遗漏。Agent Config Doctor 自动扫描和诊断这些配置，帮助开发者发现和修复配置问题。

与 skill-probe（Skill 运行时审计器）互补：skill-probe 做运行时审计，Agent Config Doctor 做配置静态扫描。两者结合形成 Agent 配置的”编译时+运行时”检查体系。

适合：使用多个 Agent 工具和 Skill 的开发者，需要维护复杂 Agent 配置的团队。不适合：只使用单一 Agent 工具的简单场景。

准备工作

1. 安装 Python 3.10+
2. 了解基本的 Agent 配置文件格式（CLAUDE.md、MCP JSON、Skill 定义）
3. 准备好要扫描的项目目录

3步快速上手

第1步: 安装

git clone https://github.com/shuowenzhang1-netizen/agent-config-doctor.git
cd agent-config-doctor
pip install -r requirements.txt

第2步: 扫描项目配置

在项目根目录运行：

python doctor.py scan /path/to/your/project

Config Doctor 会自动发现并扫描：

• CLAUDE.md / AGENTS.md 文件
• MCP 配置文件（.mcp.json 或 mcp.json）
• Skill 定义文件
• 工作流权限配置
• 提示词模板

第3步: 查看诊断报告

扫描完成后，Config Doctor 输出诊断报告，包括：

• 配置冲突：同一设置在不同文件中定义了不同的值
• 缺失配置：引用了不存在的 MCP 服务器或 Skill
• 权限问题：工作流权限配置与 Skill 声明不一致
• 格式错误：JSON 语法错误或不符合 schema 的配置

根据报告中的建议逐一修复配置问题。

常见踩坑

1. 扫描路径必须是项目根目录——Config Doctor 从根目录开始递归搜索配置文件，不在根目录运行可能遗漏配置
2. 自定义配置文件路径需要额外配置——如果配置文件不在标准位置，需要在 doctor.py 中指定
3. Python 版本要求 3.10+——较低版本可能不支持某些语法特性
4. 诊断结果需要人工判断——Config Doctor 标记的”问题”可能是你有意为之的配置，需要人工审核
5. 首次扫描可能输出大量警告——这是正常的，逐步修复即可

高级玩法

1. CI 集成：将 Config Doctor 加入 CI 流水线，配置变更时自动扫描
2. 自定义规则：编写项目特定的扫描规则，检测业务相关的配置问题
3. 多项目对比：扫描多个项目，对比 Agent 配置的最佳实践
4. 配置迁移辅助：在升级 Agent 工具版本时，用 Config Doctor 检测需要更新的配置

小技巧

1. 将 Config Doctor 加入 pre-commit hook，每次提交前自动扫描
2. 使用 —output json 参数导出结构化报告，方便集成到其他工具
3. 关注仓库更新——作者可能添加新的配置类型支持
4. 将扫描报告保存为基线，后续扫描只关注新增问题
5. 配合 skill-probe 使用——Config Doctor 做静态检查，skill-probe 做运行时验证

常见问题 FAQ

Q1: Config Doctor 支持哪些 Agent 工具的配置？

目前主要支持 Claude Code 生态的配置文件（CLAUDE.md、MCP JSON、Skill 定义）。对其他 Agent 工具（如 Cursor、Codex）的配置支持取决于配置文件格式的兼容性。信息来源：GitHub README。

Q2: Config Doctor 会修改我的配置文件吗？

不会。Config Doctor 只做只读扫描和诊断，不会自动修改任何配置文件。你需要根据诊断报告手动修复。信息来源：GitHub README。

Q3: Config Doctor 和 skill-probe 有什么区别？

Config Doctor 做静态配置扫描（“配置文件写对了吗”），skill-probe 做运行时审计（“Skill 实际运行正常吗”）。两者互补：先用 Config Doctor 确保配置正确，再用 skill-probe 验证运行时行为。信息来源：两个项目的 GitHub README。

Q4: 扫描需要联网吗？

不需要。Config Doctor 完全在本地运行，不会上传任何配置数据。信息来源：GitHub README（“Local-first”）。

Q5: 支持自定义扫描规则吗？

支持。你可以编写自定义规则来检测项目特定的配置问题。参考仓库中的规则编写文档。信息来源：GitHub README。

参考链接

• GitHub 仓库：github.com/shuowenzhang1-netizen/agent-config-doctor
• 相关项目：skill-probe（Skill 运行时审计器）
• Claude Code Skills 文档：docs.claude.com/en/docs/claude-code
• MCP 协议规范：modelcontextprotocol.io