RepoGuard

RepoGuard

The Architecture Guardian for AI-Assisted Codebases
RepoGuard aims to mitigate the challenges posed by AI coding assistants that can often create chaotic and non-compliant code structures. This tool provides an automated solution to enforce strict architectural guidelines across your repository, ensuring that AI-assisted coding remains efficient and aligned with established practices.

Problem Statement

AI coding assistants like Cursor, GitHub Copilot, and Claude Code can generate a vast amount of code in mere seconds. However, without stringent repository-level context, they frequently lead to:

• Bypassing Architectural Layers: Making direct database queries within UI components or API controllers.
• Reinventing Existing Helpers: Duplicating utility functions instead of reusing established code.
• Compromising Type Safety: Using loose typing with any or as any, which can lead to vulnerabilities.
• Exposing Credentials: Hardcoding sensitive information like API keys within the codebase.

Key Features

RepoGuard helps maintain architectural integrity by performing the following actions:

1. Generates strict, customized .cursorrules files for Cursor AI, as well as context files (CLAUDE.md) for Claude Code.
2. Executes inline audits for every Pull Request (PR), providing immediate feedback on architectural compliance.
3. Installs Git Pre-Commit Hooks and performs Architectural Health Checks.

Getting Started

Simply run the following command in any repository to initialize RepoGuard without requiring any installation:

npx repoguard-rules init

For global installation, use the following commands:

npm install -g repoguard-rules
repoguard init

CLI Commands

RepoGuard offers a suite of command-line interface (CLI) commands:

• Initialize AI context guardrails:

  npx repoguard-rules init
  

• Audit the codebase for architectural compliance:

  npx repoguard-rules audit
  

• Validate staged changes before committing:

  npx repoguard-rules check
  

• Install a pre-commit hook to prevent non-compliant commits:

  npx repoguard-rules install-hook
  

• Simulate an architecture review on AI-generated diffs:

  npx repoguard-rules review --sample
  

GitHub Action for PR Architecture Review

Integrating RepoGuard into your CI pipeline allows for automatic violation checks before merging:

# .github/workflows/repoguard.yml
name: RepoGuard Architecture Audit

on:
  pull_request:
    types: [opened, synchronize]

jobs:
  audit:
    name: Guard Architecture
    runs-on: ubuntu-latest
    steps:
      - name: Checkout Code
        uses: actions/checkout@v4
      - name: Run RepoGuard Architecture Review
        uses: repoguard-app/repoguard-action@v1
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          strict_mode: true

Built-in Architectural Rules

RepoGuard enforces the following architectural rules to safeguard code quality and maintainability:

• Layering Boundaries: Prevent direct database calls in controllers.
• Secret Leak Detection: Flags hardcoded sensitive information.
• Strict Type Safety: Prohibits the use of any.
• Clean Production Logs: Ensures structured logging usage.
• Next.js / SSR Safety: Prevents mismatches in server-side rendered content.
• SQL Injection Risk: Detects unsafe SQL operations.
• API Schema Validation: Enforces validation on incoming payloads.
• DRY Principle: Avoids unnecessary code duplication.

Performance

RepoGuard operates with zero external dependencies and can execute checks in less than 1.5 seconds, leading to minimal overhead during CI processes.

Contributing

Contributions are welcomed. Refer to the CONTRIBUTING.md document to learn how to add custom rules for additional frameworks.

RepoGuard is designed with care to support AI-assisted engineering teams, providing the necessary tools to maintain code quality and architectural integrity.