do-architecture-md

Generate an ARCHITECTURE.md codemap documenting a codebase's modules, boundaries, and invariants.

2|Updated May 25, 2026
One-click install
npx skills add https://github.com/edheltzel/Do-Skills --skill do-architecture-md-edheltzel
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: do-architecture-md
Source: https://github.com/edheltzel/Do-Skills/tree/main/skills/core/do-architecture-md
Command: npx skills add https://github.com/edheltzel/Do-Skills --skill do-architecture-md-edheltzel

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? New contributors struggle to figure out where to make changes in an unfamiliar codebase, and existing documentation often goes stale or dives into implementation details. This Skill produces a concise, stable ARCHITECTURE.md that gives readers a mental map of the project. ## Core Features & Use Cases - Structured Exploration Workflow: Guides the AI through reading manifests, directory trees, and entry points before writing anything. - Codemap Template: Produces per-module sections with Boundary and Invariant callouts, a bird's eye view, and cross-cutting concerns like error handling and testing. - Quality Checklist and Example: Enforces matklad's principles (name don't link, mark absences, stay under ~300 lines) with a complete reference example for a TypeScript project. - Use Case: When onboarding engineers to a growing service, ask the AI to document the architecture and receive a maintainable ARCHITECTURE.md that answers "where is the thing that does X?" ## Quick Start Ask the AI to write an ARCHITECTURE.md for this repository following matklad's principles.

Frequently Asked Questions about do-architecture-md

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an ARCHITECTURE.md for my codebase?▼

Start with a one-paragraph summary of the problem the project solves, add a bird's eye view of data flow, then write a codemap with one short section per top-level module. Mark API boundaries and invariants explicitly, and finish with cross-cutting concerns like error handling and testing.

What should an architecture document include?▼

Include module purposes in 1-3 sentences, names of important types for symbol search, API boundaries between layers, and architectural invariants including things deliberately absent. Omit implementation details, file links, setup instructions, and anything that changes with routine pull requests.

How long should an ARCHITECTURE.md file be?▼

Keep it under roughly 300 lines so it stays readable and maintainable. Only describe things unlikely to change frequently, and revisit the document a couple of times per year rather than synchronizing it with code.

What is the difference between ARCHITECTURE.md and README?▼

README covers setup, installation, and usage for people who want to run the project. ARCHITECTURE.md explains the internal structure, module boundaries, and invariants for people who need to modify the code.

When should I not write detailed architecture documentation?▼

Avoid documenting implementation details of individual modules, exhaustive API references, or anything that changes with routine PRs, since these go stale quickly. Inline comments and generated API docs like rustdoc or typedoc cover those cases better.