SpecGuard

• 

  Intro

• 

  result1

• 

  result2

Inspiration

As a developer who has written many pull requests, I kept running into the same problem that every company and repository has its own engineering rules, but it is difficult to know whether I have satisfied them all before requesting review.

Rules can be scattered across contribution guides, documentation, CI configuration, and reviewer expectations. A developer might update a dependency but forget a lockfile, add an API route without the required validation, or miss a generated-file update. That inspired me to build SpecGuard.

What it does

SpecGuard is a contract driven pull request reviewer.

It turns repository specific engineering rules into an auditable review process. It evaluates a pull request with deterministic checks and AI-assisted reasoning, then links every finding to:

• The exact repository contract or rule
• The relevant changed code
• A concrete remediation step

It also tracks assessment coverage, so users can see which rules were checked, scoped out, or remain unassessed.

How we built it

We built SpecGuard with Codex and GPT-5.6 Terra, around the idea of treating repository rules as an explicit contract.

Codex helped us accelerate implementation, iterate on the product experience, and test the workflow against a real public pull request. GPT-5.6 Terra powers the AI-assisted judgment layer, helping evaluate repository rules that require code level context beyond deterministic checks.

The system:

• Reads and evaluates repository specific requirements
• Runs deterministic checks for objective rules
• Uses AI judgment for rules that need code-level context
• Preserves evidence so findings remain traceable
• Displays a clear pull request verdict and evidence index
• Recovers when AI output times out or is invalid
• Includes committed fallback scenarios so the public demo works without API credentials

For the demo, we used a real public pull request from the OpenAI Codex repository. SpecGuard identified a concrete issue: a dependency related change that required an accompanying Bazel lockfile update.

Challenges we ran into

The biggest challenge was making AI review trustworthy.

A generic AI code review can sound convincing while being difficult to verify. We needed every finding to be grounded in actual repository requirements, rather than vague best practices.

Reliability was another challenge. AI calls can time out or return malformed output, so we designed the review flow to recover from failures while clearly showing coverage and assessment status.

Accomplishments that we're proud of

We are proud that SpecGuard does more than produce a score or a list of suggestions.

It provides an evidence backed review experience where a developer or reviewer can quickly answer:

• What rule was violated?
• What code caused the issue?
• Why does it matter?
• What exact change is needed to fix it?

We are also proud that the demo works without requiring users to provide API credentials.

What we learned

We learned that useful AI review needs accountability.

The most valuable output is not simply “AI found an issue.” It is a finding connected to a repository rule, supported by evidence, and paired with a concrete remediation.

We also learned that coverage matters. Knowing which rules were assessed and being transparent about rules that were not, is essential for trust in automated review.

What's next for SpecGuard

Next, we want to expand SpecGuard with:

• GitHub pull request integration
• Configurable repository contracts
• Team-specific policy templates
• Pull request comments with linked evidence
• Additional deterministic rules and language support
• Review history and analytics for recurring contract violations

Our goal is to help developers catch repository specific issues before human review, so pull requests arrive more complete, more compliant, and easier to review.

Built With

• chatgpt-5.6
• codex
• githubapi
• next.js
• node.js
• react
• tailwindcss
• typescript
• zod