npx skills add https://github.com/supercent-io/skills-template --skill ai-tool-compliance

undefined

**소요 시간**: 5~15분 (프로젝트 규모에 따라 다름)

/compliance-improve 실행
       |
  1. 최근 verification-run.json 로드
       |
  2. FAIL 항목 추출 (rule_id + evidence)
       |
  3. 각 FAIL에 대해:
       |
     a. evidence 파일:줄번호에서 위반 코드 Read
     b. rule.remediation + rule.check_pattern.must_contain에서 수정 방향 도출
     c. 변경 전/후 코드 diff 생성
     d. Write로 수정 적용 (사용자 확인 후)
     e. 해당 룰만 재검증 (Grep 패턴 재실행)
     f. PASS 전환 확인
       |
  4. 전체 재검증 (/compliance-verify)
       |
  5. Before/After 점수 비교 출력
       |
  6. 잔여 FAIL 없으면 → P1 권장 요건 도입 가이드 제시

1. Glob(check_targets) → 대상 파일 수집
2. grep_patterns 매칭 → 해당 기능 사용 파일 식별
   - 매칭 0건 → N/A (해당 기능 미사용, 패널티 없음)
3. must_not_contain 검사 (exclude_paths 제외)
   - 매칭 발견 → 즉시 FAIL + evidence 기록
4. must_contain 검사
   - 전체 충족 → PASS
   - 부분 충족 → WARNING
   - 미충족 → FAIL

