PKM

Vuexy Next.js — Codebase Documentation and SKILL.md Strategy

4 min read

Vuexy Next.js — Codebase Documentation and SKILL.md Strategy

A method for using Claude Code to systematically document any large template codebase and produce a persistent context file (SKILL.md) that Claude can load before every development task.

Why / When to Use

When you have a large, complex template codebase (e.g. Vuexy Next.js) and want Claude Code to work inside it confidently — reusing existing components rather than reinventing them, following codebase conventions, and knowing where everything lives.

Core Concept

Run Claude Code through a 4-phase analysis that produces 12 documentation files in claude-docs/. The final file — SKILL.md — is a dense, verified context anchor Claude loads at the start of every session.

Phase 1 — Codebase Discovery

# Start Claude Code in the Vuexy project root
cd ~/projects/vuexy-next.js
claude

Ask Claude Code to scan:

  • Full directory structure and key config files
  • Routing strategy (App Router vs Pages Router)
  • Where branding/colors/navigation configs live
  • Where mock/fake data lives

Phase 2 — Systematic Deep Read

Claude Code reads all source files in this order:

  1. Config & Setup (next.config.js, tailwind.config.js, MUI theme)
  2. Layouts — every variant, slots, when each is used
  3. Navigation — menu config, route→nav mapping
  4. UI Components — every component with props, variants, usage
  5. Pages & Routes — every page, data requirements
  6. Pre-built Apps — Email, Chat, Calendar, Kanban, eCommerce, Invoice
  7. Data Fetching — SWR/React Query/axios patterns, mock data locations
  8. Charts — ApexCharts vs Chart.js usage, data shapes
  9. Authentication — JWT, Auth Guards, login flow, session handling
  10. ACL — role definitions, permission checks, route and UI restriction patterns
  11. Forms — form library, validation patterns, reusable form components
  12. State Management — Redux/Zustand/Context, store structure
  13. Theming — MUI theme customisation, Tailwind config, dark mode
  14. Types & Interfaces — key TypeScript types
  15. Utilities & Hooks — every custom hook and utility

Phase 3 — claude-docs/ File Inventory

FileContents
CODEBASE_MAP.mdDirectory tree, tech stack, routing strategy, key config files
COMPONENTS.mdEvery component: location, props, variants, usage example
LAYOUTS.mdAll layout variants, slots, when to use each
PAGES_AND_APPS.mdEvery pre-built page/app: route, data needs, how to adapt
DATA_AND_CHARTS.mdFetch patterns, mock data locations, chart components
AUTH_AND_ACL.mdJWT/Auth Guard/session flow, role definitions, ACL patterns
THEMING_AND_STYLING.mdMUI theme, Tailwind config, dark mode, design tokens
FORMS_AND_VALIDATION.mdForm library, validation patterns, reusable form components
STATE_MANAGEMENT.mdRedux/Zustand/Context usage, store structure
HOOKS_AND_UTILS.mdEvery custom hook and utility with usage examples
TYPESCRIPT_TYPES.mdCore types/interfaces and where they are used
SKILL.mdCrown jewel — dense context anchor Claude loads before every task

Phase 4 — SKILL.md Structure

The SKILL.md contains 21 sections:

  1. Codebase Identity (one paragraph)
  2. Absolute Rules (15–20 must-follow conventions)
  3. Directory Map (compact, one line per folder)
  4. Layout System (variants, how to apply)
  5. Navigation & Menu (config file, how to add items)
  6. Component Reference (table + full entry for top 15–20)
  7. Page & Route Patterns (new page boilerplate)
  8. Authentication (login flow, protecting routes, connecting real backend)
  9. Access Control (roles, permission checks, route restriction)
  10. Data Fetching (patterns, mock→real swap)
  11. Charts & Data Visualization (reusable chart components)
  12. Forms & Validation (standard form pattern, form+API submission)
  13. State Management (store structure, how to add state)
  14. Theming & Styling (MUI tokens, dark mode, how to style new components)
  15. Custom Hooks Reference
  16. Utility Functions Reference
  17. TypeScript Types Reference
  18. Task Playbook (10 most common tasks step-by-step)
  19. Anti-Patterns (what NOT to do with correct alternatives)
  20. Quick-Start Checklist
  21. File Finder

How to Use After Generation

# Every new Claude Code session:
"Read claude-docs/SKILL.md first, then [your task here]"

The SKILL.md becomes smarter over time — when Claude finds something undocumented or wrong, update the SKILL.md in place.

Gotchas

  • Every file path in SKILL.md must be real and verified from source — never guessed
  • Code examples must use actual imports from this codebase, not generic Next.js code
  • Run Phase 1 (codebase scan) before Phase 2 (SKILL.md creation) — SKILL.md relies on the 11 prior docs

Source

Conversation: “Next.js template framework contents” — 2026-05-13

Graph View