체크리스트 시스템

코드 수정 시 자동으로 품질/보안/문서 검증을 수행하고, 프로젝트별 리포트를 관리하며, /-msk-checklist-review로 미해결 항목을 검토하는 시스템입니다.

전체 흐름

코드/문서 수정
  ↓ PostToolUse Hook
  ↓ checklist-validator.sh 실행
  ↓ validators/*.sh (자동 검사)
  ↓ projects/{project}/latest.json 저장
  ↓
다음 턴
  ↓ <checklist-review> 태그로 AI에게 주입
  ↓ tmux 4줄: [code]15/35 +20r [doc]3/5 +2r 13:21
  ↓
사용자: /-msk-checklist-review
  ↓ 항목별 AI 설명 → 승인/수정/보류
  ↓ 리포트 갱신

41항목 7분류

보안 (Security) — 9항목

ID	항목	자동	설명
S1	하드코딩 시크릿	✅	API키, 비밀번호, 토큰 패턴 탐지
S2	SQL Injection	✅	Raw SQL, 바인딩 미사용
S3	XSS	✅	`{!! !!}`, `dangerouslySetInnerHTML`
S4	Authorization	AI	CRUD+READ 전체 권한 검사. 타 테넌트 자원은 404 반환
S5	테넌트 격리	✅+AI	Global Scope 적용, cross-tenant 차단
S6	입력 검증	✅	FormRequest 존재, `$request->all()` 금지
S7	CSRF/CORS	✅	CSRF 토큰, CORS 과다 허용 방지
S8	에러 정보 노출 방지	✅	production stack trace, internal path 차단
S9	의존성 취약점	✅	`composer audit` + `npm audit`

테넌트 격리 (S5)

Multi-tenant SaaS에서 가장 치명적인 사고는 cross-tenant 데이터 유출입니다. 모든 Eloquent 모델에 tenant scope가 적용되어 있는지 확인합니다.

안정성/운영 (Reliability) — 5항목

ID	항목	자동	설명
R1	에러 핸들링 패턴	AI	try-catch 일관성, 사용자 친화적 에러 메시지
R2	구조화 로깅	✅+AI	Log:: 호출에 context array 포함, 계층적 로그 채널
R3	PII 마스킹	✅	로그에 비밀번호, 토큰, 이메일 노출 금지
R4	Rate Limiting	✅	인증 엔드포인트에 throttle 미들웨어
R5	트랜잭션/멱등성	AI	DB::transaction, 중복 요청 방지

데이터/성능 (Data & Performance) — 5항목

ID	항목	자동	설명
D1	N+1 쿼리 방지	AI	Eager loading 사용
D2	DB 마이그레이션 안전성	✅	drop/rename 탐지, down() 존재, large table lock 경고
D3	인덱스 검토	AI	쿼리 패턴 대비 인덱스 존재
D4	캐싱 전략	AI	TTL, invalidation, Redis fallback
D5	환경 설정 정합성	✅	.env.example 키 vs config/ env() 교차 검증

품질 (Quality) — 7항목

ID	항목	자동	설명
Q1	SOLID 원칙	AI	단일 책임, 인터페이스 분리, 의존성 역전
Q2	DRY 원칙	AI	중복 코드 탐지
Q3	아키텍처 적절성	AI	Core/Plugin/프로젝트 계층 준수
Q4	하드코딩 방지	✅	config(), env() 사용, magic number 금지
Q5	타입 힌트	✅	함수 파라미터/리턴 타입
Q6	디버그 코드 제거	✅	dd(), dump(), console.log
Q7	외부 패키지 검토	AI	직접 구현 전 기존 솔루션 확인. 필요시 웹 검색 후 건의

국제화 (i18n) — 4항목

ID	항목	자동	설명
I1	하드코딩 문자열 금지	✅	`__()`, `trans()` 사용 확인
I2	타임존 처리	✅+AI	DB=UTC 저장, 표시=DISPLAY_TIMEZONE
I3	언어팩 구조	AI	번역 키 일관성, 누락 키, namespace 분리
I4	날짜/숫자 포맷	AI	Carbon locale, Number::format locale 기반

글로벌 제품 지향

모든 프로젝트는 글로벌 출시를 전제합니다. UI 문자열은 반드시 번역 함수를 통해 표시하고, 날짜/시간은 UTC 저장 + 사용자 타임존 표시 원칙을 따릅니다.

테스트 (Testing) — 5항목

ID	항목	자동	설명
T1	테스트 파일 존재	✅	새 코드에 대응 테스트
T2	테스트 커버리지	✅	최소 기준 충족
T3	엣지 케이스	AI	경계값, null, 빈 배열, 권한 없는 사용자
T4	코드와 함께 테스트	✅	파일 생성 시 테스트도 함께
T5	TDD (보안/Core)	AI	Core/Permission, Core/Tenant는 테스트 먼저

문서 (Documentation) — 6항목

ID	항목	자동	설명
DC1	README 업데이트	AI	기능 추가/변경 시 반영
DC2	API 문서화	AI	엔드포인트 추가 시 문서
DC3	문서 형식	✅	Markdown 구조, frontmatter
DC4	문서 정합성	AI	코드↔CLAUDE.md/AGENTS.md 동기화
DC5	설계 문서 유지	AI	_docs/design/ 과 코드 일치
DC6	Git 커밋 메시지	✅	`type(scope): subject` 형식

검증 레벨

새 작업 시작
    │
    ├─ 파일 3개 이하 & 10줄 미만?
    │       YES → 🟢 minimal (~10항목)
    │
    ├─ 기존 기능 수정/확장?
    │       YES → 🟡 standard (~25항목)
    │
    └─ 새 기능/아키텍처/DB 변경?
            YES → 🔴 full (41항목)

레벨은 변경된 파일 수와 종류에 따라 자동 감지됩니다.

tmux 표시

상태바 4줄 우측에 프로젝트별 체크리스트 상태:

[code]15/35 ok [doc]3/5 +2r 13:21

[code] = 보안 + 안정성 + 데이터 + 품질 + 국제화 + 테스트
[doc] = 문서
색상: 초록(ok), 노랑(+Nr), 빨강(!Nf)
프로젝트별 독립 표시 (tmux 세션 기준)

수동 리뷰 (`/-msk-checklist-review`)

tmux에서 +Nr이 표시될 때 실행:

사용자: /-msk-checklist-review
  ↓
AI: [1/N] SOLID 원칙 — 설명 + 관련 파일 + 분석
  → 선택: 1)통과 2)수정 3)보류 4)중단
  ↓
사용자: 1 (통과)
  → 리포트 갱신, 다음 항목으로
  ↓
... 반복 ...
  ↓
AI: 완료 보고 — CK 15/35 +20r → 25/35 +10r

자동 검사 스크립트

스크립트	검사 항목
`coding.sh`	하드코딩, 타입힌트, 디버그코드
`security.sh`	시크릿, SQLi, XSS
`validation.sh`	FormRequest 존재, `$request->all()` 금지
`dependency.sh`	`composer audit` + `npm audit`
`migration.sh`	drop/rename 탐지, down() 존재
`documentation.sh`	문서 형식
`git.sh`	커밋 메시지
`testing.sh`	테스트 존재, 커버리지

위치: .ai-core/scripts/validators/

설정

.ai-core/config/global.json:

{
  "checklist": {
    "enabled": true,
    "level": "standard",
    "code_extensions": "php|js|jsx|ts|tsx|py|go|java|rb|sh|rs|...",
    "doc_extensions": "md|mdx|txt|rst|adoc"
  }
}

근거 문서 매핑

각 체크리스트 항목에는 "왜 이걸 검증하는가"를 설명하는 근거 문서가 연결되어 있습니다.

체크리스트	근거 문서 (`_docs/ai-rules/global-rules/details/`)
보안 (S1~S9)	`security_concepts.md` + `tenant_isolation.md`
품질 (Q1~Q7)	`coding_standards.md` + `laravel_rules.md`
테스트 (T1~T5)	`testing_guide.md` + `specs/testing/*.md`
문서 (DC1~DC6)	`documentation_guide.md`
성능 (D1~D5)	`performance_optimization.md`
에러 처리 (R1)	`error_handling.md`
로깅 (R2~R3)	`logging_strategy.md`
Git (DC6)	`git_workflow.md`
국제화 (I1~I4)	`design/i18n-timezone-architecture.md`

양방향 연결

체크리스트 → 근거 문서: 각 domain/*.md 상단에 참조 링크
근거 문서 → 체크리스트: global_rules.md에 매핑 테이블

정기 점검 (Periodic Audit)

실시간 검증(코드 수정 시)과 별도로, 프로젝트 전체를 주기적으로 스캔하는 정기 점검 시스템입니다.

실시간 vs 정기 점검

구분	실시간 (기존)	정기 점검
트리거	PostToolUse / Stop Hook	cron / schedule / 수동
범위	변경 파일만	프로젝트 전체
검토 방식	Hook 자동 + AI review	항목별 심층 검토 (formal)
결과	`latest.json` (덮어쓰기)	`{날짜}_{agent}_{model}_report.md` (누적)
Multi-LLM	없음	primary + cross_check agents

구조

.ai-core/validation/checklists/audit/
├── schedule.json                ← 공통 기본값 + 레지스트리
├── schedules/                   ← 1파일 = 1스케줄
│   ├── weekly-workspace-projects.json
│   ├── biweekly-core.json
│   ├── monthly-infra.json
│   └── weekly-security-focus.json
├── targets/                     ← 1파일 = 1타겟 (20개)
│   ├── exam.how.json
│   ├── platform-core.json
│   └── ...
└── templates/                   ← 보고서 템플릿
    ├── audit-tasks.md
    ├── project-report.md
    └── summary-report.md

등록된 스케줄

스케줄	주기	Primary Agent	Cross-check	타겟
주간 Workspace	매주 월 09:00	claude/sonnet	—	workspace 7개
격주 Core	매월 1,15일 10:00	claude/opus	gemini, kilo	platform-core
월간 인프라	매월 1일 11:00	claude/sonnet	—	.ai-core, ops
주간 보안	매주 수 08:00	claude/sonnet	gemini	전체 workspace

실행 방식 (formal)

각 항목을 -msk-checklist-review와 동일한 패턴으로 1개씩 심층 검토합니다:

스케줄 실행
  ↓ Phase 1: 자동 검사 (validators 스크립트)
  ↓ Phase 2: AI 심층 검토 (1개씩 순차)
  │   ├── 코드 Read → 분석
  │   ├── cross_check 있으면 chorus 교차 검증
  │   └── AskUserQuestion (통과/수정/보류/중단)
  ↓ Phase 3: 종합 보고서 + 추이 비교

파일명 규칙

{YYMMDD-HHmm}_{agent}_{model}_{suffix}

예시	의미
`260413-0900_claude_sonnet_tasks.md`	진행 추적
`260413-0900_claude_sonnet_report.md`	보고서
`260415-1000_claude_opus_report.json`	기계용 (추이 비교)

Multi-LLM 교차 검증

"primary_agent": { "agent": "claude", "model": "opus" },
"cross_check": [
  { "agent": "gemini", "model": "gemini-3.1-pro" },
  { "agent": "kilo",   "model": "claude-opus-4-6" }
]

cross_check: [] → primary만 단독 실행
cross_check: [gemini] → primary + 1개 교차 검증
cross_check: [gemini, kilo] → primary + 2개 교차 검증

타겟 정의

각 타겟은 targets/{id}.json에 독립 정의:

{
  "id": "exam.how",
  "path": { "root": "workspace/exam.how", "web": "workspace/exam.how/web" },
  "type": "laravel",
  "scan": { "dirs": ["web/app/", "web/config/", ...], "exclude": ["web/vendor/", ...] },
  "check_override": {
    "skip_items": [],
    "extra_focus": ["S4", "S5", "T3"]
  },
  "tags": ["workspace", "laravel"]
}

스케줄에서는 ID로 참조: "targets": ["exam.how", "apis.how", ...]

구현 상태

정기 점검의 스케줄/타겟/템플릿 정의가 완성되었습니다. 실행 스킬(-msk-checklist-audit)과 chorus-cli 연동은 추후 구현 예정입니다.

체크리스트 자가 개선

AI가 작업 중 체크리스트에 추가할 만한 검증 항목을 발견하면, AskUserQuestion으로 제안합니다.

발견 상황	AI 행동
반복 실수가 체크리스트에 없음	해당 도메인에 항목 추가 제안
보안/성능 이슈를 수동으로 발견	자동화 가능 여부와 함께 추가 제안
기존 항목이 아키텍처와 불일치	항목 업데이트 또는 삭제 제안
프로파일 레벨 배정이 부적절	레벨 재배정 제안

승인 필수

사용자 승인 없이 체크리스트 파일을 생성/수정하지 않습니다. 항목 추가 시 프로파일(profiles/*.md) 레벨 매핑도 함께 업데이트해야 합니다.

전체 흐름​

41항목 7분류​

보안 (Security) — 9항목​

안정성/운영 (Reliability) — 5항목​

데이터/성능 (Data & Performance) — 5항목​

품질 (Quality) — 7항목​

국제화 (i18n) — 4항목​

테스트 (Testing) — 5항목​

문서 (Documentation) — 6항목​

검증 레벨​

tmux 표시​

수동 리뷰 (/-msk-checklist-review)​

자동 검사 스크립트​

설정​

근거 문서 매핑​

정기 점검 (Periodic Audit)​

실시간 vs 정기 점검​

구조​

등록된 스케줄​

실행 방식 (formal)​

파일명 규칙​

Multi-LLM 교차 검증​

타겟 정의​

체크리스트 자가 개선​

관련 문서​