deepcode-sync

name	deepcode-sync
description	Build and maintain a structured knowledge base (.mycode/) of the current codebase. Scans project structure, docs, and code patterns then writes organized markdown files. Use when starting in a new project, after significant codebase changes, or when context feels stale.
argument-hint	["force|update|status"]
user-invocable	true
allowed-tools	GlobTool, GrepTool, ReadTool, FileWriteTool, FileEditTool, BashTool, WebFetchTool
context	fork
agent	general-purpose

Deepcode Sync

Build and maintain .mycode/ — a structured, persistent knowledge base of the current codebase. This skill creates organized markdown documentation so Claude can understand the project without re-reading the entire codebase every session.

Overview

.mycode/ lives at the project root and contains detailed, structured documentation of the codebase. Unlike CLAUDE.md (which is for behavioral instructions), .mycode/ is pure knowledge: architecture, stack, tools, commands, services, patterns, and quirks.

A GUIDE.md file acts as the index — Claude reads this first to find what it needs.

Mode

Run with /deepcode-sync or pass an argument:

• /deepcode-sync — normal sync: check external docs first, scan codebase, update .mycode/
• /deepcode-sync force — force full rebuild of all files
• /deepcode-sync update — only update files that changed since last sync
• /deepcode-sync status — show what's in .mycode/ and when it was last updated

Workflow

Phase 1: Read External Docs First

Before scanning the codebase, read external documentation to understand the project:

1. Check README.md at project root
2. Check CHANGELOG.md if it exists
3. Check package.json for scripts and dependencies
4. Check docs/ directory if it exists
5. Check project-level CLAUDE.md (.claude/CLAUDE.md or ./CLAUDE.md)

Summarize what you learned. If .mycode/ already exists and this is an update, compare external docs with what's documented — flag anything that changed.

Phase 2: Scan Codebase Structure

Use Glob and Grep to map the codebase efficiently:

• GlobTool("**/*.ts") / GlobTool("**/*.tsx") — list all source files
• GlobTool("src/**/") — map directory structure
• Key entry points: src/main.tsx, src/index.ts, package.json
• Key config files: tsconfig.json, biome.json, etc.

Don't read every file — read selectively:

• Entry points and main modules
• A few representative files from each directory
• Files that look like they define core types or interfaces

Phase 3: Build / Update .mycode/

Structure .mycode/ like this:

.mycode/
├── GUIDE.md              # Index — what each file contains (always read this first)
├── ARCHITECTURE.md       # High-level architecture, layers, data flow
├── STACK.md              # Tech stack, runtime, dependencies, versions
├── STRUCTURE.md           # Directory tree + what each dir does
├── COMMANDS.md           # Available commands and scripts
├── CONFIG.md             # Configuration files and environment variables
└── QUIRKS.md             # Gotchas, non-obvious patterns, pain points

File Templates

Use references/TEMPLATES.md for the structure of each file. Keep content:

• Concise — bullet points, short sections, no fluff
• Specific — file paths, function names, actual values
• Stable — document things that don't change daily
• Actionable — Claude should be able to use this to write correct code

Phase 4: Write GUIDE.md

GUIDE.md is the most important file — it's what Claude reads first. Keep it under 30 lines with links to other files:

# .mycode/ Guide

This directory contains structured knowledge about this codebase.

## Files

- [ARCHITECTURE.md](ARCHITECTURE.md) — Layers, data flow, component relationships
- [STACK.md](STACK.md) — Runtime, language, framework, dependencies
- [STRUCTURE.md](STRUCTURE.md) — Directory tree and module purposes
- [COMMANDS.md](COMMANDS.md) — Build, test, dev, lint commands
- [CONFIG.md](CONFIG.md) — Config files, env vars, feature flags
- [QUIRKS.md](QUIRKS.md) — Gotchas, edge cases, non-obvious behaviors

Phase 5: Status Report

After sync, show a summary:

## Deepcode Sync Complete

### Files Updated
- ARCHITECTURE.md — updated data flow section
- STACK.md — no changes
- ...

### New Discoveries
- Found 3 new services in src/services/ai/
- Deprecated: src/legacy/ (no longer in use)

### Stats
- .mycode/ size: 6 files, ~15KB
- Last sync: 2026-05-15

Guidelines

Do

• Document file paths and module names
• Note non-obvious patterns and quirks
• Keep it concise — bullet points over paragraphs
• Update only what changed in incremental mode
• Use GUIDE.md as the entry point

Don't

• Don't duplicate what's in README or CLAUDE.md
• Don't document code that's self-evident
• Don't write essays — one page per topic max
• Don't document things that change every commit

How to Know It's Working

• New sessions understand the codebase without reading 20 files
• /deepcode-sync status shows recent sync date
• Claude references .mycode/ files when answering questions