🇰🇷 한국어 | 🇺🇸 English

---

AI 코딩 Best Practice

Trusted OSS — AI 코딩 5단계 전략의 15단계를 파일로 구현한 참조 저장소입니다. 35단계는 GitHub Actions 워크플로우로, 2단계와 4c는 설정 파일로 동작합니다. fork해서 즉시 사용하거나, 설정 파일을 복사해 기존 프로젝트에 적용할 수 있습니다.

---

단계별 구현 현황

단계	내용	구현 파일
1단계	프롬프트 의존	— (도구 불필요)
2단계	AI 규칙 내재화	CLAUDE.md, .cursorrules
3단계	CI/CD 자동 차단	.github/workflows/ (전통 도구 6개)
4단계	AI 방어 레이어	ai-review.yml (findings-driven), ai-fuzzing.yml, .mcp.json, .claude/settings.json
5단계	지속적 모니터링·자동 교정	dependabot.yml, renovate.json, dast.yml

---

3단계 CI/CD 구성

워크플로우	도구	역할	PR	Push/Main
secret-detection.yml	Gitleaks	API 키·토큰 하드코딩 탐지	✅	✅
sast.yml	Semgrep	SQL 인젝션·취약 패턴 탐지	✅	—
codeql.yml	CodeQL	심층 정적 분석 (주 1회 포함)	✅	✅
oss-policy.yml	syft + grype	CVE 스캔 + 라이선스 검사	✅	—
iac-security.yml	Checkov	Dockerfile·K8s 보안 설정 검사	✅	—
container-security.yml	Trivy	Docker 이미지 취약점 스캔	✅	✅

4단계 AI 방어 레이어

단계	파일	도구	역할	실행 조건
4a	ai-review.yml	Claude API	Semgrep·grype findings → AI 검증·해석 → PR 코멘트	PR (ANTHROPIC_API_KEY 등록 시 자동 활성화)
4b	ai-fuzzing.yml	Claude + requests	AI 생성 엣지케이스로 5xx 탐지	Push to main · 주 1회
4c	.mcp.json, .claude/settings.json	Claude Code 설정	MCP 서버 allowlist, 시크릿 읽기 차단, 외부 통신·배포 명령 사람 승인	에이전트 세션마다

4c는 CI가 아니라 개발자 워크스테이션의 에이전트를 대상으로 하므로 워크플로우가 아닌 설정 파일로 구현합니다. 규칙과 서버 추가 절차는 CLAUDE.md에 있습니다.

5단계 지속적 모니터링·자동 교정

워크플로우 / 설정	도구	역할	실행 주기
dependabot.yml	Dependabot	의존성 업데이트 PR 자동 생성	주 1회
renovate.json	Renovate	Critical 패치 자동 병합	즉시·주 1회
dast.yml	OWASP ZAP	배포 후 동적 취약점 스캔 (Soft fail)	Push to main

---

빠른 시작

1. Fork

GitHub에서 이 저장소를 fork한 뒤 클론합니다.

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

2. PR을 열어 파이프라인 확인

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

GitHub에서 PR을 생성하면 3단계 워크플로우 6개가 자동 실행됩니다.

3. GitHub Secrets 등록

Secret 이름	용도	필수 여부
ANTHROPIC_API_KEY	4단계 AI 리뷰 (ai-review.yml), AI 퍼징 (ai-fuzzing.yml)	선택

ANTHROPIC_API_KEY를 등록하면 4단계 AI 방어 레이어가 자동으로 활성화됩니다. 별도 설정 변경 없이 다음 PR부터 findings-driven AI 리뷰가 동작합니다.

---

커스터마이징

파일	수정 포인트
CLAUDE.md	팀 라이선스 정책, 금지 패키지 목록, MCP 서버 추가 절차
.cursorrules	도구별 규칙 조정
.mcp.json	승인한 MCP 서버 선언 (버전 고정 필수)
.claude/settings.json	에이전트 권한 — 읽기 차단 경로, 승인이 필요한 명령
.grype.yaml	취약점 임계값 (high ↔ critical)
.gitleaks.toml	조직 내부 패턴 예외 처리 추가
.semgrep.yml	언어·프레임워크별 룰셋 추가
renovate.json	자동 병합 범위, 업데이트 주기
dast.yml	안정화 후 fail_action: true 로 변경해 Hard fail 전환

