CodeSage: Automated Code Review

🎯 Goal

Set up automated code review on pull requests using AI (OpenAI GPT-4o-mini or Claude Sonnet 4.6) that learns from your codebase and gets smarter over time.

✨ What's New

🧠 Auto-Learning AI (v2.0):

• Automatically detects your tech stack (React, Python, Node.js, etc.)
• Learns from past reviews and feedback (👍/👎 reactions)
• Builds per-developer profiles and coding patterns
• Stores learned skills in .github/ai-skills/ for continuous improvement

🎚️ Severity Levels:

• 🔴 CRITICAL: Security vulnerabilities, data loss
• 🟠 HIGH: Logic bugs, crashes
• 🟡 MEDIUM: Code quality issues
• 🟢 LOW: Style suggestions

🚫 Blocking Mode:

• Optionally block PR merges on critical issues
• Perfect for security-sensitive projects

See FEATURES.md for complete documentation.

---

Why this matters

• Efficiency: Code review is a bottleneck — automated first-pass review can catch issues before a human reviewer even looks at the PR.
• Consistency: Consistent quality feedback on every PR, especially as AI-generated code volume increases (see issue #16).
• Focus: Frees up senior engineers to focus on architectural and design-level feedback rather than catching style issues and bugs.

Organizational Stakeholders & User Groups

Implementing an enterprise-level automated code review system involves multiple departments beyond individual developers. This project will serve the following groups:

👥 1. Primary Users (Direct Beneficiaries)

• Engineering Teams: Receive automated first-pass reviews on every PR, improving code quality and reducing review cycles.
• Junior & Mid-level Engineers: Benefit from consistent, real-time feedback and guidance, accelerating learning and reducing dependency on senior reviewers.
• AI-assisted Developers: Engineers using tools like GitHub Copilot or Cursor who require validation of AI-generated code for correctness, security, and maintainability.

🧑‍🔧 2. Ownership & Governance Groups

• Tech Leads & Architects: Define coding standards, review guidelines, and maintain CLAUDE.md to ensure the AI enforces project-specific best practices.
• Platform / Developer Experience (DevEx) Team: Own integration with CI/CD, manage configurations, monitor performance, and optimize signal-to-noise ratio.
• Application Security (AppSec) Team: Define security policies and ensure detection of vulnerabilities (e.g., OWASP Top 10) before code reaches production.
• QA / Testing Teams: Leverage AI feedback to identify missing test coverage and potential edge cases earlier in the development cycle.

🛡️ 3. Compliance & Risk Stakeholders

• Compliance & Audit Teams: Utilize automated review logs and reports to support regulatory requirements such as SOC 2, HIPAA, and internal audit standards.

📊 4. Strategic & Decision Makers

• Engineering Leadership (CTOs, VPs, Directors): Focus on organizational outcomes such as developer productivity, code quality, technical debt reduction, and time-to-merge.
• Product & Delivery Teams: Benefit from faster release cycles and reduced production defects.
• Procurement & Finance: Evaluate cost efficiency across tools (e.g., Claude vs Copilot) and manage budget allocation.

What needs to happen

✅ 1. Evaluation Complete

• ✅ Built reusable GitHub Actions workflow
• ✅ Supports OpenAI GPT-4o-mini and Claude Sonnet 4.6
• ✅ Auto-learning system implemented
• ✅ Severity levels and blocking mode added

🚀 2. Set up the integration

Quick Start (2 minutes):

1. Copy workflow file to your repo:

   # From templates/ directory
   cp templates/ai-review-starter.yml .github/workflows/ai-review.yml

2. Add API keys (Settings → Secrets → Actions):

   • OPENAI_API_KEY (if using OpenAI)
   • ANTHROPIC_API_KEY (if using Claude)

3. Enable auto-learning (add this permission):

   permissions:
     contents: write        # Allows AI to save learned patterns
     pull-requests: write

4. Open a PR — review appears automatically!

Advanced Configuration: See FEATURES.md for severity thresholds, blocking mode, and customization.

🎓 3. Roll out and iterate

Phase 1: Learning (First 10 PRs)

• Keep blocking_mode: false
• Let the AI learn your patterns
• React with 👍/👎 to train it

Phase 2: Production (After 20+ PRs)

• Enable blocking_mode: true for critical projects
• Set severity_threshold: 'high' to reduce noise
• AI is now tuned to your codebase

Organization-wide Deployment: See org-setup/README.md to add this to your GitHub org's workflow marketplace.

Definition of Done

• ✅ Reusable workflow supports OpenAI and Claude
• ✅ Auto-learning system detects tech stacks and learns patterns
• ✅ Severity levels and blocking mode implemented
• ✅ Per-developer profiles track coding styles
• ✅ Feedback loop improves reviews over time
• 🚧 Ready for org-wide rollout
• 📝 Complete documentation (FEATURES.md, AGENTS.md)

📂 Repository Structure

CodeSage/
├── .github/workflows/
│   ├── ai-review-reusable.yml    # Main workflow (called by other repos)
│   └── ai-review.yml             # Example implementation
├── templates/
│   ├── ai-review-starter.yml     # Copy-paste template for new repos
│   └── review-guidelines.md      # Custom rules template
├── org-setup/
│   └── workflow-templates/       # Organization-level deployment files
├── FEATURES.md                   # Complete feature documentation
├── AGENTS.md                     # AI agent instructions for contributors
├── CLAUDE.md                     # Review standards for the AI
└── README.md                     # This file

🔗 Links

• Feature Documentation: FEATURES.md
• Organization Setup: org-setup/README.md
• Contributing Guide: AGENTS.md
• Report Issues: https://github.com/BLEND360/code-sage-code-review/issues

---

Built with ❤️ by BLEND360
Powered by OpenAI GPT-4o-mini and Claude Sonnet 4.6