vibeguard: Command for Claude Code

Core Concept

• Preventing problems before writing code is 10 times less expensive than detecting and fixing them after writing.
• What is output is a constraint set (a list of things that cannot be done), not a pile of information.
• The constraint set guides all subsequent coding, eliminating the need to make architectural decisions during the implementation phase
• Each constraint must be verifiable — either by writing a guard script or by writing a test assertion

Selection

Skip preflight for docs-only work, small bugs, focused tests, and explicit mechanical changes. Run it only for major architecture, migration, cross-system policy work, or when the user explicitly requests preflight.

No routing packet, runtime snapshot, or execution handoff is required. Ask a focused question only when a missing decision would materially change the constraints.

Trigger Condition

• Major cross-cutting architecture or migration work
• Added new entry point (binary/service/CLI subcommand)
• Modify the data layer (database, cache, file storage)
• Cross-module refactoring

Guardrails

• No code modification, only reading and analysis
• No guessing - Uncertainty is marked as [UNCLEAR], and subsequently confirmed with AskUserQuestion
• Show the constraint set before coding when the user requested a planning checkpoint

Steps

1. Identify project type and structure

   • Detect languages/frameworks (Cargo.toml → Rust, package.json → TS/JS, pyproject.toml → Python)
   • Recognize monorepo/workspace structure (workspace members/packages/apps)
   • List all entry points (bin crate, main.ts, app.py, CLI commands)
   • Output: project overview (list of languages, frameworks, entry points)

2. Map shared resources

   • Search all data path constructs (data_dir, db_path, config_path, .join("xxx.db"))
   • Search all environment variables read (env::var, process.env, os.environ)
   • Search all port/address bindings (listen, bind, PORT)
   • Identify shared state (global singleton, shared database, message queue)
   • Output: Shared resource map (which resources are used by which entrances)

3. Extract existing schema

   • Error handling mode (Result vs unwrap, try-catch style)
   • Type definition location (core/ vs each app defines it individually)
   • Naming convention (snake_case/camelCase, prefix rules)
   • Division of module responsibilities (which module is responsible for what)
   • Output: pattern list

3.5. Reference Implementation Search (Skeleton Projects)

• Before implementing new functions, first search whether there are similar implementations inside and outside the project for reference.
• Search within the project: Use Grep/Glob to search for keywords, function names, and pattern names to confirm that no existing implementations are missing
• Search outside project (only for large cross-cutting changes):
  • Use WebSearch to search for "battle-tested" open source implementations (e.g. "<feature> implementation" site:github.com)
  • Evaluate the suitability of candidate implementations (license compatibility, dependencies, maintenance activity)
  • Not copy, but extract design decisions as input to constraint sets
• Output: Reference Implementation List

  [REF-01] In the project: src/core/xxx.ts already has similar XX logic and should be extended rather than newly created.
  [REF-02] Outside the project: The ZZ mode at github.com/xxx/yyy is worthy of reference (MIT, 1.2k stars, actively maintained)
  [REF-NONE] No reference implementation found, need to design from scratch
  

• If an existing implementation is found in the project → Generate L1 constraint: "Extend [REF-XX] instead of creating a new one"

3.6. Directory semantic verification

• List all subdirectory names of the project (first level + second level), and compare the built-in semantic mapping table to determine the consistency of responsibilities: