Przejdź do treści
Biblioteka skilli
Programowanie · Planowanie

map-architecture

/map-architecture

Tworzy mapę architektury repozytorium, skanując istniejący kod albo prowadząc krótką sesję doboru stosu, struktury folderów i konwencji w pustym repozytorium.

Repozytorium
sdlc ↗
Licencja
MIT
Ostatnia zmiana repozytorium
25.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
3
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 25.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

MIT, otwarta: można używać i zmieniać, z zachowaniem informacji o autorze.

Co robi i kiedy

Tworzy mapę architektury repozytorium, skanując istniejący kod albo prowadząc krótką sesję doboru stosu, struktury folderów i konwencji w pustym repozytorium.

Wyzwalacze z opisu

survey the codebasemap the architectureset up a new projectbootstrap the foundation
Oryginalny opis (EN)

Use to establish the repo's architecture map the rest of the pipeline reads. Two modes: on an EXISTING codebase it scans once and persists what's there; on an EMPTY/greenfield repo it runs a short, level-adaptive foundation session — picks the stack / folder structure / data approach / conventions WITH you (defaults-heavy), fixes them as the foundation + foundational ADRs, and emits a scaffold tasks.json that implement-tasks materializes into a real skeleton. Triggers on "survey the codebase", "map the architecture", "set up a new project", "bootstrap the foundation", "/sdlc:map-architecture",

Jak działa

  1. Як це читати (короткий вступ)
  2. Owner
  3. Inputs
  4. Protocol
  5. Definition of Done
  6. Anti-patterns
  7. References & template
Sekcje z nagłówków SKILL.md, w oryginale · 74 linii, 1 316 słów
Podgląd SKILL.md
---
name: map-architecture
model: inherit
effort: medium
agents: [explorer]
description: >-
  Use to establish the repo's architecture map the rest of the pipeline reads. Two modes: on an
  EXISTING codebase it scans once and persists what's there; on an EMPTY/greenfield repo it runs a
  short, level-adaptive foundation session — picks the stack / folder structure / data approach /
  conventions WITH you (defaults-heavy), fixes them as the foundation + foundational ADRs, and emits
  a scaffold tasks.json that implement-tasks materializes into a real skeleton. Triggers on "survey
  the codebase", "map the architecture", "set up a new project", "bootstrap the foundation",
  "/sdlc:map-architecture", "вивчи кодову базу", "карта архітектури", "новий проєкт",
  "заклади фундамент". Output: docs/architecture-map.md (+ adr/ + scaffold tasks.json on
  greenfield). Records reflects_commit for staleness; reads, never overwrites, an authored
  architecture doc.
triggers:
  - /sdlc:map-architecture
  - "survey the codebase"
  - "map the architecture"
  - "set up a new project"
  - "bootstrap the foundation"
  - "вивчи кодову базу"
  - "карта архітектури"
  - "новий проєкт"
  - "заклади фундамент"
stage: "00"
---

# Skill: map-architecture (SDLC stage 00 — the pipeline's anchor)

The pipeline's anchor on architecture. It produces `docs/architecture-map.md` — the single source of "what the system is" that `write-prd` (constraints), `architecture-design` (matches against it), `generate-data-model`, and `implement-tasks` all read instead of re-discovering the code. It runs in one of **two modes**, auto-detected:

- **Brownfield** (the repo has source) → scan it once and persist the **current** architecture.
- **Greenfield** (empty / near-empty repo) → run a short, **level-adaptive foundation session**: pick the stack / structure / data approach / conventions *with* the user (defaults-heavy), fix them as the **foundation** + foundational ADRs, and emit a **scaffold `tasks.json`** that `implement-tasks` turns into a real skeleton. Greenfield detail → [`./references/foundation.md`](./references/foundation.md).

Repo-level utility (one map serves every feature). The scan is delegated to the `sdlc:explorer` agent — read-only brownfield scout per [`../_shared/agent-roster.md`](../_shared/agent-roster.md). Question phrasing → [`../_shared/ask-style.md`](../_shared/ask-style.md).

## Як це читати (короткий вступ)

Це Step 0 SDLC-циклу — перший крок перед будь-якою фічою. Він сканує кодову базу **один раз** і зберігає результат у `docs/architecture-map.md`, щоб усі наступні кроки (`write-prd`, `architecture-design`, `implement-tasks`) читали цей файл, а не пересканували репо щоразу. На **brownfield** (є код) — сканує реальний стан. На **greenfield** (порожнє репо) — разом з тобою вибирає стек і конвенції, зберігає їх як фундамент, і генерує scaffold `tasks.json`.

