troskatertroskater/flowdeck-claude/skills/codebase-mapping/SKILL.md

codebase-mapping

Skill0 starsChanged 22 days agoMITView on GitHub

Map architecture, conventions, and file structure into `<fd>/.codebase/`. Use when onboarding or before deep feature work.

In this repository32 other files it gives its agents.
- .claude/CLAUDE.mdCLAUDE.md
- api-designSkill
- arch-constraint-guardSkill
- backend-patternsSkill
- clean-architectureSkill
- context-budgetSkill
- cqrsSkill
- ddd-architectureSkill
- debug-flowSkill
- dependency-auditSkill
- django-patternsSkill
- django-tddSkill
- event-driven-architectureSkill
- fd-codenavSkill
- fd-mapSkill
- frontend-patternSkill
- git-releaseSkill
- git-workflowSkill
- golang-patternsSkill
- hexagonal-architectureSkill
- java-patternsSkill
- layered-architectureSkill
- performance-profilingSkill
- postgres-patternsSkill
- python-patternsSkill
- refactor-guideSkill
- research-firstSkill
- rust-patternsSkill
- saga-architectureSkill
- security-scanSkill
- tdd-workflowSkill
- test-gap-detectorSkill

The file

We split this skill into the rules it gives an agent

10 rules. About 0 are common, 7 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈7
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Distinctive:
Before a major feature that spans multiple modules
line 16
Very specific:
When /fd-task runs its init step for an unmapped project
line 17
Very specific:
When <fd>/.codebase/ is missing or stale
line 18
Very specific:
All outputs go to <fd>/.codebase/:
line 22
Distinctive:
Read in this order:
line 36
Distinctive:
Document each top-level directory's purpose:
line 44
Distinctive:
Do not guess. Read the files to confirm what each directory contains.
line 55
Distinctive:
Write 1-2 examples for each pattern, not a generic description.
line 66
Distinctive:
Only document what you have read — never document by assumption
line 87
Distinctive:
If a file's purpose is unclear, note "purpose unclear — investigate before modifying"
line 88

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

<fd> is this project's FlowDeck directory, the one fd-state path prints (~/.fd-plan/<project>/, or <project>/.fd-plan/ when the storage setting is project).

Codebase Mapping Skill

Produces structured documentation of a codebase that agents can read to answer "how does this project work?" without re-scanning every time.

When to Activate

Starting work on an unfamiliar codebase
Before a major feature that spans multiple modules
When /fd-task runs its init step for an unmapped project
When <fd>/.codebase/ is missing or stale

Output Files

All outputs go to <fd>/.codebase/:

File	Contents
`ARCHITECTURE.md`	System design: layers, modules, data flow
`CONVENTIONS.md`	Naming, style, patterns specific to this project
`DEPENDENCIES.md`	Key external packages and what they do
`INDEX.md`	File-by-file inventory
`ENTRY_POINTS.md`	How the application starts and key entry files

Mapping Sequence

Step 1: Start from the outside

Read in this order:

package.json / pyproject.toml / Cargo.toml — dependencies, scripts, metadata
README.md — stated purpose and architecture
Entry point files (main, index, app, server)
Configuration files (env examples, config schemas)

Step 2: Map the directory structure

Document each top-level directory's purpose:

src/
  api/          — HTTP route handlers
  services/     — Business logic
  models/       — Database schemas and queries
  utils/        — Shared helpers
tests/          — Test files (mirror of src/)
scripts/        — Build and deployment scripts

Do not guess. Read the files to confirm what each directory contains.

Step 3: Document key conventions

Find examples in the code:

How are errors handled? (throw? return Result? error callback?)
How are modules exported? (default export? named exports?)
What is the naming pattern for files? (UserService.ts? user-service.ts?)
Where do interfaces/types live?
How is dependency injection done?

Write 1-2 examples for each pattern, not a generic description.

Step 4: Document entry points

## Entry Points

- `src/index.ts` — Application bootstrap, registers routes and middleware
- `src/workers/queue.ts` — Background job processor, runs independently
- `scripts/migrate.ts` — Database migration runner

Step 5: List key dependencies

For each significant dependency, document:

What it is used for in this project
Where in the codebase it is used
Version (note if pinned due to known issues)

Accuracy rules

Only document what you have read — never document by assumption
If a file's purpose is unclear, note "purpose unclear — investigate before modifying"
Timestamp the mapping: Last updated: [date]

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

Reviews can't be read right now.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free