senior-architect
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.
Best use case
senior-architect is best used when you need a repeatable AI agent workflow instead of a one-off prompt.
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.
Teams using senior-architect should expect a more consistent output, faster repeated execution, less prompt rewriting.
When to use this skill
- You want a reusable workflow that can be run more than once with consistent structure.
When not to use this skill
- You only need a quick one-off answer and do not need a reusable workflow.
- You cannot install or maintain the underlying files, dependencies, or repository context.
Installation
Claude Code / Cursor / Codex
Manual Installation
- Download SKILL.md from GitHub
- Place it in
.claude/skills/senior-architect/SKILL.mdinside your project - Restart your AI agent — it will auto-discover the skill
How senior-architect Compares
| Feature / Agent | senior-architect | Standard Approach |
|---|---|---|
| Platform Support | Not specified | Limited / Varies |
| Context Awareness | High | Baseline |
| Installation Complexity | Unknown | N/A |
Frequently Asked Questions
What does this skill do?
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.
Where can I find the source code?
You can find the source code on GitHub using the link provided at the top of the page.
SKILL.md Source
# 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
Related Skills
senior-secops
Security operations workflow for vulnerability triage, incident response, detection/alerting improvements, and post-incident hardening. Use when responding to security alerts, reviewing logs for suspicious activity, building incident playbooks, or running quick log summaries during triage.
senior-qa
QA workflow for building test strategies and validating releases: risk-based testing, test pyramid decisions, E2E/integration/unit coverage, exploratory testing, and regression planning. Use when creating test plans, reviewing test coverage, triaging flaky tests, or preparing release sign-off criteria.
senior-prompt-engineer
Prompt engineering workflow for building reliable assistants and agents: task decomposition, instruction hierarchy, tool-use patterns, safety constraints, and evaluation design. Use when writing or refactoring system prompts, creating structured prompts, building prompt test suites, or debugging regressions in LLM behavior.
senior-devops
DevOps workflow for CI/CD, infrastructure, observability, reliability, and safe deployments. Use when designing deployment pipelines, reviewing infra changes, improving operational readiness (alerts/runbooks), or auditing a repo’s production-readiness signals.
senior-backend
Backend engineering workflows for designing and implementing robust APIs and services: data modeling, authN/authZ, error handling, performance, migrations, observability, and operational safety. Use when building or reviewing backend code, defining API contracts, planning DB changes, or writing backend design docs.
information-architect
World-class information architecture workflows for product and design teams: define navigation, taxonomy, labeling, content models, and page hierarchy so complex products feel obvious. Use when designing or redesigning an app/website structure, menus, docs/knowledge base IA, onboarding flows, search/filtering, permissions-based navigation, or when turning a messy feature set into a coherent system.
skill-installer
Install Codex skills into $CODEX_HOME/skills from a curated list or a GitHub repo path. Use when a user asks to list installable skills, install a curated skill, or install a skill from another repo (including private repos).
skill-creator
Guide for creating effective skills. This skill should be used when users want to create a new skill (or update an existing skill) that extends Codex's capabilities with specialized knowledge, workflows, or tool integrations.
jwebmp-webawesome
WebAwesome icon integration for JWebMP — modern, open-source icon library. Provides 1,500+ icons with solid/regular styles, sizing, rotation, animation, and CSS utilities. Drop-in FontAwesome alternative with fresh designs. Use when working with WebAwesome icons, modern icon designs, or as FontAwesome alternative in JWebMP applications.
jwebmp-webawesome-pro
WebAwesome Pro integration for JWebMP with premium icons and features. Extends jwebmp-webawesome with additional styles, premium icons, and advanced features. Use when working with WebAwesome Pro icons or premium WebAwesome features in JWebMP applications.
jwebmp-weather-icons
Weather Icons font library for JWebMP providing weather icon fonts. Use when displaying weather-related icons.
jwebmp-waypoints
Waypoints jQuery plugin for JWebMP triggering functions when elements enter the viewport. Use when implementing scroll-based interactions and animations.