**Словничок термінів:**
- *brownfield* — репо з наявним кодом (є що сканувати).
- *greenfield* — нове/порожнє репо (фундамент встановлюється з нуля).
- *reflects_commit* — git-sha, яка архітектурна карта відображає (для відстеження свіжості).
- *scaffold tasks.json* — набір завдань, який `implement-tasks` матеріалізує у скелет проєкту.
- *§Frontend / UI foundation* — секція карти, яка описує дизайн-систему, компоненти і токени: щоб `architecture-design` / `break-tasks` / `implement-tasks` **перевикористовували**, а не перевинаходили UI.

## Owner

Architect / Tech Lead — they own the architecture (brownfield: confirm it reflects reality; greenfield: decide the foundation).

## Inputs

- (Optional) a path/scope hint (default: repo root).
- (Read, never overwrite) an authored architecture doc if present (`docs/architecture.md`, `ARCHITECTURE.md`, root `CLAUDE.md`, ADRs) — a strong input the map reconciles with, never clobbers.

## Protocol

1. **Detect mode + freshness.** If `docs/architecture-map.md` exists and is fresh (its `reflects_commit` ≈ current HEAD) → «map is fresh (reflects `<commit>`). Reuse or refresh?»; STOP on reuse. Else decide the mode: **brownfield** if the repo has source (modules/packages beyond config), else **greenfield** (empty or only scaffolding like a bare `go.mod` / `package.json`).

### Brownfield path (existing code)

2. **Read authored docs first.** Any hand-maintained architecture doc / root `CLAUDE.md` / ADRs → authoritative input; reconcile with it, never overwrite.
3. **Scan via explorer.** Dispatch the `sdlc:explorer` agent (`subagent_type: "sdlc:explorer"` — `haiku`/`low`, clean-isolated per [`../_shared/agent-roster.md`](../_shared/agent-roster.md)): «Report (a) language + frameworks + versions, (b) top-level module layout + per-module layers, (c) layering / wiring conventions, (d) datastores + access, (e) inter-module comms, (f) cross-cutting conventions (errors, IDs, tests, migrations) with one cited example each, (g) 2–3 representative features as precedents, (h) **if a frontend exists** — the component library / design system, design tokens (colors/spacing/typography), styling approach (Tailwind / CSS-modules / styled-components / …), shared UI primitives, and a representative screen/component as the UI precedent to reuse.» Large repo → fan out per subtree. (Fallback `subagent_type: "Explore"` if `sdlc:explorer` is unavailable.)
4. **Synthesize + stamp + validate + write.** Fill [`./templates/architecture-map.md`](./templates/architecture-map.md) (C4 of what exists, module inventory, cited conventions, datastores, **the Frontend / UI foundation if a frontend exists**, precedent guide, constraints) with real `file:line` anchors. Record `updated_at` + `reflects_commit: <short HEAD>`. **Validate the C4 Mermaid per [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md)** (render-parse with `mmdc` if available, else the structural lint; fix before committing). Write + commit `map-architecture: architecture map (reflects <commit>)`. Then **emit the stage-handoff block** per [`../_shared/handoff.md`](../_shared/handoff.md) — *What I did* + *Review* (`docs/architecture-map.md`) + *Run next* (`/clear`, then `/sdlc:write-prd <slug>`).

### Greenfield path (empty repo) → [`./references/foundation.md`](./references/foundation.md)

G2. **Calibrate to the person.** One opening `AskUserQuestion` to gauge how the user wants to engage — «pick good defaults, I'll confirm» / «walk me through each choice with explanations» / «let me choose each piece, keep it terse». This sets the dialogue's depth + phrasing (junior → defaults + glossed explanations per [`../_shared/ask-style.md`](../_shared/ask-style.md); senior → terser, more control). Not a product brief.
G3. **Intent (short).** 1–3 questions: what the project is + the kind of capabilities it'll have (e.g. «HTTP API» / «CLI» / «web app»). Enough to choose an architecture — deliberately NOT the feature briefing (that's `write-prd`'s job, per feature).
G4. **Pick the foundation, defaults-heavy.** At the calibrated depth, choose: stack (language/framework/datastore), architectural style (e.g. hexagonal modules), folder/module structure, data/persistence approach (migration tool, ID strategy), core conventions (errors, tests, CI). Recommend a coherent default set; the user confirms or adjusts. Choice menus + defaults → [`./references/foundation.md`](./references/foundation.md).
G5. **Fix the foundation.** Write `docs/architecture-map.md` as the **established foundation** (mark `mode: greenfield-bootstrap`; the C4 is the *target* baseline) + spawn **foundational ADRs** in `docs/adr/` for the irreversible picks (stack, module style, persistence). Record `reflects_commit`. **Validate the C4 Mermaid per [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md)** before committing.
G6. **Emit the scaffold + hand off.** Write a scaffold `tasks.json` at `docs/features/_scaffold/tasks/tasks.json` — the same `tasks/tasks.json` location `break-tasks` uses, so `implement-tasks _scaffold` finds it (the skeleton: folder/module structure, a baseline module, the test harness, migration tooling, CI, a `CLAUDE.md`/rules doc) per the contract in [`./references/foundation.md`](./references/foundation.md). Each task's DoD anchors on the **skeleton smoke test** — «the project builds + boots + the empty test suite runs + the migration tool runs». Commit `map-architecture: greenfield foundation + scaffold plan`. Then **emit the stage-handoff block** per [`../_shared/handoff.md`](../_shared/handoff.md) — *What I did* (foundation fixed + the scaffold plan) + *Review* (`docs/architecture-map.md`, `docs/adr/`, `docs/features/_scaffold/tasks/tasks.json`) + *Run next* (`/clear`, then `/sdlc:implement-tasks _scaffold` to materialize the skeleton; the literal slug is `_scaffold`).