---

관련 가이드

• AI 코딩 5단계 전략
• 30분 완성 Quick CI/CD
• AI 보안 코드 리뷰
• AI 퍼징
• 에이전트와 MCP 도구 거버넌스
• DevSecOps — 전사 파이프라인 설계

---

AI Coding Best Practice

A reference repository implementing stages 1 to 5 of the Trusted OSS — AI Coding Strategy as files. Stages 3 to 5 run as GitHub Actions workflows; stage 2 and stage 4c are config files. Fork it for immediate use, or copy individual config files into your existing project.

---

Implementation Status by Stage

Stage	Description	Implementation Files
Stage 1	Prompt-only	— (no tools needed)
Stage 2	AI rule internalization	CLAUDE.md, .cursorrules
Stage 3	CI/CD auto-blocking	.github/workflows/ (6 traditional tools)
Stage 4	AI defense layer	ai-review.yml (findings-driven), ai-fuzzing.yml, .mcp.json, .claude/settings.json
Stage 5	Continuous monitoring & auto-remediation	dependabot.yml, renovate.json, dast.yml

---

Stage 3: CI/CD Configuration

Workflow	Tool	Role	PR	Push/Main
secret-detection.yml	Gitleaks	Detect hardcoded API keys & tokens	✅	✅
sast.yml	Semgrep	Detect SQL injection & vulnerable patterns	✅	—
codeql.yml	CodeQL	Deep static analysis (includes weekly scan)	✅	✅
oss-policy.yml	syft + grype	CVE scan + license check	✅	—
iac-security.yml	Checkov	Dockerfile & K8s security config check	✅	—
container-security.yml	Trivy	Docker image vulnerability scan	✅	✅

Stage 4: AI Defense Layer

Stage	File	Tool	Role	Trigger
4a	ai-review.yml	Claude API	Semgrep/grype findings → AI validation & interpretation → PR comment	PR (auto-activates when ANTHROPIC_API_KEY is set)
4b	ai-fuzzing.yml	Claude + requests	AI-generated edge cases to detect 5xx errors	Push to main · weekly
4c	.mcp.json, .claude/settings.json	Claude Code settings	MCP server allowlist, secret reads blocked, human approval for egress and deploy commands	Every agent session

Stage 4c governs the agent on a developer workstation rather than CI, so it ships as config files rather than a workflow. The rules and the server intake procedure are in CLAUDE.md.

Stage 5: Continuous Monitoring & Auto-Remediation

Workflow / Config	Tool	Role	Schedule
dependabot.yml	Dependabot	Auto-generate dependency update PRs	Weekly
renovate.json	Renovate	Auto-merge critical patches	Immediately · weekly
dast.yml	OWASP ZAP	Dynamic vulnerability scan after deployment (soft fail)	Push to main

---

Quick Start

1. Fork

Fork this repository on GitHub, then clone it.

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

2. Open a PR to verify the pipeline

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

Opening a PR on GitHub will automatically trigger all 6 Stage 3 workflows.

3. Register GitHub Secrets

Secret Name	Purpose	Required
ANTHROPIC_API_KEY	Stage 4 AI review (ai-review.yml), AI fuzzing (ai-fuzzing.yml)	Optional

Once ANTHROPIC_API_KEY is registered, the Stage 4 AI defense layer activates automatically. No additional configuration needed — findings-driven AI review starts on the next PR.

---

Customization

File	What to Modify
CLAUDE.md	Team license policy, prohibited package list, MCP server intake procedure
.cursorrules	Per-tool rule adjustments
.mcp.json	Approved MCP servers (version pin required)
.claude/settings.json	Agent permissions — blocked read paths, commands that require approval
.grype.yaml	Vulnerability threshold (high ↔ critical)
.gitleaks.toml	Add organization-internal pattern exceptions
.semgrep.yml	Add language/framework-specific rulesets
renovate.json	Auto-merge scope, update schedule
dast.yml	Switch to hard fail by changing fail_action: true after stabilization

---

Related Guides

• AI Coding 5-Stage Strategy
• 30-Minute Quick CI/CD
• AI Security Code Review
• AI Fuzzing
• Agent and MCP Tool Governance
• DevSecOps — Enterprise Pipeline Design