Architecture Review

Name: Architecture Review
Author: oimiragieo

oimiragieo/agent-studio

83 installs
36 repo stars
Updated July 14, 2026
oimiragieo/agent-studio

Helps with ai & agent building tasks.

About

architecture-review is a Claude Code skill for ai & agent building. It helps solo builders move faster with AI-assisted development.

architecture-review
AI & Agent Building
AI-coding skill

Architecture Review by the numbers

83 all-time installs (skills.sh)
+1 installs in the week ending Aug 4, 2026 (Skillselion tracking)
Ranked #5,144 of 16,546 AI & Agent Building skills by installs in the Skillselion catalog
Data as of Aug 4, 2026 (Skillselion catalog sync)

npx skills add https://github.com/oimiragieo/agent-studio --skill architecture-review

Add your badge

Show developers this skill is listed on Skillselion. Paste this into your README.

[![Listed on Skillselion](https://skillselion.com/badge/skills/oimiragieo/agent-studio/architecture-review.svg)](https://skillselion.com/skills/oimiragieo/agent-studio/architecture-review)

Installs	83
repo stars	★ 36
Last updated	July 14, 2026
Repository	oimiragieo/agent-studio ↗

What it does

Helps with ai & agent building tasks.

Files

SKILL.mdMarkdownGitHub ↗

Architecture Review Skill

<identity> Architecture Review Skill - Evaluates system designs against best practices, identifies anti-patterns, and ensures architectural decisions align with non-functional requirements (scalability, maintainability, security, performance). </identity>

Reviewing system architecture designs
Identifying anti-patterns and architectural smells
Validating against SOLID, DRY, YAGNI principles
Assessing non-functional requirements
Recommending architectural improvements

</capabilities>

Step 1: Gather Architecture Context

Understand the current architecture by:

1. Read project structure: Use Glob to map directory structure 2. Identify key components: Find entry points, services, data layers 3. Review dependencies: Check package.json, imports, module graph 4. Understand data flow: Trace requests through the system

Step 2: Evaluate Design Principles

Check adherence to fundamental principles:

SOLID Principles:

Single Responsibility: Does each class/module have one reason to change?
Open/Closed: Can behavior be extended without modification?
Liskov Substitution: Are subtypes substitutable for base types?
Interface Segregation: Are interfaces focused and minimal?
Dependency Inversion: Do high-level modules depend on abstractions?

Other Principles:

DRY: Is logic duplicated unnecessarily?
YAGNI: Are there unused or speculative features?
Separation of Concerns: Are responsibilities properly divided?

Step 3: Check for Anti-Patterns

Identify common anti-patterns:

God Class/Module: Classes doing too much
Spaghetti Code: Tangled, hard-to-follow logic
Circular Dependencies: Modules that reference each other
Feature Envy: Classes that use other classes' data excessively
Shotgun Surgery: Changes that require touching many files
Leaky Abstractions: Implementation details exposed to consumers

Step 4: Assess Non-Functional Requirements

Evaluate against NFRs:

Scalability: Can the system handle increased load?
Maintainability: How easy is it to modify and extend?
Testability: Can components be tested in isolation?
Security: Are there potential vulnerabilities?
Performance: Are there obvious bottlenecks?
Observability: Can the system be monitored effectively?

Step 5: Generate Review Report

Create a structured report with:

1. Summary: Overall assessment and key findings 2. Strengths: What the architecture does well 3. Concerns: Issues requiring attention (prioritized) 4. Recommendations: Specific improvements with rationale 5. Trade-offs: Acknowledge valid design trade-offs

</execution_process>

<best_practices>

1. Be Constructive: Focus on improvements, not criticism 2. Prioritize Issues: Not all problems are equally important 3. Consider Context: Understand constraints and trade-offs 4. Suggest Alternatives: Don't just identify problems 5. Reference Patterns: Cite established patterns when relevant

</best_practices> </instructions>

<examples> <usage_example> Example Review Request:

Review the architecture of src/services/ for scalability and maintainability

Example Response Structure:

## Architecture Review: src/services/

### Summary

The service layer follows a reasonable structure but has some coupling issues...

### Strengths

- Clear separation between API handlers and business logic
- Good use of dependency injection

### Concerns

1. **High Priority**: UserService has 15 methods (God Class)
2. **Medium Priority**: Circular dependency between OrderService and InventoryService
3. **Low Priority**: Some magic numbers in validation logic

### Recommendations

1. Split UserService into UserAuthService and UserProfileService
2. Introduce EventBus to decouple Order and Inventory
3. Extract validation constants to configuration

</usage_example> </examples>

Iron Laws

1. ALWAYS review architecture before COMPLEX or EPIC implementation starts — architectural problems discovered after implementation cost 10-100x more to fix; review in the design phase. 2. NEVER approve an architecture with undocumented single points of failure — every SPOF must be explicitly identified and have a documented mitigation plan. 3. ALWAYS evaluate against non-functional requirements — performance, security, scalability, maintainability, and observability are non-optional; functional correctness without NFR compliance is incomplete. 4. NEVER treat architectural trade-offs as implicit — every trade-off must be explicitly documented with rationale; hidden trade-offs become future surprises and unowned technical debt. 5. ALWAYS check for circular dependencies before approving a design — circular module dependencies make testing, refactoring, and deployment order unpredictable and progressively harder to resolve.

Anti-Patterns

Anti-Pattern	Why It Fails	Correct Approach
No NFR evaluation	Design may pass functional tests but fail at scale or under attack	Always evaluate performance, security, scalability, observability
Reviewing only the happy path	Systems fail at error boundaries, not in the happy path	Review failure modes, retry behavior, and circuit breakers
Approving without trade-off documentation	Hidden trade-offs become future surprises	Explicitly document all trade-offs with rationale
Single point of failure left undocumented	System has silent fragility that surfaces under load	Map all SPOFs; require mitigation plans for each
Checking SOLID without anti-pattern catalog	Principle adherence doesn't guarantee absence of anti-patterns	Check both principles AND concrete anti-patterns (God Class, Shotgun Surgery, etc.)
Architecture review after implementation starts	Too late to fix structural issues without major rework	Review in design phase, before any code is written

Rules

Always provide constructive feedback with actionable recommendations
Prioritize issues by impact and effort to fix
Consider existing constraints and trade-offs

Related Workflow

This skill has a corresponding workflow for complex multi-agent scenarios:

Workflow: .claude/workflows/architecture-review-skill-workflow.md
When to use workflow: For comprehensive audits or multi-phase analysis requiring coordination between multiple agents (developer, architect, security-architect, code-reviewer)
When to use skill directly: For quick reviews or single-agent execution

Memory Protocol (MANDATORY)

Before starting:

cat .claude/context/memory/learnings.md

After completing:

New pattern -> .claude/context/memory/learnings.md
Issue found -> .claude/context/memory/issues.md
Decision made -> .claude/context/memory/decisions.md

ASSUME INTERRUPTION: Your context may reset. If it's not in memory, it didn't happen.

'use strict';
/**
 * Post-execute hook for architecture-review
 * Auto-generated by enterprise-bundle-scaffolder
 *
 * Records metrics after skill execution.
 */

function postExecute(_context) {
  // Record execution metrics
  return { ok: true, skill: 'architecture-review' };
}

module.exports = { postExecute };

'use strict';
/**
 * Pre-execute hook for architecture-review
 * Auto-generated by enterprise-bundle-scaffolder
 *
 * Validates inputs before skill execution.
 */

function preExecute(context) {
  // Validate skill invocation context
  if (!context || typeof context !== 'object') {
    return { allow: true, message: 'architecture-review: no context to validate' };
  }
  return { allow: true };
}

module.exports = { preExecute };

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "architecture-reviewInput",
  "description": "Input schema for Architecture review and design validation. Evaluates system designs against best practices, identifies anti-patterns, and ensures architectural decisions align with non-functional requirements.",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "target": {
      "type": "string",
      "description": "Target file or path for the skill to operate on"
    },
    "options": {
      "type": "object",
      "description": "Additional options for skill execution",
      "additionalProperties": true
    }
  }
}