## Definition of Done

- `docs/architecture-map.md` exists with `updated_at` + `reflects_commit`; an authored doc (if any) was reconciled, never overwritten.
- **Brownfield:** C4 of what exists + module inventory + cited conventions + precedent guide, real `file:line` anchors (no placeholders).
- **Greenfield:** foundation fixed (stack/structure/data/conventions) at the user's calibrated level + foundational ADRs in `docs/adr/` + a scaffold `tasks.json` at `docs/features/_scaffold/tasks/tasks.json` whose tasks carry the skeleton smoke-test DoD, ready for `implement-tasks`.

## Anti-patterns

- **Re-scanning the repo in every downstream skill** — the point is to scan once; others read the map (drift detection is the only re-read, of real domain files).
- **Overwriting a hand-maintained `docs/architecture.md`** — `map-architecture` writes its own map and reconciles.
- **A map with no `reflects_commit`** — it silently rots; nobody knows it's stale.
- **Greenfield: a full product brief.** The foundation session picks the *architecture*, not the features — the idea/briefing is `write-prd`'s job, per feature. Keep it to intent + foundation choices.
- **Greenfield: ignoring the person's level.** A junior gets defaults + plain-language explanations; a senior gets control + terseness. One calibration question sets this — don't fire a senior-level wall of choices at a first-timer.
- **Placeholders / guessed layout** — cited or `UNKNOWN`; a fictional map is worse than none.
- **Skipping the §Frontend / UI foundation.** If the repo has a frontend, the design system / component library / tokens / closest UI precedent must be captured here — so `architecture-design`, `break-tasks`, and `implement-tasks` compose the existing system instead of reinventing it. Omitting this turns the map into a backend-only document that silently breaks UI reuse downstream.

## References & template

- [`./references/foundation.md`](./references/foundation.md) — greenfield: the calibration question, level-adaptive depth, the stack/structure/convention choice menus + defaults, foundational-ADR list, and the scaffold `tasks.json` contract.
- [`./templates/architecture-map.md`](./templates/architecture-map.md) — output scaffold (same file for current OR foundation; a `mode:` marker distinguishes).
- [`../_shared/agent-roster.md`](../_shared/agent-roster.md) — the `sdlc:explorer` agent contract (`haiku`/`low`, read-only).
- [`../_shared/mermaid-check.md`](../_shared/mermaid-check.md) — validate the C4 Mermaid block after writing it.
- [`../_shared/handoff.md`](../_shared/handoff.md) — the stage-handoff block format (printed as the final output).
- [`../_shared/ask-style.md`](../_shared/ask-style.md) — question phrasing + depth (used in greenfield calibration).
- [`../_shared/surfaces.md`](../_shared/surfaces.md) — §Frontend / UI foundation in the map is the source `architecture-design` / `break-tasks` / `implement-tasks` / `review-feature` read to reuse the existing design system instead of reinventing it.
Pliki w paczce (3)
  • SKILL.md 12 KB
  • references/foundation.md 6 KB
  • templates/architecture-map.md 5 KB

Wersje

W bazie nie ma innych skilli o nazwie map-architecture.

Migawka bazy z 13.11.2026 · wersja paczki 6f3ccee3fae8 (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 100survey
    Tworzy mapę architektury repozytorium: skanuje istniejący kod albo prowadzi sesję fundamentów dla pustego projektu.
  • 90scaffold
    Buduje realny szkielet projektu z planu fundamentu: foldery, punkt wejścia, testy, narzędzia migracji, CI i dokument konwencji.
  • 100architecture-map
    Generuje lub odświeża mapę architektury całego repozytorium: architecture-map.json z nazwanymi przepływami jako kontrakt maszynowy oraz samodzielny podgląd architecture-map.html.
  • 90archwhere
    Utrzymuje mapę architektury w repozytorium i umieszcza każdą zmianę kodu na tej mapie, także w nowych repozytoriach.
  • 100update-codebase-map
    Odświeża istniejącą mapę kodu i architektury w .claude/.codebase-info po zmianach, gdy dokumenty się zdezaktualizowały.
  • 81map-codebase
    Tworzy interaktywną mapę repozytorium z zweryfikowanej struktury, symboli i importów, jako samodzielną stronę HTML.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.