Claude Atlas：Claude Code配置的可视化审计与治理工具

扫描、映射并可视化Claude Code配置，自动发现重复代理、冲突触发器和孤立记忆文件，提供交互式HTML报告和CI集成能力。

问题背景：配置蔓延的隐形成本\n\nClaude Code作为Anthropic推出的AI编程助手，允许用户通过自定义代理（agents）和技能（skills）来扩展其能力。用户可以在~/.claude/目录下配置全局代理，也可以在各个项目的.claude/目录下配置项目级代理。\n\n随着使用时间增长，这种灵活性也带来了配置管理的挑战：\n\n- 重复代理：两个功能几乎相同的代理竞争相同的触发词\n- 孤立文件：为已放弃项目编写的CLAUDE.md文件仍然留在系统中\n- 配置覆盖：全局技能被某个项目中的同名项目级版本静默覆盖\n- 触发冲突：多个代理共享相似的触发模式，导致Claude Code难以确定应该激活哪个代理\n\n这些问题不会立即导致系统崩溃，但会 silently（静默地）降低工作效率，甚至在不恰当的时机触发错误的代理行为。Claude Atlas正是为了解决这一痛点而设计的审计工具。\n\n## 核心功能概览\n\nClaude Atlas提供两种主要使用模式：\n\n### 快速健康检查（check命令）\n\n适合在终端快速查看配置状态，可在CI/CD流程中集成：\n\nbash\n# 默认：发现任何高严重性问题时失败\nclaude-atlas check\n\n# 仅检查重复和覆盖问题\nclaude-atlas check --max-severity high --quiet\n\n# CI集成，输出GitHub Actions注解格式\nclaude-atlas check --format github\n\n# JSON格式输出，供自定义工具链使用\nclaude-atlas check --top 0 --format json\n\n\n返回码：0（无问题）、1（达到阈值的问题）、2（错误）。\n\n### 完整交互式扫描（scan命令）\n\n生成详细的HTML报告，支持可视化探索和深度分析：\n\nbash\n# 扫描~/.claude + 当前目录，输出到./claude-atlas.html\nclaude-atlas scan\n\n# 扫描指定路径\nclaude-atlas scan --paths ~/work/arco --paths ~/work/flagbridge -o /tmp/atlas.html\n\n# 自动发现嵌套的.claude/目录\nclaude-atlas scan --auto-discover ~/work --auto-discover ~/personal\n\n# 启用语义分析（需要ANTHROPIC_API_KEY）\nclaude-atlas scan --semantic\n\n\n## 技术实现：从扫描到可视化\n\n### 发现阶段（Discovery）\n\n扫描器递归查找以下配置元素：\n\n- .claude/目录及其中的代理定义文件\n- CLAUDE.md记忆文件\n- 项目级和全局级配置\n\n解析器提取每个构件的前置元数据（frontmatter），包括名称、触发词、描述等信息。\n\n### 分析阶段（Analysis）\n\n分析引擎构建构件关系图，识别以下类型的边（关系）：\n\n| 边类型 | 含义 |\n|--------|------|\n| duplicate_exact | SHA-256哈希完全相同——字面意义上的复制 |\n| duplicate_semantic | Jaccard相似度≥0.60（可疑）/≥0.85（可能重复） |\n| overrides | 项目级构件覆盖同名全局构件 |\n| trigger_collision | 两个构件共享≥2个独特的触发词token |\n| references | 一个构件的内容中提及另一个构件的名称 |\n| contains | 记忆文件将同一.claude/根目录下的构件分组（仅UI展示） |\n\n阈值参数可在src/claude_atlas/analysis/graph.py中调整。\n\n### 语义精炼（可选）\n\n当启用--semantic标志时，工具会将Jaccard标记的候选对发送到Anthropic API进行结构化判断（重复/重叠/独立）。模型判定为"独立"的对将从图中移除，其余对会附加模型的推理说明。\n\n这需要ANTHROPIC_API_KEY，并需要安装semantic额外依赖：uv tool install "claude-atlas[semantic]"。\n\n### 报告生成\n\n扫描结果通过Mustache模板渲染为交互式HTML报告，包含：\n\n- 图可视化：节点代表构件，边代表关系，支持点击查看详情\n- 问题标签页：列出所有需要注意的配置问题\n- 构件详情：查看每个代理的完整定义和元数据\n\n## 架构设计\n\n项目代码结构清晰，模块化程度高：\n\n\nsrc/claude_atlas/\n├── cli.py # Typer命令行接口\n├── models.py # 数据类和枚举定义\n├── scanner/\n│ ├── discovery.py # 发现.claude/目录和CLAUDE.md文件\n│ └── parsers.py # 前置元数据解析\n├── analysis/\n│ ├── graph.py # 启发式分析 → 边列表\n│ └── llm_judge.py # 可选的Anthropic精炼\n└── report/\n ├── renderer.py # ScanResult → HTML\n └── templates/report.mustache\n\n\n这种分层架构使得各模块可以独立测试和演进，也为未来功能扩展提供了清晰的接入点。\n\n## 安装与使用\n\n### 前提条件\n\n- Python 3.11+\n- uv（推荐）、pipx或pip\n\n### 安装uv（如尚未安装）\n\nbash\n# macOS (Homebrew)\nbrew install uv\n\n# macOS / Linux (官方安装脚本)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n\n### 安装claude-atlas\n\nbash\n# 推荐：隔离工具安装\nuv tool install claude-atlas\n\n# 或pipx\npipx install claude-atlas\n\n# 或pip\npip install claude-atlas\n\n\n升级：uv tool upgrade claude-atlas\n\n### 开发安装\n\nbash\ngit clone https://github.com/grippado/claude-atlas.git\ncd claude-atlas\nuv sync --all-extras\nuv run claude-atlas --help\n\n\n## 应用场景与价值\n\n### 个人开发者\n\n对于长期使用Claude Code的开发者，定期运行claude-atlas check可以快速发现配置漂移问题：\n\n- 清理不再需要的孤立文件\n- 合并功能重复的代理\n- 解决触发词冲突\n\n### 团队协作\n\n在团队环境中，Claude Atlas可以帮助：\n\n- 标准化代理命名和触发词约定\n- 识别不同成员创建的重复代理\n- 在项目模板中预配置最佳实践\n\n### CI/CD集成\n\n通过--format github输出，可以在GitHub Actions等CI平台中集成配置健康检查：\n\nyaml\n- name: Check Claude Code Config\n run: claude-atlas check --format github\n\n\n这可以在代码提交时自动检测配置问题，防止有问题的代理定义进入主分支。\n\n## 设计哲学与路线图\n\n项目遵循以下设计原则：\n\n- 离线优先：默认离线运行，不依赖外部API\n- MIT开源：完全开源，社区可自由使用和贡献\n- 多语言支持：文档提供英文和巴西葡萄牙语版本\n\n根据路线图，下一个主要版本v0.4.0将引入HTML分类仪表板：图视图变为次要标签页，主视图变为基于卡片的分类仪表板，包含健康评分、并排预览和针对每个问题的操作按钮。\n\n## 技术启示\n\nClaude Atlas的设计思路对其他AI工具的配置管理具有借鉴意义：\n\n1. 配置即代码：将代理定义视为代码资产，需要版本控制和审计\n2. 静态分析：通过启发式规则在运行前发现问题，而非依赖运行时调试\n3. 可视化优先：交互式HTML报告比纯文本输出更易于理解和决策\n4. 渐进式增强：核心功能离线可用，可选的AI增强功能需要API密钥\n\n对于Claude Code用户而言，这是一个实用的配置治理工具，能够将隐性的配置债务显性化，帮助用户维护一个干净、高效的AI助手环境。