{
  "$schema": "http://json-schema.org/draft-07/schema#",
  "title": "architecture-reviewOutput",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "ok": {
      "type": "boolean"
    },
    "summary": {
      "type": "string"
    }
  }
}

#!/usr/bin/env node
'use strict';
/**
 * architecture-review - Enterprise Skill Script
 * Auto-generated by enterprise-bundle-scaffolder
 */

const fs = require('fs');
const path = require('path');

// Parse arguments
const args = process.argv.slice(2);
const options = {};
for (let i = 0; i < args.length; i++) {
  if (args[i].startsWith('--')) {
    const key = args[i].slice(2);
    const value = args[i + 1] && !args[i + 1].startsWith('--') ? args[++i] : true;
    options[key] = value;
  }
}

if (options.help) {
  console.log(`
architecture-review - Enterprise Skill

Usage:
  node main.cjs --check <file>    Check a file against guidelines
  node main.cjs --list            List all guidelines
  node main.cjs --help            Show this help

Description:
  Architecture review and design validation. Evaluates system designs against best practices, identifies anti-patterns, and ensures architectural decisions align with non-functional requirements.
`);
  process.exit(0);
}

if (options.list) {
  console.log('Guidelines for architecture-review:');
  console.log('See SKILL.md for full guidelines');
  process.exit(0);
}

console.log('architecture-review skill loaded. Use with Claude for code review.');