How It Works
erode uses a multi-stage AI pipeline to analyze pull requests for architecture drift. Cheaper, faster models handle extraction and routing, while stronger models handle the analysis.
File filtering
Section titled “File filtering”Before any AI stage runs, erode filters the PR diff to remove files that are irrelevant to architecture analysis. Tests, documentation, lock files, build config, CI config, and build output are all stripped out automatically. This reduces noise and saves API usage.
The built-in skip patterns cover:
- Tests —
*.test.ts,*.spec.js,__tests__/, etc. - Documentation —
*.md,docs/,README,CHANGELOG - Config & tooling —
.vscode/,.prettierrc,tsconfig.json,vite.config.* - Lock files —
package-lock.json,yarn.lock,pnpm-lock.yaml - Build output —
dist/,build/,.next/,coverage/ - CI/CD —
.github/,.gitlab-ci.yml,.circleci/
To analyze all files regardless of these patterns, set skip-file-filtering: 'true' in the GitHub Action or pass --skip-file-filtering on the CLI.
Stage 1 — Resolve
Section titled “Stage 1 — Resolve”When a repository maps to multiple components in the architecture model, erode uses AI to determine which component is most relevant to the pull request. This stage uses a cheaper model (Haiku for Anthropic, Flash for Gemini) to keep costs low.
This stage is skipped entirely when the repository maps to a single component.
Stage 2 — Scan
Section titled “Stage 2 — Scan”The PR diff is fed to a fast model that extracts dependency changes and new integrations. The output is a structured list of added, removed, or modified dependencies found in the code changes.
This keeps the analysis stage focused on dependency changes rather than the full diff.
Stage 3 — Analyze
Section titled “Stage 3 — Analyze”A stronger model (Sonnet for Anthropic, Flash for Gemini) compares the extracted dependency changes against the declared architecture model and produces violation findings, each with:
- A severity level (high, medium, or low)
- A description of the drift
- Suggestions for resolving the violation
Stage 4 — Generate (optional)
Section titled “Stage 4 — Generate (optional)”When enabled, erode produces architecture model updates that bring the model back in sync with reality. This can be used to open a follow-up pull request that updates the model.
Prompt templates
Section titled “Prompt templates”Each stage’s behavior is defined by a markdown prompt template with {{variable}} substitution. These templates are maintained alongside the source code and are assembled at runtime by the prompt builder.
For a detailed stage-by-stage reference including inputs, outputs, and error handling, see Analysis Pipeline.