정산 분류·산정 레퍼런스#
settlement-invoice 스킬이 참조하는 판정 기준·산식·스키마입니다. 계약별 숫자(단가·적용률 등)는
여기 없습니다 — 그 값들은 항상 대상 프로젝트의 .claude/settlement/<slug>.config.md
에서 옵니다.
이 문서는 어떻게 판단하고 어떻게 계산하는가의 방법론만 다룹니다.
1. 분류 판정 트리#
그 변경은 무엇 때문에 일어났는가?
│
├─ 클라이언트 트래커(Jira 등)에 접수된 " 기능 요청 " · " 신규 요구 " 티켓이 출처다
│ └─▶ 청구 대상 — " 발주처 요청 신규 기능 "
│
├─ 클라이언트 트래커에 " 하자·버그 " 로 접수됐다
│ ├─ 실제로 기존 기능이 계약/설계대로 동작하지 않았던 것을 고쳤다
│ │ └─▶ 무상 처리 — " 하자 보수 "
│ └─ 접수된 하자를 조사하다 보니, 애초에 계약에 없던 신규 동작을 만들어야 했다
│ (예: " 버튼이 안 눌린다 " 는 신고였는데, 조사 결과 그 버튼 자체가
│ 계약에 없던 새 화면 흐름을 요구했다)
│ └─▶ 청구 대상 — " 하자 접수 건 중 계약범위 밖 추가 작업 "
│ (⚠️ 이 판정은 사람 확인 필수 — REFERENCE.md 만으로 확정하지 않는다)
│
├─ 로컬 설정의 " 이전 계약 범위 " 목록에 있는 조항이 다루는 작업이다
│ └─▶ 계약범위 제외
│
├─ 화면 동작·API 응답이 그대로인 내부 구조 변경이다
│ (리팩터링, 상태관리 전환, 코드 정리, 문서 정비)
│ └─▶ 계약범위 제외 — " 화면 동작이 달라지지 않는 내부 작업 "
│
├─ 자체 개발/CI/배포 환경 정비다 (빌드 파이프라인, 테스트 인프라, 시크릿 관리 등)
│ └─▶ 계약범위 제외 — " 사내 개발·배포 환경 "
│
└─ 자체 점검(코드 리뷰·보안 감사 등)에서 발견해 스스로 고친 것이다
(클라이언트가 신고하지도, 요청하지도 않았다)
└─▶ 계약범위 제외 — " 자체 점검에서 발견한 조치 "1-1. 요청 출처를 못 찾으면 어떻게 하나#
커밋/PR에 트래커 티켓 참조가 없으면 그 자체가 신호다 — 클라이언트가 요청한 것이 아닐 가능성이 높다. 자동으로 "청구 대상 아님"으로 밀어넣지 말고, 아래를 확인한다:
- PR 본문이나 이슈에 "화면설계서"·"기획 확정"·"요청" 같은 표지가 있는지 — 있으면 문서 인용이 출처를 대신한다.
- 없으면 "요청 출처 불명"으로 표시해 사람에게 보여준다. 사람이 확인해 트래커 참조를 나중에 붙이거나, 자체 발견으로 확정한다.
1-2. 하나의 PR이 여러 항목을 담고 있으면#
PR 하나가 청구 대상 기능과 계약범위 내 정비를 동시에 포함할 수 있다(예: "회원가입 절차 재편"이면서 동시에 "내부 상태관리 전환"도 같이 한 경우). 이럴 때는 PR을 쪼개서 두 항목으로 기재한다 — 하나의 PR = 하나의 청구 항목이 아니라, 하나의 변경 의도 = 하나의 항목이다. PR diff 안에서 "이 파일들은 기능 변경, 이 파일들은 순수 리팩터"를 구분할 수 있으면 그렇게 나눈다.
2. 공수 산정 기준 (M/D)#
"표준 공수"는 실제 소요 시간이 아니라 시장에서 통용되는 산정치다. 아래는 출발점이 되는 규모 구간표다 — 프로젝트마다 실제 스택·복잡도가 다르므로 로컬 설정에서 재정의할 수 있다.
| 규모 | 특징 | 표준 공수 (M/D) |
|---|---|---|
| XS | 문구·상수 교체, 단일 조건 수정, 단순 UI 값 변경 | 0.125 – 0.25 |
| S | 단일 화면 안의 동작 추가/수정, 단일 API 엔드포인트 | 0.25 – 0.75 |
| M | 여러 화면에 걸친 흐름 변경, 신규 API + 화면 1~2개 | 1 – 2.5 |
| L | 새 기능 계열 신설(여러 화면 + 서버 + 데이터 모델), 기존 절차 전면 재설계 | 3 – 8 |
| XL | 운영 데이터 대규모 교정, 신규 플랫폼 대응, 인증/보안 체계 신설 | 8 이상 (사유를 항목 설명에 반드시 남긴다) |
산정 시 diff 크기(파일 수·라인 수)만으로 판단하지 않는다. 화면 재설계 결정이 3줄짜리 설정 변경으로 구현될 수도 있고, 문구 하나가 다국어 대응까지 걸쳐 여러 파일을 건드릴 수도 있다 — 바뀐 "동작·화면·계층의 개수"를 기준으로 잡는다.
적용률#
청구 M/D = 표준 공수 × 적용률. 적용률은 계약마다 다른 협의 값이며 로컬 설정에서 가져온다.
기본값을 이 문서에 두지 않는다 — 잘못된 기본값이 실제 청구액에 그대로 반영되는 사고를 막기
위함이다. 설정에 없으면 스킬 실행 전에 반드시 사용자에게 확인한다.
3. CI/CD 인프라 사용료 (선택 모듈)#
자체 빌드 서버(self-hosted CI 러너)를 운영하는 프로젝트에서만 해당한다. 클라우드 CI(GitHub 제공 러너 등)만 쓰는 프로젝트는 이 절을 생략한다.
시장가 = 자체 러너가 처리한 컴퓨팅 시간(시간) × 클라우드 macOS 러너 공개 단가($/분) × 60 × 환율
적용 사용료 = 시장가 × 적용률 # 개발 공수와 같은 비율을 쓰는 것이 관례
실 결제분 = 클라우드 제공 러너로 실제 결제된 사용량 (있다면 그대로 더한다)
최종 인프라 사용료 = 적용 사용료 + 실 결제분
집계 대상은 잡 종류별(빌드·테스트·정적분석 / 실기기 검증 / 배포 / 화면 비교 검증 / 기타)로
나눠 실행 횟수·평균 소요·합계 시간을 표로 만든다. CI 플랫폼의 워크플로 실행 로그(예: GitHub
Actions API GET /repos/{owner}/{repo}/actions/runs)에서 기간·상태·소요시간을 뽑아 집계한다.
4. 구글 시트 컬럼 스키마#
TEMPLATES.md 의 워크북 생성 스크립트가 만드는 두 탭의 정본 스키마입니다. 기존 정산 관행과 호환되도록 열 이름을 고정합니다 — 임의로 열을 빼거나 순서를 바꾸지 않습니다.
탭 1 — "견적서" (요약)#
상단 블록(자유 서식, 공급자/발주처 정보 — 로컬 설정에서 채움) 아래 표:
| 열 | 내용 |
|---|---|
| 구분 | 카테고리 대분류 (예: "① 발주처 요청 신규 기능", "② 하자 접수 건 중 추가 작업") + 그 소계 행 |
| 설명 | 기능 영역(하위 그룹) 또는 개별 항목명 |
| M/D | 청구 M/D (소계 행은 그 그룹의 합계) |
| 금액 | 원화 금액 (소계 행은 합계) |
마지막에 "전체 수행 작업 산출액", "이전 계약 범위 내 작업 전액 제외", "하자 보수·내부 작업 무상 처리", "최종 청구액" 4행과 공급가액/부가세/합계 3행을 둔다.
탭 2 — "상세내역" (항목별 원장)#
| 열 | 내용 |
|---|---|
| NO | 일련번호 |
| 구분 | 탭 1 의 대분류와 동일 값 (청구 대상이 아닌 항목도 포함하려면 "무상"·"제외"를 추가 값으로 사용) |
| 분류 | 기능 영역(회원·결제·뷰어 등 — 로컬 설정의 분류 체계를 따름) |
| 기능 / 작업 | 항목명 |
| 적용 범위 | 영향받은 레이어(앱·서버·웹·관리자 페이지 등, 공백 구분 나열) |
| 요청 출처 / 판정 | 트래커 티켓 번호 + 저장소 이슈/PR 번호. 없으면 "자체 발견" 등 판정 근거 |
| 규모 | 위 §2 표의 XS/S/M/L/XL |
| M/D | 청구 M/D |
| 금액 | 원화 금액 |
⚠️ 청구하지 않는 항목(무상·제외)도 이 탭에 함께 적재하는 것을 권장한다 — M/D·금액을 0으로 두고 "구분"에 "무상"/"제외"를 명시하면, 시트 하나로 전체 작업 이력을 조회할 수 있어 나중에 "이 기간에 대체 뭘 했나"를 물었을 때 아티팩트를 다시 열지 않아도 된다.
5. 아티팩트 섹션 ↔ 시트 데이터 대응#
| 아티팩트 섹션 | 시트 원천 |
|---|---|
| 표지 최종 청구액 | 탭 1 "최종 청구액" 행 |
| Summary 3행 | 탭 1 소계 3종 |
| 주차별 카드 | 탭 2 를 "요청 출처 / 판정"의 반영 주차로 그룹핑 (별도 "주차" 열을 둬도 된다 — 로컬 설정에서 선택) |
| 작업 항목 리스트 | 탭 2 의 청구 대상 행 |
| 무상/제외 목록 | 탭 2 의 무상/제외 행 |
같은 데이터를 두 형태(사람이 읽는 웹 페이지 / 회계·이력 관리용 시트)로 내보내는 것이 이 플러그인의 핵심이다 — 한쪽만 갱신되고 다른 쪽이 낡는 일이 없도록, 항상 같은 분류 결과 표에서 두 산출물을 함께 생성한다.