# Architecture Docs

> Write architecture documentation and ADRs for software systems, repos, libraries, and workflow bundles. Use when Codex is asked to document system structure, module boundaries, decisions, tradeoffs, dependencies, diagrams, or architecture decision records.

- Skill: `gabrielmoreira/architecture-docs` (Agent Skill, multi-file: 3 files)
- Install (CLI): `npx skillmds@latest add gabrielmoreira/architecture-docs`
- Raw SKILL.md: https://api.skillmd.com/api/skills/gabrielmoreira/architecture-docs/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Docs & Writing
- License: MIT
- Author: gabrielmoreira (https://skillmd.com/u/gabrielmoreira)
- Updated: 2026-09-09
- Page: https://skillmd.com/skills/gabrielmoreira/architecture-docs

---


# Architecture Docs

## Core Workflow

1. Identify the audience, system boundary, source of truth, and decision the doc
   supports.
2. Read the relevant code, configs, diagrams, existing docs, and tests before
   describing architecture.
3. Document structure, responsibilities, data flow, integration points,
   dependencies, constraints, and operational assumptions.
4. For decisions, capture context, options considered, tradeoffs, decision,
   consequences, and review triggers.
5. Separate current architecture from planned architecture.
6. Include validation notes and open questions.

## Safety Rules

- Do not invent architecture, dependencies, guarantees, or operational behavior.
- Do not expose sensitive infrastructure, secrets, private endpoints, or threat
  details in public docs.
- Mark inferred architecture clearly when source evidence is incomplete.

## Deliverable Shape

For architecture docs, provide:

- Scope and audience
- System overview
- Components and responsibilities
- Data or control flow
- Key decisions and tradeoffs
- Constraints and risks
- Validation notes
- Open questions

## References

- Read `references/architecture-docs-checklist.md` when writing architecture
  docs or ADRs.