architecture-decision

Files (1)

• SKILL.md

SKILL.md (first lines)

# SKILL: architecture-decision
## For: Agent 04 — ARCHITECT
## Version: 1.0.0

## Core principle
The stack follows the problem. Every technical decision is justified in terms of the problem it solves, not familiarity or preference.

## Process
STEP 1 — Understand the problem: product type, user profile, data volume, offline/sync requirements, OS/hardware constraints, available tools (Codex, Claude Code). Do not evaluate technologies until this is complete.
STEP 2 — Evaluate 2-3 options per layer with pros/cons in context, not in the abstract.
STEP 3 — Check viability: can Codex/Claude Code implement it well? Enough documentation? Manageable dependencies? If not → document it explicitly.
STEP 4 — Separate decisions you can make from decisions that need PO approval.
STEP 5 — Document what was discarded and why — as important as what was chosen.

## Criteria to evaluate a technology
✓ Solves the problem better than the alternatives
✓ Actively maintained, with enough community and documentation
✓ Implementable with the available tools
✓ Scales with expected growth

Warnings: last update over a year ago, sparse docs, dependencies with vulnerabilities, inactive community.

## Architectural maintainability
✓ Each module with a clear responsibility
✓ Explicit, minimal dependencies between modules
✓ No critical logic in monolithic files
✓ An AI can modify a module understanding only that module

## Tooling context
Claude Chat: does not run code, produces decisions and documentation.
Claude Code/Codex: best with modular, well-documented files, struggles with long files (+2000 lines), needs explicit context in AGENTS.md.

## ARCHITECTURE.md structure
Stack evaluation → System structure → Folder structure → Technical decisions → Decisions pending approval → Risks → Environment limits

## Mistakes to avoid
× Choosing the known stack without evaluating it against the problem
× Mixing responsibilities in one module
× Not documenting what was discarded
× Ignoring expected growth

From 6SNT-RADIO/6SNT-Studio, MIT.