SC-001: grep signup/register -> assert role='guest' -> grep guestBlock/guestDeny -> assert exists
SC-002: grep fetch(https://) in client -> assert 0 hits -> grep gateway log -> assert cost fields -> assert cache check
SC-003: grep firebase/firestore in client/ -> assert 0 hits -> grep authMiddleware in functions/ -> assert exists
SC-004: grep catch blocks -> assert logAction in each -> grep roleChange -> assert auditLog
SC-005: grep res.json for raw text -> assert 0 hits -> grep guest response -> assert no model/cost info

undefined

undefined

/compliance-verify 실행
       |
  11개 P0 룰 전수 검증
       |
  점수 산출 (보안+권한+비용+로그)
       |
  +----+----+----+
  |         |         |
Green     Yellow    Red
  |         |         |
자동 승인  PM 승인   배포 차단
  |       대기      |
  v         |      수정 후
배포       v      재검증
        PM 확인     |
        |    |      v
      승인  반려   /compliance-improve
        |    |
        v    v
      배포  수정 후
            재검증

project/
├── compliance/
│   ├── rbac-matrix.yaml          # 5역할 x 게임/메뉴/기능 권한 매트릭스
│   ├── rules/
│   │   └── p0-rules.yaml         # 11개 P0 룰 정의
│   ├── log-schema.yaml           # 행동 로그 스키마 (Firestore/BigQuery)
│   └── cost-tracking.yaml        # 비용 추적 필드 정의
├── compliance-config.yaml        # 프로젝트 메타 + 검증 설정
└── compliance-report.md          # 검증 결과 리포트 (verify 실행 시 생성)

project:
  name: "my-ai-tool"
  type: "web-app"           # web-app | api | mobile-app | library
  tech_stack: ["typescript", "firebase", "next.js"]

verification:
  catalog_path: "compliance/rules/p0-rules.yaml"   # 기본값
  exclude_paths:                                     # 검증 제외 경로
    - "node_modules/**"
    - "dist/**"
    - "**/*.test.ts"
    - "**/*.spec.ts"

scoring:
  domain_weights:            # 합계 = 100
    security: 40
    auth: 25
    cost: 20
    logging: 15

gate:
  green_threshold: 90        # 90점 이상 = 자동 승인
  yellow_threshold: 75       # 75~89점 = PM 확인 필요
  p0_fail_override: true     # P0 FAIL 시 점수 무관 Red 판정

log_schema:
  version: "1.0.0"
  storage:
    primary: "firestore"           # 실시간 접근용
    archive: "bigquery"            # 분석/감사용
    retention:
      hot: 90                      # 일 (Firestore)
      cold: 365                    # 일 (BigQuery)

  fields:
    - name: userId
      type: string
      required: true
    - name: action
      type: string
      required: true
      description: "수행 동작 (ai_call, role_change, login, etc.)"
    - name: timestamp
      type: timestamp
      required: true
    - name: model
      type: string
      required: false
      description: "AI 모델명 (gemini-1.5-flash 등)"
    - name: inputTokens
      type: number
      required: false
    - name: outputTokens
      type: number
      required: false
    - name: estimatedCost
      type: number
      required: false
      description: "USD 기준 예상 비용"
    - name: status
      type: string
      required: true
      enum: [success, fail, timeout, error]
    - name: errorMessage
      type: string
      required: false
    - name: metadata
      type: map
      required: false
      description: "추가 컨텍스트 (bytesProcessed, cacheHit 등)"

cost_tracking:
  version: "1.0.0"

  ai_models:
    required_fields:
      - model              # 모델 식별자
      - inputTokens        # 입력 토큰 수
      - outputTokens       # 출력 토큰 수
      - estimatedCost      # USD 예상 비용
    optional_fields:
      - cacheHit           # 캐시 히트 여부
      - latencyMs          # 응답 지연 (ms)

  bigquery:
    required_fields:
      - queryId            # 쿼리 식별자
      - bytesProcessed     # 스캔 바이트
      - estimatedCost      # USD 예상 비용
    optional_fields:
      - slotMs             # 슬롯 사용 시간
      - cacheHit           # BQ 캐시 히트 여부

  cost_formula:
    gemini_flash: "$0.075 / 1M input tokens, $0.30 / 1M output tokens"
    gemini_pro: "$1.25 / 1M input tokens, $5.00 / 1M output tokens"
    bigquery: "$5.00 / TB scanned"

undefined

undefined

// functions/src/gateway/ai-gateway.ts
// 외부 API 직접 호출 금지 - 반드시 이 Gateway 경유

import { onCall, HttpsError } from "firebase-functions/v2/https";
import { verifyRole } from "../auth/rbac";
import { logAction } from "../logging/audit";
import { checkCache } from "../cache/cost-cache";

export const callAIModel = onCall(async (request) => {
  // 1. 서버 사이드 권한 검증 (AUTH-P0-003)
  const user = await verifyRole(request.auth, ["admin", "manager"]);

  // 2. Guest 접근 차단 (AUTH-P0-002)
  if (user.role === "guest") {
    throw new HttpsError("permission-denied", "Access denied");
  }

  // 3. 캐시 우선 조회 (COST-P0-011)
  const cached = await checkCache(request.data.prompt);
  if (cached) {
    await logAction({
      userId: user.uid,
      action: "ai_call",
      source: "cache",
      cost: 0,
    });
    return { result: cached, fromCache: true };
  }

  // 4. Gateway 경유 AI 호출 (SEC-P0-005)
  const result = await callGeminiViaGateway(request.data.prompt);

  // 5. 비용 로그 기록 (COST-P0-006)
  await logAction({
    userId: user.uid,
    action: "ai_call",
    model: result.model,
    inputTokens: result.usage.inputTokens,
    outputTokens: result.usage.outputTokens,
    estimatedCost: result.usage.estimatedCost,
  });

  // 6. 민감 원문은 서버에서만 처리, 클라이언트에는 참조 ID 반환 (SEC-P0-009)
  const responseRef = await storeResponse(result.text);
  return { responseId: responseRef.id, summary: result.summary };
});

bash scripts/install.sh [options]
  --dry-run        변경 없이 미리보기
  --skip-checks    의존성 확인 건너뛰기

bash scripts/verify.sh [--rule RULE_ID] [--output JSON_PATH]

bash scripts/score.sh [--input VERIFY_JSON] [--verbose]

bash scripts/gate.sh

수행 내용:
1. verify.sh + score.sh 순차 실행
2. P0 FAIL 존재 여부 확인
   - 1건이라도 있으면 → Red (exit 1)
3. 총점 기반 등급 판정
   - 90+ → Green (exit 0)
   - 75~89 → Yellow (exit 2)
   - 74 이하 → Red (exit 1)
4. 등급 + 점수 + 수정 필요 목록 콘솔 출력

**CI/CD 통합 예시 (GitHub Actions)**:

```yaml

<!-- TODO: System 결과 보완 예정 - GitHub Actions 워크플로우 통합 YAML -->

---