Best Practice Repository

This is a reference GitHub repository that implements the 5-Stage Strategy as CI workflows and configuration files. You can fork it for immediate use or copy configuration files into an existing project.

Stage 4c (agent and MCP tool governance) targets the agent on a developer workstation rather than CI, so it ships as config files (.mcp.json, .claude/settings.json) instead of a workflow. For enforcing it across an organization, see Agent and MCP Tool Governance.

Repository

github.com/trustedoss/ai-coding-best-practice

Repository Structure

ai-coding-best-practice/
├── README.md                          # badges + step-by-step explanation + guide links
├── src/
│   └── app.py                         # sample Python web app (with dependencies)
├── requirements.txt
├── Dockerfile
├── docker-compose.yml                 # app startup for DAST/AI fuzzing
│
├── CLAUDE.md                          # Stage 2: Embed AI rules + 4c: MCP server intake
├── .cursorrules                       # Stage 2: Cursor rules
│
├── .mcp.json                          # 4c: Approved MCP servers (currently empty)
├── .claude/
│   └── settings.json                  # 4c: Agent permissions (blocked reads, commands needing approval)
│
├── .gitleaks.toml                     # Stage 3: secret detection settings
├── .grype.yaml                        # Stage 3: SCA threshold settings
├── .semgrep.yml                       # Stage 3: SAST ruleset
│
├── renovate.json                      # Stage 5: Renovate auto-updates
│
├── k8s/
│   └── deployment.yaml                # sample target for IaC security scan (Checkov)
│
├── scripts/
│   └── ai-fuzz.py                     # AI fuzzing run script
│
└── .github/
    ├── dependabot.yml                 # Stage 5: Dependabot settings
    └── workflows/
        ├── secret-detection.yml       # Stage 3: Gitleaks
        ├── sast.yml                   # Stage 3: Semgrep
        ├── codeql.yml                 # Stage 3: CodeQL (PR + weekly)
        ├── oss-policy.yml             # Stage 3: syft + grype + licenses
        ├── iac-security.yml           # Stage 3: Checkov (Dockerfile/K8s)
        ├── container-security.yml     # Stage 3: Trivy
        ├── ai-review.yml              # Stage 4: findings-driven AI review (ANTHROPIC_API_KEY auto-enabled when configured)
        ├── ai-fuzzing.yml             # Stage 4: AI fuzzing (weekly + push)
        └── dast.yml                   # Stage 5: OWASP ZAP (Push to main)

Stage-by-stage Implementation

Stage 3 — CI/CD Auto Blocking

Area	Implementation File	Description
Secret Detection	`secret-detection.yml`	Gitleaks — Detects hardcoded API keys/tokens in every PR
SAST	`sast.yml`	Semgrep — OWASP Top 10 ruleset + custom rules
SAST (Deep)	`codeql.yml`	CodeQL — Static analysis on PRs and weekly schedule
SCA	`oss-policy.yml`	syft + grype — SBOM generation, CVE scan, and license checks
IaC Security	`iac-security.yml`	Checkov — Detects Dockerfile/Kubernetes configuration issues
Container Security	`container-security.yml`	Trivy — Docker image vulnerability scan

Stage 4 — AI Defense Layer

Item	Implementation File	Description
AI Code Review (4a)	`ai-review.yml`	Semgrep/grype findings → Claude validation and deep interpretation → PR comment
AI Fuzzing (4b)	`ai-fuzzing.yml`	Claude generates edge cases → runs app → detects 5xx errors (Push to main)
MCP governance (4c)	`.mcp.json`, `.claude/settings.json`	No MCP server auto-approved, secret reads blocked, human approval for egress and deploy commands

Stage 5 — Continuous Monitoring & Auto-remediation

Item	Implementation File	Description
Automatic Dependency Updates	`dependabot.yml`	Automatically creates weekly dependency update PRs
Automatic Patch Merge	`renovate.json`	Auto-merges Critical patches, notifies for Major updates
DAST	`dast.yml`	OWASP ZAP Baseline — dynamic scan on Push to main

Getting Started

1. Fork the repository

Bash
git clone https://github.com/YOUR-ORG/ai-coding-best-practice.git
cd ai-coding-best-practice

2. Add GitHub Secrets

Secret Name	Usage	Required
`ANTHROPIC_API_KEY`	AI code review, AI fuzzing	Optional

3. Open a PR to verify pipelines

Bash
git checkout -b test/pipeline-check
echo "# test" >> README.md
git commit -am "test: pipeline check"
git push origin test/pipeline-check

When a PR is created, six Stage 3 workflows run automatically. Stage 4 AI review is enabled automatically when ANTHROPIC_API_KEY is configured. AI fuzzing and DAST run on Push to main or weekly schedules.

Customization Points

File	What to Customize
`CLAUDE.md`	Reflect team license policy and prohibited package list
`.grype.yaml`	Adjust vulnerability thresholds (`high` ↔ `critical`)
`.gitleaks.toml`	Add internal organization pattern exceptions
`.semgrep.yml`	Add language/framework-specific rulesets
`renovate.json`	Adjust auto-merge scope and update cadence
`dast.yml`	After stabilization, change to `fail_action: true` for hard fail

5-Stage Strategy — Purpose and adoption sequence of each stage
30-Minute Quick CI/CD — Minimal starting point focused on SCA
AI Security Code Review — Semantic vulnerability detection with AI
DevSecOps — Organization-wide Pipeline Design — Multi-repository policy governance