PashaSchool/faultlines

## 问题所在 每位工程师在面对新代码库时都会发现同样的情况： 你的 **issue 跟踪器**并不了解实情——里面满是一厢情愿的工单。 **静态分析**只看得到导入，却看不到意图。 而你的 **AI 智能体**只是简单地 `grep` 15 个文件，并在不断猜测中耗尽你的上下文窗口。 答案其实一直就在你的 **git 历史记录**中。Faultlines 帮你读取它们。 ## Faultlines 能做什么 ``` $ faultlines ./my-app ✓ 472 commits analysed · 1,284 files mapped FEATURE HEALTH COVERAGE HOTSPOTS FLOWS ───────────────────────────────────────────────────────── Billing & Subscriptions 62 48% 3 7 Authentication 88 91% 0 4 Document E-Sign 41 ⚠ 22% 5 9 Team & Permissions 79 66% 1 5 … → Highest blast radius: src/payments/charge.ts (touches 4 features) → Riskiest flow: e-sign/finalize (low coverage · 5 recent bug-fixes) ``` **双层特性映射图**： - **开发者特性** —— 基于代码，也就是你的工程师实际工作的单元。 - **产品特性** —— 这些单元最终汇总构成的面向客户的能力。 ……每一个都被拆解为**流程**（真实的用户旅程），经过评分，将责任归属精确到**函数和代码行范围**，并提供给人类*以及* AI 智能体。 ## 功能 - **特性与流程检测** —— 源自 git 历史 + 代码结构，适用于**任何技术栈**（Next.js、Rails、Django、FastAPI、Express、Spring、Laravel、Phoenix 等）。 - **缺陷热点与健康评分** —— 在系统告警之前，提前发现正在腐化的代码。 - **行为测试覆盖率** —— 针对*每个用户流程*的覆盖率，即使没有 `lcov` 也能从历史记录中推断。 - **变更影响 / 爆炸半径** —— “如果我修改了这些文件，这里是会受影响的内容，以及需要添加的审查者。” - **符号级归属** —— 针对每个流程的函数、类和**代码行范围**，而不仅仅是文件列表。 - **所有权与巴士因子** —— 谁在维护每个特性，以及知识集中在哪些极其危险的地方。 - **面向 AI 智能体的 MCP 服务器** —— 13 个具有类型的工具，供你的编程智能体直接调用，而无需进行 grep。 - **运行时叠加层** —— 将 **Sentry** 错误和 **PostHog** 使用情况映射到特性上（查看哪些特性实际上发生了故障并被使用）。 - **本地优先与隐私保护** —— 在你的机器上运行；你的源代码根本不需要离开本地。 ## 快速开始 ``` pip install faultlines # 扫描 repo。直接使用 `faultlines ` 运行扫描 pipeline —— # flows 和 symbol 级别的归属默认包含在内。 faultlines /path/to/your/repo ``` Faultlines 是**确定性优先**的：特性/流程的结构来自于你的代码和 git 历史，不需要 LLM。设置 `ANTHROPIC_API_KEY` 后，一个 **Haiku** 处理过程会自动添加人类可读的名称并进行流程检测——无需额外标志。使用 `--model haiku|sonnet|opus`（默认值：`haiku`）选择模型： ``` export ANTHROPIC_API_KEY=sk-ant-... faultlines /path/to/your/repo --model sonnet ``` 这会将带有版本信息的**特性映射 JSON** 写入 `~/.faultline/`。你可以探索它、在不同运行之间进行对比、将其交付到 CI，或者直接将其交给你的 AI 智能体（见下文）。 ## 为 AI 编程智能体而生 这就是切入点。安装配套的 MCP 服务器，你的智能体就不会再盲目猜测了： ``` # 一次性运行，无需安装（推荐） uvx faultlines-mcp # 或者安装它 pip install faultlines-mcp ``` ``` // ~/.cursor/mcp.json (or: claude mcp add faultlines -- faultlines-mcp) { "mcpServers": { "faultlines": { "command": "faultlines-mcp" } } } ``` 现在 Cursor / Claude Code / Cline / Windsurf 可以调用 **13 个工具**： | | 工具 | |---|---| | **发现** | `list_features` · `find_feature` · `get_repo_summary` | | **文件与符号** | `get_feature_files` · `get_flow_files` · `find_symbols_in_flow` · `find_symbols_for_feature` | | **风险与影响** | `get_hotspots` · `get_feature_owners` · `analyze_change_impact` · `get_regression_risk` | | **运行时** | `get_feature_errors` (Sentry) · `get_feature_pageviews` (PostHog) | ## 指标 —— 以及它们为何重要 | 指标 | 它告诉了你什么 | 为什么值得关注 | |---|---|---| | **健康评分** | 代码变动、缺陷修复、覆盖率和所有权的综合体现 | 用一个数字来评估接下来该重构什么 | | **缺陷修复率** | 修复缺陷的提交所占的比例 | 高 = 脆弱、容易出缺陷的代码 | | **代码变动** | 某个特性被修改的频率 | 热点检测；不稳定性的信号 | | **影响评分** | 结构性爆炸半径 − 覆盖率 | 此处的更改实际上会危及哪些部分 | | **覆盖率** | **每个流程**的行为测试覆盖率 | 找出未经测试的用户旅程，而不仅仅是未测试的代码行 | | **所有权 / 巴士因子** | 谁掌握了知识 | 在核心人员离职前发现单点故障 | ## 工作原理 ``` git history ─┐ ├─▶ deterministic extractors ─┐ code/config ─┘ (routes · MVC · schema · │ package · stack patterns) ├─▶ feature & flow map │ + metrics + symbols Haiku pass · naming + flows (key set) ─┘ │ ▼ feature-map JSON ──▶ CLI · CI · dashboard · MCP ``` **确定性优先。** 其结构来源于你的路由约定、配置、schema 以及 git 的共同变更模式——不需要 LLM。当设置了 `ANTHROPIC_API_KEY` 时，一个 Anthropic（默认为 Haiku，使用 `--model sonnet|opus`）处理过程会自动添加人类可读的名称并进行流程检测。输出的是一个单一且带有版本号的 JSON——这是每个使用者都会读取的稳定契约。 ## 集成 - **GitHub** —— 在 diff 涉及的确切特性上提供 PR 评论，包含风险、覆盖率缺口和运行时信号。 - **Sentry** —— 将生产环境错误映射到特性。 - **PostHog** —— 每个特性的实际使用情况和流量。 - **Slack** —— 每周汇总最高风险、覆盖率缺口和热点。 ## 为什么不直接用…… - **…grep / 阅读文件？** 会消耗上下文，并且会遗漏静态分析无法看到的跨边界、运行时和历史的耦合关系。 - **…SonarQube / linter？** 对于代码行级别的问题很棒；但对*特性*、*流程*和*爆炸半径*视而不见。 - **…你的 issue 跟踪器？** 描述的是意图，而非现实。Faultlines 的基础是代码和历史记录真正表达的内容。 Faultlines 是唯一能够将**结构 + git 历史 + 运行时**结合到一个映射图中——并将其提供给你的 AI 智能体的层。 ## 路线图 - [x] 在任何技术栈上实现双层特性/流程映射 - [x] 行为测试覆盖率与健康评分 - [x] 符号级归属 - [x] MCP 服务器（13 个工具）—— 本地 · 托管 · VPC - [x] Sentry + PostHog 运行时叠加层 - [x] 每次提交时进行增量、亚秒级的重新扫描 - [x] 支持更多智能体与 IDE 的原生插件 ## 许可证 MIT —— 详见 [LICENSE](LICENSE)。

如果 Faultlines 帮助你（或你的智能体）更快地了解了某个代码库，请**[为本仓库点 Star](https://github.com/PashaSchool/faultlines)**。 专为工程师及与他们并肩工作的 AI 智能体而打造 · [faultlines.dev](https://faultlines.dev)

标签：AI编程助手, Git分析, MCP, Python, SOC Prime, 代码库智能, 代码质量分析, 开发工具, 无后门, 逆向工具