← vibecodeqa.online

VibeCode QA — AI Skills Guide

Give this page URL to Claude, Codex, Cursor, or any AI coding assistant to teach it how to use VibeCode QA on your project.

What is VibeCode QA?

A code health scanner that runs 34 checks across 7 categories (Foundations, Quality, Testing, Architecture, Security, AI Readiness, AI Analysis) and generates a scored report. Zero config, runs with npx — no setup, works on TypeScript/JavaScript and Dart/Flutter projects.

Quick Start

1. Run your first scan

npx @vibecodeqa/cli

This auto-detects your stack, runs all 34 checks, and opens an HTML report in your browser. Output goes to .vibe-check/.

2. Fast mode (skip test execution)

npx @vibecodeqa/cli --skip-tests

3. CI mode (fail build if score < 60)

npx @vibecodeqa/cli --ci

4. SARIF output for GitHub Security tab

npx @vibecodeqa/cli --sarif

5. JSON output (pipe to other tools)

npx @vibecodeqa/cli --json

6. Monorepos (auto-detected)

npx @vibecodeqa/cli ~/my-monorepo

Auto-detects pnpm/npm/yarn/bun workspaces, turborepo, nx, lerna, and melos. Scans all packages, checks tsconfig strict per package, scopes confusion analysis per package. Supports bun.lock (text) and bun.lockb (binary). No config needed.

7. Delta reports (what changed)

npx @vibecodeqa/cli fix        # baseline → fix → final scan → delta
cat .vibe-check/delta.md       # markdown report of what changed

Every scan compares against the previous run. The --markdown and --pr-comment outputs include per-check score changes, fixed issues, and new issues.

8. Live monitor (re-scans on file changes)

npx @vibecodeqa/cli monitor

Full-screen TUI dashboard. Press c for settings (thresholds, panel toggles). Press q to quit.

Output Files

The 25 Checks

Foundations (23%)

Quality (26%)

Testing (15%)

Architecture (9%)

Security (16%)

AI Readiness (11%)

AI Analysis (Pro)

Five deeper, LLM-powered checks (weight 0 in the free score — informational):

How to Use the Results

Reading the JSON report programmatically

const report = JSON.parse(fs.readFileSync('.vibe-check/report.json', 'utf-8'));
console.log(`Score: ${report.grade} ${report.score}/100`);
for (const check of report.checks) {
  if (check.issues.length > 0) {
    console.log(`${check.name}: ${check.grade} — ${check.issues.length} issues`);
  }
}

Fixing issues with AI

Each issue in the report includes a copy-pasteable fix prompt. The format is:

Fix this issue in src/session.ts:240
warning: cognitive complexity 28 (max 15)
Check: complexity

Copy these directly into Claude, Codex, or your AI coding tool.

Configuration (.vcqa.json)

Create .vcqa.json in your project root to customize behavior:

{
  "checks": {
    "confusion": { "enabled": false },
    "standards": { "ignore": ["generated/**"] }
  },
  "ignore": ["vendor/**", "*.pb.ts"],
  "failUnder": 70
}

You can also put this in the "vcqa" field of package.json.

CLI commands

Output modes

Adding to GitHub Actions

name: VibeCode QA
on: [pull_request]
permissions:
  contents: read
  pull-requests: write
jobs:
  scan:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx @vibecodeqa/cli --skip-tests --ci --sarif --pr-comment --annotations
        env:
          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
      - uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: .vibe-check/report.sarif

For AI Agents: Workflow

When working on a codebase that uses VibeCode QA, follow this workflow:

  1. Run npx @vibecodeqa/cli --skip-tests --json to get a baseline score
  2. Read the JSON to understand which checks are failing and why
  3. Fix issues starting with the highest-severity ones (errors first, then warnings)
  4. Re-run after fixes to verify the score improved
  5. Aim for grade B (75+) minimum; grade A (90+) for production-ready code

Key patterns AI agents should know

Supported Stacks

Links

VibeCode QA — Code health scanner for the AI coding era. MIT license.