메뉴
Deep-analyzes the codebase to discover stack, architecture, patterns, conventions, and pitfalls. Creates .vibeflow/ knowledge base. Use when setting up a project, after significant changes, or to deep-dive into a specific module.
Codex 또는 Claude로 설치 이 Prompt를 복사해 Codex, Claude 또는 다른 어시스턴트에 붙여 넣으면 Skill 페이지를 검토하고 설치를 진행할 수 있습니다.
SOC 직업 분류 기준
Audits recent work against its Definition of Done and project patterns. Runs the test suite, compares code against the spec, and reports PASS / PARTIAL / FAIL. Also runs the Critical Gate — a safety scan of the diff for destructive or dangerous operations. Generates an incremental prompt pack for any gaps found. Use after implementation to verify quality before shipping.
Audits implementation against its DoD and project patterns. Runs the test suite, compares code against the spec, and reports PASS / PARTIAL / FAIL. Also runs the Critical Gate — a safety scan of the diff for destructive or dangerous operations. Use after implementation to verify quality before shipping.
Implements a feature from its spec following all guardrails: budget, DoD, anti-scope, and pattern compliance. Runs an 8-phase pipeline (find spec → extract guardrails → load patterns → plan → implement → test → refine → self-verify DoD). Use after gen-spec when you're ready to code. The agent has filesystem access and acts as Coding Agent.
Implements a feature from its spec with guardrails: budget, DoD, anti-scope, and pattern compliance. Runs an 8-phase pipeline (find spec → extract guardrails → load patterns → plan → implement → test → refine → self-verify DoD). Use after gen-spec when ready to implement.
Deep-analyzes the current codebase to discover stack, architecture, patterns, conventions, and pitfalls. Creates curated documentation in .vibeflow/ that persists and can be committed to git. Supports incremental updates, scoped deep-dives, interactive review, and satellite repo analysis. Use when setting up a project, after significant changes, or to deep-dive into a specific module.
Generates a technical spec with objective, Definition of Done (3–7 binary checks), scope, anti-scope, technical decisions, and applicable patterns. Grounded in the project's real patterns from .vibeflow/. Auto-splits specs that exceed budget or DoD limits. Use when requirements are clear and you're ready to define the implementation contract.
| name | vibeflow-analyze |
| description | Deep-analyzes the codebase to discover stack, architecture, patterns, conventions, and pitfalls. Creates .vibeflow/ knowledge base. Use when setting up a project, after significant changes, or to deep-dive into a specific module. |
Deep-analyze the current codebase. Discovers stack, architecture,
patterns, conventions, key components, and pitfalls. Creates curated
documentation in .vibeflow/ that persists and can be committed to git.
Supports incremental analysis: if .vibeflow/ already exists, detects
changes via git and updates only affected modules.
Usage: Invoke this skill from the project root. Pass --fresh as input to force a complete rebuild. Pass --scope <path> to deep-dive into a specific module/directory. Pass --interactive to validate and enrich patterns with human feedback before saving. Pass --satellite <url> to analyze a dependency repo and merge only used patterns.
Detect the language of the user's conversation context.
Write ALL output in that same language.
Technical terms in English are acceptable regardless of the detected language.
Section names in generated .vibeflow/ files may be in English (they are technical),
but all descriptive text, analyses, observations, and final user reports should be
in the detected language.
Perform a deep, adaptive analysis of this codebase. Your goal is to build curated pattern documentation that will be used by every future spec, prompt pack, and audit to ensure implementations follow the project's real conventions.
Check the current state to decide which mode to run:
.vibeflow/index.md exist? (read it directly by path — see access rule below)--fresh?--scope <path>?--interactive?--satellite <url>?⚠️ .vibeflow/ access rule: The .vibeflow/ directory is gitignored by default.
Search and grep tools in IDEs respect .gitignore and will NOT find .vibeflow/ files.
To check if .vibeflow/ exists, read .vibeflow/index.md directly by its file path.
Do NOT use file search, grep, or glob to check for its existence — these will return
empty results and cause a false "does not exist" conclusion.
--interactive flag: If present, activates Phase 3.5 (Review & Enrich) after Phase 3. Composes with all modes: fresh, incremental, and scoped. Does NOT change which phases run — it adds a review step before saving.
Decision tree:
--satellite <url> requested:
.vibeflow/index.md DOES NOT exist → STOP with: "Run analyze first to establish project context, then use --satellite to analyze a dependency repo.".vibeflow/index.md EXISTS → enter satellite mode (see "Satellite Analysis Mode" section below). Skip Phases 1-5 entirely.--scope <path> requested:
.vibeflow/index.md DOES NOT exist → STOP with: "Run analyze first to establish project context, then use --scope to deep-dive into specific modules.".vibeflow/index.md EXISTS → enter scoped mode (see "Scoped Analysis Mode" section below). Skip Phases 1-5 entirely..vibeflow/ DOES NOT exist OR --fresh requested → proceed with full analysis (Phases 1-5).vibeflow/ EXISTS AND no --fresh → enter incremental mode:
Analyzed: <date> from .vibeflow/index.mdgit log --since="<date>" --name-only --pretty=format:"" to find files changed since that analysis date*.test.*, *.spec.*, docs/, README.md, .env.*, etc.).vibeflow/ is up to date." and STOP (exit early)Incremental mode: Only re-detect knowledge sources that changed per git diff. Reuse existing stack/type/structure from index.md for unchanged aspects. In fresh mode, proceed as described below.
Read the project root to understand what you're dealing with:
Sources of knowledge to detect explicitly:
.cursorrules (project-level rules).cursor/rules/*.mdc (domain-specific rules)CLAUDE.md (project instructions).clinerules (Cline AI rules).github/copilot-instructions.md (GitHub Copilot rules)/docs/ directory (if present)ARCHITECTURE.md (if present)ADRs/ directory (if present)Directories to ignore: node_modules/, .venv/, venv/, dist/, build/, .next/, __pycache__/, .git/
Determine:
Report which sources of knowledge were found.
DO NOT assume monorepo, Next.js, KMP, or any specific structure. Let the code tell you what it is.
Domain classification: Based on what was detected, classify the project into one of:
Based on the domain, activate mandatory pattern priorities (used in Phase 2 and 3):
Mobile: design-system/UI-components (REQUIRED), screen/feature-composition (REQUIRED), navigation (REQUIRED), state-management, networking/API-layer, DI, analytics, feature-flags, i18n
Web frontend: design-system/component-library (REQUIRED), page/route-composition (REQUIRED), state-management (REQUIRED), API-layer, auth, i18n
API/backend: route/endpoint-definition (REQUIRED), data-access/repository (REQUIRED), auth/middleware (REQUIRED), error-handling, DB-migrations, background-jobs
Library/CLI/other: no mandatory patterns — use existing heuristics
Incremental mode: Only re-extract rules from knowledge sources that changed. Merge with existing rules map (reuse unchanged rules). In fresh mode, proceed as described below.
Read all sources of knowledge found in Phase 1. From each, extract:
Produce an internal map (not a final output file):
.cursorrules + CLAUDE.md = project-level rules; .cursor/rules/*.mdc = domain-specific; /docs/ = reference docsPurpose of this map: Guide the sampling strategy in Phase 2 and the deep dive scope in Phase 3.
Incremental mode: Only re-sample modules that had file changes. Preserve existing sampling results for unaffected modules. In fresh mode, proceed as described below.
Heuristic for sampling:
fin_*.py, task_*.js), and mentions in rules from Phase 1.5Sampling scale (based on estimated total source files):
| Source files | Min files to sample | Per module |
|---|---|---|
| ≤50 | 8 | ≥2 |
| 51–200 | 12 | ≥2 |
| 201–1000 | 20 | ≥2 |
| 1001–5000 | 30 | ≥3 |
| 5001–20000 | 40 | ≥3 |
| 20000+ | 50–60 | ≥3 |
Prioritize: largest files by line count, most imported by others, mentioned in rules. For repos with >100 source files: explicitly document what was NOT covered in "Known Gaps" section of index.md.
Cross-module sampling (for repos with 1000+ source files): Instead of sampling many files from a few modules, sample the SAME LAYER across multiple modules/features:
Mandatory pattern verification: After sampling, check the mandatory pattern list from Phase 1 domain classification. For each REQUIRED pattern not yet covered by sampling:
Document (for all sampled files):
Look for REPEATED patterns, not one-off occurrences.
Incremental mode: Only re-analyze patterns for affected modules. For pattern docs being updated, preserve content outside <!-- vibeflow:auto:start/end --> markers — this includes the YAML frontmatter block at the top. Frontmatter preservation rule: If the pattern doc already has a --- frontmatter block AND the content within <!-- vibeflow:auto --> markers did NOT change, keep the existing frontmatter untouched (the dev may have manually edited tags via /vibeflow:teach). If the auto content DID change, regenerate the frontmatter to reflect the updated content. For existing pattern docs without markers (legacy), rewrite them entirely with markers and frontmatter added. For new patterns, create with frontmatter and markers. In fresh mode, proceed as described below.
Imported pattern protection: Before creating or updating a pattern doc, check if a pattern with the same name exists in .vibeflow/patterns/external-*/ (imported via teach --from). If an imported version exists, skip that pattern — do not create or overwrite a local version. Imported patterns from an external source of truth take precedence over auto-discovered patterns. Log a note: "Skipping <name> — imported version exists in external-<repo>/."
This is the most important phase. For each significant pattern you discover:
Expand scope using rules map: Consider modules/subsystems from the Phase 1.5 rules map, not just those found in Phase 2 sampling. If a rule mentions a module the sampling didn't cover (e.g., "fitness module" in rules but not sampled), read files from that module and decide if it deserves a pattern doc.
Cross-module pattern rule: For pattern docs that document a horizontal layer (UI composition, data access, navigation, design system usage, state management), include examples from at least 3 different features/modules. This ensures the documented pattern is the real convention, not an outlier from a single feature.
What counts as a "significant pattern" depends on the project. Examples:
Create ONE markdown file per pattern in .vibeflow/patterns/.
Name files descriptively: api-routes.md, component-architecture.md,
data-access.md, auth-flow.md, cli-commands.md, etc.
Each pattern doc must follow this structure with YAML frontmatter and markers to delimit auto-generated content:
---
tags: [tag1, tag2, tag3]
modules: [src/path1/, src/path2/]
applies_to: [artifact-type1, artifact-type2]
confidence: inferred
---
# Pattern: <Name>
<!-- vibeflow:auto:start -->
## What
1-2 sentence description of what this pattern is.
## Where
Which parts of the codebase use it.
## The Pattern
Show the REAL pattern with actual code examples from this repo.
Include 2-3 concrete examples so a coding agent can replicate it exactly.
## Rules
- Specific rules this pattern follows
- Naming conventions specific to this pattern
- What to do / what NOT to do
## Examples from this codebase
File: <real path>
<actual code snippet showing the pattern correctly>
File: <real path>
<another example, ideally showing a variation>
<!-- vibeflow:auto:end -->
## Anti-patterns (if found)
Things that exist in the codebase that BREAK this pattern.
Mark them so future work doesn't replicate mistakes.
YAML frontmatter rules:
--- delimiters) goes at the VERY TOP of the file, BEFORE the # Pattern: heading and OUTSIDE the <!-- vibeflow:auto --> markers.tags: 3-7 lowercase strings describing the domain/concepts this pattern covers. Derive from the pattern name, the "What" section content, and key concepts in "The Pattern" section. Avoid generic tags like code, file, pattern. Use specific domain tags like auth, middleware, api-routes, state-management, navigation, design-system, etc.modules: List of directory paths (relative to repo root, ending in /) where this pattern manifests. Derive from the "Where" section and the file paths in "Examples from this codebase".applies_to: List of artifact types this pattern governs. Use generic type names: components, routes, handlers, middleware, hooks, models, services, screens, tests, configs, migrations, commands, interceptors, guards, resolvers, controllers, etc.confidence: inferred (default — pattern found by automated analysis) or validated (confirmed by human via --interactive or /vibeflow:teach). Set to inferred on creation. Changed to validated during Phase 3.5 interactive review.Marker placement rule: Wrap sections ## What, ## Where, ## The Pattern, ## Rules, and ## Examples from this codebase with <!-- vibeflow:auto:start/end --> markers. The ## Anti-patterns section should NOT be wrapped — it's a natural place for manual additions and evolution. The YAML frontmatter is also NOT wrapped — it lives outside markers so manual edits to tags (via /vibeflow:teach) survive incremental updates.
CRITICAL: Include REAL code snippets from REAL files. Not pseudocode. Not "something like this". The actual code. This is what makes the patterns actionable for a coding agent.
## Rationale section: When rationale is provided (via --interactive Phase 3.5 or /vibeflow:teach), add a ## Rationale section between <!-- vibeflow:auto:end --> and ## Anti-patterns. This section is OUTSIDE markers and survives incremental updates. Only create when rationale is actually provided — no empty placeholders.
This phase runs ONLY when --interactive flag is present. Without the flag, skip directly to Phase 4.
Incremental + interactive: Only present patterns that are NEW or CHANGED in this run. Patterns already having confidence: validated in their frontmatter that were NOT modified are already validated — skip them.
Present the patterns found to the user in a compact summary:
## Patterns found (N):
1. **<Name>** — <1-line description> (modules: <paths>)
2. **<Name>** — <1-line description> (modules: <paths>)
...
### Questions:
1. **False positives?** Any of these patterns exist in the code but are NOT
intentional conventions your team follows? (indicate by number)
2. **Missing patterns?** Any conventions your team follows that didn't
show up in the analysis? (describe briefly)
3. **Why?** For the most important patterns, why did your team adopt them?
(optional, but greatly enriches the docs)
After the user responds, incorporate feedback:
confidence: deprecated and explain in ## Anti-patterns.confidence: validated. Note source: team-reported in ## What. Mark examples as <!-- TODO: find code examples -->.## Rationale section to the pattern doc (outside auto markers, before ## Anti-patterns). Content: the user's explanation.confidence: validated in frontmatter.After incorporating feedback, proceed to Phase 4.
Incremental mode:
Analyzed: <date> to the current date. Update Structural Units and Key Files only if they changed. Preserve any manually added Known Issues section.<!-- vibeflow:auto:start/end --> markers. Preserve content outside markers (this is where manual additions live). If no markers exist in the file (legacy format), rewrite the entire file with markers added.patterns/: For docs being updated, preserve content outside markers. For legacy docs without markers, rewrite with markers. For new patterns, create with markers.In fresh mode, proceed as described below.
.vibeflow/
├── index.md # Overview: stack, structure, list of all pattern docs
├── conventions.md # Coding conventions (naming, style, organization)
├── patterns/
│ └── <whatever>.md # One file per discovered pattern (varies by repo)
└── decisions.md # Empty for now, grows with use
# Project: <name>
> Analyzed: <date>
> Stack: <concise summary>
> Type: <project type>
> Suggested budget: ≤ N files per task
## Structure
<brief description of how the project is organized>
## Structural Units
<list the major units — modules, packages, routes, features, etc.>
<1-line description each>
## Pattern Registry
<!-- vibeflow:patterns:start -->
patterns:
- file: patterns/<name>.md
tags: [tag1, tag2, tag3]
modules: [src/path1/, src/path2/]
- file: patterns/<name>.md
tags: [tag4, tag5]
modules: [src/path3/]
<!-- vibeflow:patterns:end -->
## Pattern Docs Available
<list each .vibeflow/patterns/*.md with 1-line description>
## Key Files
<10-15 most critical files with 1-line descriptions>
## Dependencies (critical only)
<critical deps with 1-line rationale>
## Known Issues / Tech Debt
<bullet list if anything was found>
Pattern Registry generation: After creating/updating all pattern docs, build the Pattern Registry block in index.md. For each pattern doc in .vibeflow/patterns/:
tags and modules fields)<!-- vibeflow:patterns:start/end --> markersThe registry is ALWAYS regenerated from the pattern doc frontmatters — it is never manually edited. This ensures it stays in sync.
Budget calculation: Count the total number of source files sampled/detected in Phase 2. Suggest a budget of ~2-3% of total source files, clamped between a minimum of 4 and a maximum of 12:
Write the result as > Suggested budget: ≤ N files per task in the
index.md header. This is used by gen-spec and prompt-pack as the default budget.
Dense, specific, actionable. NOT vague guidelines — concrete rules with examples. A coding agent should be able to read this and write code that fits in perfectly.
Markers in conventions.md: Wrap the main auto-generated convention sections
with <!-- vibeflow:auto:start --> and <!-- vibeflow:auto:end -->. This allows
manual additions (team updates, discovered edge cases) to persist outside the
markers when running incremental updates.
Incorporate rules from Phase 1.5: Conventions extracted from rules/instructions must be included in conventions.md with source attribution: "(via .cursorrules)", "(via .cursor/rules/design-system.mdc)", "(via docs/ARCHITECTURE.md)". If a rule contradicts code, signal conflict: "⚠️ Conflict: .cursorrules says X, but the code does Y".
Don'ts section: conventions.md MUST include a ## Don'ts section with
explicit prohibitive rules discovered during analysis. These are as important
as prescriptive conventions — coding agents need to know what NOT to do.
Place this section inside the <!-- vibeflow:auto:start/end --> markers,
after the prescriptive convention sections.
Mine don'ts from:
any abuse in TypeScript,
hardcoded strings in i18n projects, mutable global state)Format: bullet list of concrete prohibitions with brief rationale. Example:
## Don'ts
- Do NOT use `any` in TypeScript — use `unknown` + type narrowing
- Do NOT hardcode user-facing strings — all copy goes through i18n files
- Do NOT import from internal modules of a dependency (e.g., `lib/src/internal`)
- Do NOT add new dependencies without explicit justification in the spec
Keep don'ts specific and grounded in the actual codebase — not generic best practices. Every don't should be traceable to something observed in the code, rules, or pattern anti-patterns.
Important: This file is NEVER modified by the analyze command, neither in fresh nor incremental mode. It is reserved for the architect and manual curation.
On fresh run (first analysis), create the file with a header and empty content only if it doesn't already exist:
# Decision Log
> Newest first. Updated by the architect during specs and audits.
On incremental run, leave decisions.md untouched.
After compiling all .vibeflow/ docs, ensure .vibeflow/index.md has an
up-to-date list of all pattern docs and their 1-line descriptions under
the "Pattern Docs Available" section.
--scope <path>)This mode runs when the user passes --scope <path>. It is a deep-dive into a specific module/directory, complementing the general analysis. It requires .vibeflow/index.md to already exist.
Read from the existing .vibeflow/:
index.md → stack, domain type, structural units, budgetconventions.md → global conventionspatterns/*.md → list of existing pattern docsThis provides the context that the scoped analysis builds upon. Do NOT re-detect stack, domain type, or project structure.
Focus discovery exclusively on the <path> directory:
Sample the module densely — the goal is deep understanding, not broad coverage:
For each pattern discovered in the scoped module:
If a matching global pattern doc already exists (e.g., patterns/screen-composition.md):
<!-- vibeflow:auto:start/end --> markers## Where section, add the scoped module as a location## Examples from this codebase, add 1-2 examples from the scoped modulemodules field of the frontmatter, add it. Preserve existing tags and applies_to.If the pattern is specific to this module and no global doc covers it:
patterns/ following the standard structure with frontmatter and markerspayments-reconciliation.md)For conventions.md:
<path>)"<path> diverges: "Runs ONLY when --interactive flag is present. Present only the patterns found/enriched in this scoped analysis. Follow the same format, questions, and feedback incorporation rules as Phase 3.5.
Add or update a ## Scoped Analyses section in index.md:
## Scoped Analyses
- `<path>` — analyzed on <date>, N files sampled, M patterns enriched/created
Also regenerate the ## Pattern Registry YAML block (read frontmatters from all pattern docs) and update the ## Pattern Docs Available section if new pattern docs were created.
<path>gen-spec or prompt-pack — the enriched patterns from <path> are now available."--satellite <url>)This mode runs when the user passes --satellite <url>. It analyzes a dependency repository (e.g. design system, shared lib) from the perspective of the current (main) repo. It clones the satellite, runs the analyze pipeline on it, detects what the main repo actually uses, and merges only those patterns into .vibeflow/. Requires .vibeflow/index.md to already exist.
Derive satellite name. From the URL, take the last path segment (e.g. design-system from github.com/org/design-system), remove .git if present, sanitize to alphanumeric and hyphen. Use as <satellite-name>.
Create temp directory. Use a unique path under system temp (e.g. $TMPDIR/vibeflow-satellite-<timestamp>). Do not use the main repo.
Clone. Run git clone --depth 1 <URL> <temp_dir>/satellite. If clone fails, report the error clearly, remove temp dir if partially created, then stop.
With the clone directory as the effective codebase root, perform the same phases as a fresh analysis (Discovery, Rules integration, Convention mining, Pattern deep dive, Compile). Write output inside the clone: <temp_dir>/satellite/.vibeflow/. Do not modify the main repo's .vibeflow/ in this step.
If any step fails after the clone, still remove the temp directory before exiting.
In the main repo (current working directory), collect what references the satellite:
package.json, build.gradle, Cargo.toml, pyproject.toml, or equivalent.Filter. From <temp_dir>/satellite/.vibeflow/patterns/*.md, keep only docs corresponding to the usage set. When in doubt for a direct dependency, include.
Target: .vibeflow/patterns/satellite-<satellite-name>/ in the main repo. Create if needed. Overwrite as needed.
Provenance. Prepend at the top of each merged file: > Patterns from satellite repo: <satellite-name> (ingested on YYYY-MM-DD for use by the main repo).
Write only filtered pattern docs. Do not copy the satellite's index.md or conventions.md.
Remove temp directory. Always do this, whether merge succeeded or failed.
Report: Satellite URL and name, that clone was removed, how many pattern docs were merged, remind about provenance.
Suggest: "Run gen-spec or prompt-pack — patterns from <satellite-name> are now available under .vibeflow/patterns/satellite-<satellite-name>/."
Rules: One repo per invocation. Clone is always ephemeral. Provenance is mandatory. Filter by use only.
.vibeflow/ and commit it — it's your project's living documentation."