codebase-docs

name

codebase-docs

description

Generate comprehensive markdown documentation from a codebase across multiple dimensions: project structure, database schema, features/business logic, API, and architecture. Supports multiple languages and frameworks including Ruby on Rails, React, Next.js, Python (Django/FastAPI/Flask), Node.js, Go, iOS (SwiftUI/UIKit/Swift/Objective-C), and more. Use this skill whenever the user wants to document a codebase, generate docs from source code, produce a technical overview of a repo, or create any kind of markdown documentation derived from reading actual project files. Also trigger when user says things like "document this repo", "generate docs for my project", "write up what this codebase does", or "create technical documentation".

Codebase Docs Skill

Generate multi-dimensional markdown documentation from any codebase, regardless of language or framework.

Quick Start

1. Detect the project's language/framework (see Detection below)
2. Select which doc dimensions to generate (or generate all)
3. Load the appropriate reference file for file selection strategy
4. Generate each doc using the prompts and templates in this file

---

Step 1: Framework Detection

Run these commands on the repo root to detect the stack:

# Check for key indicator files
ls package.json Gemfile requirements.txt go.mod pyproject.toml Cargo.toml 2>/dev/null

# iOS / macOS
find . -maxdepth 3 -name "*.xcodeproj" -o -name "*.xcworkspace" | head -3
ls Podfile Package.swift 2>/dev/null

# For JS/TS projects, check framework
cat package.json | grep -E '"next"|"react"|"express"|"fastify"|"nuxt"' 2>/dev/null

# For Python
cat requirements.txt pyproject.toml 2>/dev/null | grep -E 'django|fastapi|flask|sqlalchemy'

# For Ruby
cat Gemfile 2>/dev/null | grep -E 'rails|sinatra|hanami'

Then load the relevant reference file:

Detected Stack	Reference File
iOS / SwiftUI / UIKit	references/ios.md
Ruby on Rails	references/ruby-on-rails.md
React / Next.js	references/react-next.md
Python (Django / FastAPI / Flask)	references/python-web.md
Node.js (Express / Fastify)	references/node.md
Go	references/go.md
Generic / Unknown	references/generic.md

If multiple stacks exist (e.g., Rails API + React frontend), load both reference files.

---

Step 2: Select Dimensions

Default: generate all applicable dimensions for the detected stack.

Dimension	Output File	Always?
Project Structure	structure.md	✅ Yes
Database & Schema	database.md	If DB detected
Features & Business Logic	features.md	✅ Yes
API Endpoints	api.md	If API detected
Architecture & Data Flow	architecture.md	✅ Yes
Frontend Components	frontend.md	If UI detected

---

Step 3: File Selection Strategy

Each reference file specifies exactly which files to read for each dimension. This keeps context lean — never load the whole repo at once.

General rules:

• Structure: always use find + tree commands, read README, main config files
• Database: read only schema/migration files and model definitions
• Features: read controller/route/service/handler files; skip tests and generated code
• API: read route definitions, serializers/schemas, middleware
• Frontend: read component files, pages, hooks — skip node_modules, build output

# Useful recon commands
find . -name "*.rb" -path "*/models/*" | head -30
find . -name "schema.rb" -o -name "*.sql" -o -name "models.py" 2>/dev/null
find . -name "routes.rb" -o -name "urls.py" -o -name "router.ts" 2>/dev/null
grep -r "def " --include="*.py" -l | grep -v test | head -20

---

Step 4: Generation Prompts

Use these prompts as guidance when generating each dimension's document. Replace {STACK} with the detected framework name.

📁 structure.md

You are a technical writer documenting a {STACK} project.
Given the directory tree and key config files below, generate a markdown document covering:
1. Project overview (1-2 sentences inferred from code/README)
2. Directory structure with explanation of each top-level folder
3. Key configuration files and their purpose
4. Tech stack summary (languages, frameworks, major dependencies)
5. How to run the project locally (infer from Makefile/scripts/README)

Be concise and factual. Do not invent details not present in the files.
Output only the markdown document, starting with # Project Structure.

🗄️ database.md

You are a technical writer documenting the database design of a {STACK} project.
Given the schema/migration files and model definitions below, generate a markdown document covering:
1. Database overview (which DB engine, ORM used)
2. Entity Relationship summary (main entities and their relationships in prose)
3. Table-by-table reference: columns, types, constraints, indexes
4. Notable design decisions (polymorphism, soft deletes, JSONB fields, etc.)
5. Include a mermaid erDiagram for the main entities

Format tables using markdown tables. Group related models together.
Output only the markdown document, starting with # Database Schema.

⚙️ features.md

You are a technical writer documenting the business logic of a {STACK} project.
Given the controller/service/handler files below, generate a markdown document covering:
1. Core features list (bullet points, inferred from code)
2. Feature deep-dives: for each major feature, describe what it does, key files involved, and any non-obvious logic
3. Background jobs / async tasks if present
4. External integrations (payment, email, storage, etc.)

Focus on WHAT the code does, not HOW. Avoid code snippets unless essential.
Output only the markdown document, starting with # Features & Business Logic.

🔌 api.md

You are a technical writer documenting the API of a {STACK} project.
Given the route definitions and serializer/schema files below, generate a markdown document covering:
1. API overview (REST/GraphQL/gRPC, auth mechanism)
2. Base URL and versioning
3. Endpoint reference: for each endpoint, show Method, Path, Description, Request params, Response shape
4. Common error responses
5. Authentication & authorization notes

Use markdown tables for the endpoint reference.
Output only the markdown document, starting with # API Reference.

🏗️ architecture.md

You are a senior engineer documenting the architecture of a {STACK} project.
Given the codebase files below, generate a markdown document covering:
1. Architecture pattern (MVC, hexagonal, microservices, etc.)
2. Request lifecycle (how a request flows through the system)
3. Key abstractions and design patterns used
4. Data flow diagram (use a mermaid flowchart)
5. External dependencies and third-party services
6. Scalability and performance considerations visible from code

Output only the markdown document, starting with # Architecture Overview.
Include at least one mermaid diagram.

🖥️ frontend.md

You are a technical writer documenting the frontend of a {STACK} project.
Given the component and page files below, generate a markdown document covering:
1. UI framework and component library used
2. Page/route structure
3. Key components: name, purpose, props/interface
4. State management approach
5. API integration patterns (how frontend talks to backend)
6. Styling approach (CSS modules, Tailwind, styled-components, etc.)

Output only the markdown document, starting with # Frontend Components.

---

Step 5: Output & Assembly

Save each dimension to its output file. Optionally generate an index.md:

# Project Documentation

Auto-generated documentation for **{project_name}**.

| Document | Description |
|---|---|
| [Project Structure](structure.md) | Directory layout, tech stack, setup |
| [Database Schema](database.md) | Tables, relationships, indexes |
| [Features](features.md) | Business logic and core functionality |
| [API Reference](api.md) | Endpoints, request/response formats |
| [Architecture](architecture.md) | Patterns, data flow, design decisions |
| [Frontend](frontend.md) | Components, routing, state management |

---

Reference Files

Read the relevant file(s) for framework-specific guidance on which files to load:

• references/ios.md — iOS (SwiftUI, UIKit, Swift, Objective-C)
• references/ruby-on-rails.md — Ruby on Rails file selection & tips
• references/react-next.md — React / Next.js
• references/python-web.md — Django, FastAPI, Flask
• references/node.md — Express, Fastify, NestJS
• references/go.md — Go (net/http, Gin, Echo)
• references/generic.md — Unknown / polyglot repos