Explore a workspace codebase and generate or improve CLAUDE.md and .claude/rules/ documentation. Analyzes directory structure, tech stack, conventions, and workflows to produce context-engineered documentation optimized for Claude's processing. Use this skill when the user wants to set up a project for Claude, initialize Claude context, create or update CLAUDE.md, document a codebase for Claude, migrate from .cursorrules, or mentions "codebase docs", "claude docs", "셋업", "문서화" in context of Claude configuration — even if they don't say "codebase-docs" explicitly. Invoke with /codebase-docs [path].
Explore a workspace and produce high-quality CLAUDE.md and .claude/rules/ files that maximize Claude's effectiveness in that codebase. If documentation already exists, analyze and improve it.
This skill applies context engineering best practices:
If argument provided, use that path. Otherwise, use the current working directory.
Confirm the target workspace path with the user before proceeding. If the workspace is the same repo where this skill lives (dotfiles), warn and confirm — the user likely wants to target a different project.
Detect the user's language from conversation context. The generated CLAUDE.md body (rules, directives, commands) should be in English for higher LLM compliance. Project description and inline comments may use the user's language if the team is non-English.
Run these in parallel using the Explore agent or direct tools:
1a. Structure scan:
ls top-level directoryGlob for key config files: **/package.json, **/Cargo.toml, **/go.mod, **/pyproject.toml, **/build.gradle*, **/pom.xml, **/Makefile, **/Dockerfile*, **/docker-compose*, **/.github/workflows/*Glob for framework/tooling configs: **/tsconfig*.json, **/vite.config.*, **/next.config.*, **/nuxt.config.*, **/tailwind.config.*, **/turbo.json, **/nx.json, **/pnpm-workspace.yamlGlob for version/env files: **/.nvmrc, **/.node-version, **/.python-version, **/.env.example, **/renovate.json, **/.github/dependabot.ymlGlob for existing docs: **/CLAUDE.md, **/.claude/rules/*, **/.cursorrules, **/.github/CONTRIBUTING.md1b. Convention detection:
Grep for test patterns: describe(, it(, test(, #[test], func Test, def test_, @TestGrep for linting configs: .eslintrc*, .prettierrc*, ruff.toml, .golangci*, clippy.toml.github/workflows/, .gitlab-ci.yml, Jenkinsfile1c. Git history analysis:
git log --oneline -20 — recent work direction and active areasgit log --format='%s' -50 — detect commit conventions (conventional commits, prefixes, etc.)git log --diff-filter=M --name-only --pretty='' -50 | sort | uniq -c | sort -rn | head -10 — most actively modified filesgit branch -r | head -20)1d. Read key files (first 100 lines each, if they exist):
From Step 1 results, determine:
| Dimension | What to extract |
|---|---|
| Tech stack | Languages, frameworks, major dependencies |
| Project type | Library, CLI, web app, API, monorepo, etc. |
| Build system | Commands to build, test, lint, format |
| Code organization | src/ layout, module patterns, naming conventions |
| Testing | Framework, test location, run commands |
| CI/CD | Pipeline structure, deployment targets |
| Existing conventions | Code style, commit conventions, PR process |
| Git workflow | Commit message format, branch strategy, active areas |
| Runtime versions | Node/Python/Go versions pinned via version files |
If .cursorrules found: Parse and map existing rules into CLAUDE.md sections and .claude/rules/ files. Present a migration plan showing where each rule maps to before proceeding. Delete .cursorrules only after user confirms the migration is complete.
Classify the codebase:
| Type | CLAUDE.md Focus |
|---|---|
| Monorepo | Top-level index + per-package rules (see references/monorepo-guide.md) |
| Library/SDK | API design conventions, test patterns, versioning |
| Web app | Component patterns, state management, routing |
| CLI tool | Command structure, argument parsing, output format |
| API service | Endpoint conventions, error handling, auth patterns |
| Config/dotfiles | Stow structure, platform specifics, deployment |
Check if CLAUDE.md or .claude/rules/ already exist.
If no existing docs → generate fresh using references/claude-md-template.md.
If existing docs found → enter Improvement Mode (see references/improvement-checklist.md for detailed criteria):
.claude/rules/ glob patterns match current directory structurereferences/claude-md-template.md)The generated CLAUDE.md must follow this hierarchy:
1. Project identity (1-2 lines: what this is)
2. Essential commands (build, test, lint — copy-pasteable)
3. Architecture overview (directory map, key patterns)
4. Code conventions (naming, style, patterns to follow)
5. File references for deep dives ("see docs/api.md for endpoint specs")
Generate context-specific rule files when the project warrants them:
| File pattern | When to create | Content focus |
|---|---|---|
*.md (general) | Always, if project has specific patterns | Code style, naming, imports |
test-*.md | Test files detected | Test conventions, mocking patterns |
api-*.md | API routes detected | Endpoint patterns, error responses |
component-*.md | UI components detected | Component structure, props, state |
Rules files use paths in frontmatter to scope activation:
---