# Architecture Quality Assess

> Assess and score codebase architecture health — layer separation, SOLID compliance, module coupling (FAN-IN/FAN-OUT), circular dependencies, drift from documented patterns. Use whenever the user asks to assess/review/grade architecture quality, wants an architecture score, or asks how healthy the codebase's architecture is. Analysis-only report + refactoring tasks; for docs-vs-code drift use document-hub-analyze.

- Skill: `artsmc-claude-dev-agents/architecture-quality-assess` (Agent Skill, multi-file: 155 files)
- Install (CLI): `npx skillmds@latest add artsmc-claude-dev-agents/architecture-quality-assess`
- Raw SKILL.md: https://api.skillmd.com/api/skills/artsmc-claude-dev-agents/architecture-quality-assess/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- Author: artsmc (https://skillmd.com/u/artsmc-claude-dev-agents)
- Updated: 2026-09-10
- Page: https://skillmd.com/skills/artsmc-claude-dev-agents/architecture-quality-assess

---


# Architecture Quality Assessment

Static-analysis pipeline that scores a codebase's architecture (0-100) and reports violations with file:line detail and fix recommendations. Analysis-only — never edits code. Supports Python and JS/TS projects (Next.js, React, Vue, Express, NestJS, FastAPI, Django, Flask).

## Workflow

1. **Run the assessment**:
   ```bash
   bash ~/.claude/skills/architecture-quality-assess/skill.sh [PROJECT_PATH] [OPTIONS]
   ```
   The project root must contain a manifest (package.json, requirements.txt, or pyproject.toml) or project detection fails.

2. **CLI options** (verified against `scripts/assess.py --help` — trust this table over older docs):

   | Option | Meaning | Default |
   |---|---|---|
   | `project_path` | Directory to analyze | `.` |
   | `--format {markdown,json,tasks,all}` | Report format(s) | `markdown` |
   | `--output`, `-o` | Output file path | `<project>/architecture-assessment.{md,json}` |
   | `--severity {critical,high,medium,low}` | Minimum severity reported | `low` |
   | `--verbose`, `-v` | Detailed progress | off |
   | `--no-cache` | Force full re-parse | caching on |
   | `--list-analyzers` | List analyzers and exit | — |

   Caution: README.md mentions `--incremental`, `--cache`, `--generate-tasks`, and `--config`; those flags do NOT exist in assess.py. Use `--format tasks` for the task list.

3. **Read the report** (`architecture-assessment.md` in the project root): overall score, then violations by severity (critical → low), each with file, line, and recommendation. Exit code is 1 when critical violations exist — usable directly as a CI gate (`--format json --severity critical`).

4. **Optional follow-ups**:
   - `--format tasks` (or `all`) writes `architecture-refactoring-tasks.md`, consumable by `/start-phase-execute` and `/pm-db import`.
   - Drift detection runs automatically when `memory-bank/systemPatterns.md` / `systemArchitecture.md` exist in the project.

## What it analyzes

Seven analyzers: project/framework detection, layer separation (Clean Architecture), SOLID (all 5 principles), design patterns and anti-patterns, coupling metrics + circular dependencies, code organization, and memory-bank drift.

## Workflow verify (diverse-lens false-positive reduction)

`scripts/assess.py`'s pattern-matching can collide with unrelated same-named constructs (e.g. an
Express router's `.delete()` HTTP-verb method matching an "ORM usage" pattern) or produce
dependency-graph artifacts (e.g. a module reported as depending on itself). For a lower-false-
positive report, wrap its output in the diverse-lens verify graph:
`workflows/architecture-quality-assess-verify.js`, invoked via
`Workflow({ scriptPath: '~/.claude/workflows/architecture-quality-assess-verify.js' })` (never by
name — see `docs/graph-orchestration.md` §6). It does not re-analyze anything; it takes assess.py's
own violations as input, one grounding agent per file re-reads the real code, then three
distinct-lens verifiers (correctness / security / reproduces — reinterpreted for architecture: does
the pattern-match hold, does it cross a real security/data boundary, does tracing the actual
code/import path confirm it) each try to REFUTE every violation, defaulting to refuted under
uncertainty. A violation reaches the report only on majority non-refutation (FRS FR-14).

`assess.py <path> --format json` currently errors on a pre-existing bug unrelated to this workflow
(`lib/reporters/json_reporter.py` reads a `SOLIDMetrics` attribute that doesn't exist — already
failing `tests/test_integration.py::test_json_report_generation` in this skill's own baseline
suite). Until that's fixed independently, obtain the violations array by calling the same
orchestrator the CLI uses, bypassing only the broken reporter:

```bash
cd skills/architecture-quality-assess && python3 -c "
import sys, json; sys.path.insert(0, '.')
from pathlib import Path
from scripts.assess import AssessmentOrchestrator
p = Path('<project_path>').resolve()
orch = AssessmentOrchestrator(project_path=p, verbose=False, cache_enabled=False)
result = orch.run()
print(json.dumps([v.to_dict() for v in result.violations]))
"
```

then pass that array as `args.violations` (plus `repo_root` and `project_path`) to the workflow.

**When to use the plain analyzer vs the verify graph:** plain `assess.py` for routine
scans/CI gates where a human triages the report anyway; the verify graph (one grounding agent per
file plus 3 verifier agents per violation, bounded by `args.max_findings`, default 15, per FRS
FR-17) when the violation set feeds an automated gate or a report acted on without re-checking each
line.

Measured on the skill's own fixtures (`tests/fixtures/{django-app,express-api,nextjs-app-router,
python-fastapi}`): the raw analyzer produced exactly 2 violations across all four fixtures (1 per
app that had any), and both were false positives — a self-referential "circular dependency" that
was a dependency-graph artifact, and an "ORM usage" match that was actually Express's
`router.delete()` HTTP-verb method in a fixture with no database layer at all. The verify pass
refuted both, unanimously (3/3 lenses each). Full methodology and numbers:
`~/.claude/job-queue/feature-graph-orchestration/docs/planning/task-updates/task-15-diverse-lens-verify.md`.

## Docs and references (read on demand)

- `README.md` (this dir) — user guide: use cases, score/severity/metric interpretation, `.architecture-assess.json` config basics, skill integrations (memory-bank, pm-db, document-hub), GitHub Actions CI example, troubleshooting, best practices, FAQ.
- `USAGE_GUIDE.md` (this dir) — command walkthroughs and workflow scripts: pre-refactor assessment, CI quality gate, weekly review, self-analysis.
- `references/analysis-details.md` — per-analyzer violation heuristics (SOLID rules, pattern/anti-pattern catalog, coupling thresholds, drift detection) with example output. Read when explaining why something was flagged.
- `references/report-formats.md` — full markdown/JSON report schemas and generated task-list format. Read when parsing JSON output or wiring CI checks.
- `references/operations.md` — optional deps (networkx, tree-sitter), full config-file schema, performance/caching notes, extra troubleshooting/FAQ, changelog. Read for setup or slow analysis.