home / skills / vadimcomanescu / codex-skills / senior-architect

senior-architect skill

safe

/skills/.curated/platform/senior-architect

This skill helps you design and document scalable architectures with ADRs, diagrams, and clear interfaces to inform decisions and guide implementation.

npx playbooks add skill vadimcomanescu/codex-skills --skill senior-architect

Review the files below or copy the command above to add this skill to your agents.

Files (11)

SKILL.md

2.4 KB

---
name: senior-architect
description: "Senior software architecture workflows and tooling for system design, scalability and reliability planning, API/data modeling, trade-off analysis, ADR writing, and producing clear architecture diagrams (Mermaid). Use when you need to define or revise architecture for a feature/system, choose technologies, document decisions, or review an existing codebase’s architecture."
---

# Senior Architect

Design and document architectures that are clear, defensible, and shippable.

## Quick Start
1) Clarify constraints:
   - Primary user journey + success metrics
   - Non-functional requirements (latency, throughput, availability, cost, compliance)
   - Team constraints (skills, timelines, operational maturity)
2) Produce outputs (in this order):
   - **Context**: system boundary + external dependencies
   - **Containers**: major runtime components and responsibilities
   - **Interfaces**: APIs/events/contracts + data ownership
   - **Risks**: failure modes + mitigations + open questions
   - **Decisions**: ADRs with explicit trade-offs

## Use the bundled tools (optional, but recommended)

From your project root, run the scripts from the installed skill directory (default install location: `~/.codex/skills/senior-architect/`).

Bootstrap a documentation skeleton (ADR + architecture doc templates):
```bash
python ~/.codex/skills/senior-architect/scripts/project_architect.py . --out docs/architecture
```

Summarize dependencies and detected stack signals (Node/Python/Go/Rust, Next.js, Postgres, etc.):
```bash
python ~/.codex/skills/senior-architect/scripts/dependency_analyzer.py . --json --output /tmp/deps.json
```

Generate a starter Mermaid diagram based on detected components:
```bash
python ~/.codex/skills/senior-architect/scripts/architecture_diagram_generator.py . --out docs/architecture/diagram.mmd
```

## References (load only when needed)
- Architecture patterns and when to use them: `references/architecture-patterns.md`
- End-to-end system design workflow + checklists: `references/system-design-workflow.md`
- Tech decision matrixes (DB, APIs, queues, caching, observability): `references/tech-decision-guide.md`

## Deliverables (what “done” looks like)
- `docs/architecture/ARCHITECTURE.md` with clear boundaries, contracts, data ownership, and scaling assumptions
- At least one ADR under `docs/architecture/adr/` for the most consequential decision
- A Mermaid diagram (`.mmd`) that matches the written architecture

Overview

This skill provides senior-level software architecture workflows and tooling to design, document, and defend scalable, reliable systems. It focuses on translating requirements and constraints into clear system boundaries, runtime containers, APIs, risk analyses, and actionable architectural decisions. The outputs are shippable artifacts: an architecture doc, ADRs, and a diagram.

How this skill works

The skill inspects project code and dependency signals to infer components, frameworks, and service boundaries, then generates a documentation skeleton and starter diagrams. It guides you through clarifying constraints, producing context/containers/interfaces/risks, and formalizing trade-offs as ADRs. Optional scripts can bootstrap docs, analyze dependencies, and produce a Mermaid diagram from detected components.

When to use it

Defining or revising architecture for a new feature or system
Choosing databases, APIs, queues, caching, or observability stacks
Preparing ADRs for high-impact technical decisions
Reviewing an existing codebase to extract architecture and risks
Planning scalability, availability, and operational runbooks

Best practices

Start by capturing the primary user journey and measurable success metrics
List non-functional requirements (latency, throughput, availability, cost, compliance) up front
Document system boundary and external dependencies before diving into components
Model containers and interfaces with explicit data ownership and contracts
Write ADRs that state options, trade-offs, chosen approach, and migration plan
Include failure modes, mitigations, and open questions as part of the architecture deliverable

Example use cases

Bootstrap an architecture doc and ADRs for a new microservice handling payments
Analyze a monorepo to surface backend/frontend runtimes and produce a starting Mermaid diagram
Compare DB/queue/cache options with a tech decision matrix and capture the result in an ADR
Produce a scalability plan: assumptions, bottlenecks, and mitigation path for a high-throughput API
Review an acquired codebase to produce a concise architecture summary and risk register

FAQ

What artifacts will I get from using this skill?

You get an ARCHITECTURE.md with boundaries and contracts, at least one ADR for a key decision, and a Mermaid diagram that reflects the written architecture.

How do I capture non-functional constraints effectively?

Quantify targets (e.g., p95 latency, RPS, uptime) and list team/operational constraints; use these as acceptance criteria for architectural choices.