问题背景：配置蔓延的隐形成本\n\nClaude Code作为Anthropic推出的AI编程助手，允许用户通过自定义代理（agents）和技能（skills）来扩展其能力。用户可以在~/.claude/目录下配置全局代理，也可以在各个项目的.claude/目录下配置项目级代理。\n\n随着使用时间增长，这种灵活性也带来了配置管理的挑战：\n\n- 重复代理：两个功能几乎相同的代理竞争相同的触发词\n- 孤立文件：为已放弃项目编写的CLAUDE.md文件仍然留在系统中\n- 配置覆盖：全局技能被某个项目中的同名项目级版本静默覆盖\n- 触发冲突：多个代理共享相似的触发模式，导致Claude Code难以确定应该激活哪个代理\n\n这些问题不会立即导致系统崩溃，但会 silently（静默地）降低工作效率，甚至在不恰当的时机触发错误的代理行为。Claude Atlas正是为了解决这一痛点而设计的审计工具。\n\n核心功能概览\n\nClaude Atlas提供两种主要使用模式：\n\n快速健康检查（check命令）\n\n适合在终端快速查看配置状态，可在CI/CD流程中集成：\n\nbash\n默认：发现任何高严重性问题时失败\nclaude-atlas check\n\n仅检查重复和覆盖问题\nclaude-atlas check --max-severity high --quiet\n\nCI集成，输出GitHub Actions注解格式\nclaude-atlas check --format github\n\nJSON格式输出，供自定义工具链使用\nclaude-atlas check --top 0 --format json\n\n\n返回码：0（无问题）、1（达到阈值的问题）、2（错误）。\n\n完整交互式扫描（scan命令）\n\n生成详细的HTML报告，支持可视化探索和深度分析：\n\nbash\n扫描~/.claude + 当前目录，输出到./claude-atlas.html\nclaude-atlas scan\n\n扫描指定路径\nclaude-atlas scan --paths ~/work/arco --paths ~/work/flagbridge -o /tmp/atlas.html\n\n自动发现嵌套的.claude/目录\nclaude-atlas scan --auto-discover ~/work --auto-discover ~/personal\n\n启用语义分析（需要ANTHROPIC_API_KEY）\nclaude-atlas scan --semantic\n\n\n技术实现：从扫描到可视化\n\n发现阶段（Discovery）\n\n扫描器递归查找以下配置元素：\n\n- .claude/目录及其中的代理定义文件\n- CLAUDE.md记忆文件\n- 项目级和全局级配置\n\n解析器提取每个构件的前置元数据（frontmatter），包括名称、触发词、描述等信息。\n\n分析阶段（Analysis）\n\n分析引擎构建构件关系图，识别以下类型的边（关系）：\n\n| 边类型 | 含义 |\n|--------|------|\n| duplicate_exact | SHA-256哈希完全相同——字面意义上的复制 |\n| duplicate_semantic | Jaccard相似度≥0.60（可疑）/≥0.85（可能重复） |\n| overrides | 项目级构件覆盖同名全局构件 |\n| trigger_collision | 两个构件共享≥2个独特的触发词token |\n| references | 一个构件的内容中提及另一个构件的名称 |\n| contains | 记忆文件将同一.claude/根目录下的构件分组（仅UI展示） |\n\n阈值参数可在src/claude_atlas/analysis/graph.py中调整。\n\n语义精炼（可选）\n\n当启用--semantic标志时，工具会将Jaccard标记的候选对发送到Anthropic API进行结构化判断（重复/重叠/独立）。模型判定为"独立"的对将从图中移除，其余对会附加模型的推理说明。\n\n这需要ANTHROPIC_API_KEY，并需要安装semantic额外依赖：uv tool install "claude-atlas[semantic]"。\n\n报告生成\n\n扫描结果通过Mustache模板渲染为交互式HTML报告，包含：\n\n- 图可视化：节点代表构件，边代表关系，支持点击查看详情\n- 问题标签页：列出所有需要注意的配置问题\n- 构件详情：查看每个代理的完整定义和元数据\n\n架构设计\n\n项目代码结构清晰，模块化程度高：\n\n\nsrc/claude_atlas/\n├── cli.py Typer命令行接口\n├── models.py 数据类和枚举定义\n├── scanner/\n│ ├── discovery.py 发现.claude/目录和CLAUDE.md文件\n│ └── parsers.py 前置元数据解析\n├── analysis/\n│ ├── graph.py 启发式分析 → 边列表\n│ └── llm_judge.py 可选的Anthropic精炼\n└── report/\n ├── renderer.py ScanResult → HTML\n └── templates/report.mustache\n\n\n这种分层架构使得各模块可以独立测试和演进，也为未来功能扩展提供了清晰的接入点。\n\n安装与使用\n\n前提条件\n\n- Python 3.11+\n- uv（推荐）、pipx或pip\n\n安装uv（如尚未安装）\n\nbash\nmacOS (Homebrew)\nbrew install uv\n\nmacOS / Linux (官方安装脚本)\ncurl -LsSf https://astral.sh/uv/install.sh | sh\n\n\n安装claude-atlas\n\nbash\n推荐：隔离工具安装\nuv tool install claude-atlas\n\n或pipx\npipx install claude-atlas\n\n或pip\npip install claude-atlas\n\n\n升级：uv tool upgrade claude-atlas\n\n开发安装\n\nbash\ngit clone https://github.com/grippado/claude-atlas.git\ncd claude-atlas\nuv sync --all-extras\nuv run claude-atlas --help\n\n\n应用场景与价值\n\n个人开发者\n\n对于长期使用Claude Code的开发者，定期运行claude-atlas check可以快速发现配置漂移问题：\n\n- 清理不再需要的孤立文件\n- 合并功能重复的代理\n- 解决触发词冲突\n\n团队协作\n\n在团队环境中，Claude Atlas可以帮助：\n\n- 标准化代理命名和触发词约定\n- 识别不同成员创建的重复代理\n- 在项目模板中预配置最佳实践\n\nCI/CD集成\n\n通过--format github输出，可以在GitHub Actions等CI平台中集成配置健康检查：\n\nyaml\n- name: Check Claude Code Config\n run: claude-atlas check --format github\n\n\n这可以在代码提交时自动检测配置问题，防止有问题的代理定义进入主分支。\n\n设计哲学与路线图\n\n项目遵循以下设计原则：\n\n- 离线优先：默认离线运行，不依赖外部API\n- MIT开源：完全开源，社区可自由使用和贡献\n- 多语言支持：文档提供英文和巴西葡萄牙语版本\n\n根据路线图，下一个主要版本v0.4.0将引入HTML分类仪表板：图视图变为次要标签页，主视图变为基于卡片的分类仪表板，包含健康评分、并排预览和针对每个问题的操作按钮。\n\n技术启示\n\nClaude Atlas的设计思路对其他AI工具的配置管理具有借鉴意义：\n\n1. 配置即代码：将代理定义视为代码资产，需要版本控制和审计\n2. 静态分析：通过启发式规则在运行前发现问题，而非依赖运行时调试\n3. 可视化优先：交互式HTML报告比纯文本输出更易于理解和决策\n4. 渐进式增强：核心功能离线可用，可选的AI增强功能需要API密钥\n\n对于Claude Code用户而言，这是一个实用的配置治理工具，能够将隐性的配置债务显性化，帮助用户维护一个干净、高效的AI助手环境。