Pier_v1/.agents/skills/tea-versioning/SKILL.md

name, description

name	description
tea-versioning	전역 지침 산출물 저장·형식·버전 관리·변경 이력 — 파일 기반 산출(G4), DOC 유형축과 파일명(F1), 산출 형식 .md·xlsx 컨펌·스크립트 보관(F3), SemVer 승급 권한·두 자리 패딩·판 올리기 절차(F5), 변경 이력 표(F6). 산출물 파일명·버전을 정하거나 기존 산출물을 고치기 직전에 반드시 읽는다.

산출물 저장·형식·버전·변경 이력

전역 지침 스킬 — 코어 taskexecutionagent.md(v0.3.01) [스킬 지도]에서 호출된다. 담긴 조항: G4, F1, F3, F5, F6 아래는 v0.2.08 이전 코어의 조항 원문이다(무손실 이관). 조항 ID·번호는 코어와 공통이다. 코어의 요약과 어긋나 보이면 이 원문을 따르고, 그 사실을 [Step 5] 비고에 적는다.

G4. 파일 기반 산출 원칙

• 모든 문건은 파일로 저장하여 사용자가 직접 접근할 수 있게 한다. 저장 규칙은 [SECTION 3]을 따른다.
• 편집기 작업 사본(working copy)에만 반영하고 종료하지 않는다. 작업 사본을 사용한 경우에도 [Step 5] 종료 전 원본 경로에 저장되었는지 [V9]로 확인한다.
• 도구 호출 10회 이상이 투입된 조사·분석 중간 산출물은 결과 채택 여부와 무관하게 파일로 저장한다. 재조사 비용이 가장 크다.
• 문건 본문은 파일에 쓰고, 대화 화면에는 저장 사실과 다음 단계만 알린다. — v0.2.05 신설
  • 본문을 화면에 출력한 뒤 파일에도 저장하면 같은 내용이 두 벌이 된다. 사용자는 편집기에서 검토하므로 화면 출력분은 소비되지 않고 컨텍스트 비용만 이중으로 든다. ([G6])
  • 화면에는 저장 경로·버전·진행 상황·이번 분량의 요지·확인 요청만 남긴다. ([R10])
  • 사용자가 화면 표출을 명시적으로 요청한 경우에만 본문을 함께 출력한다.
  • 표·수치 등 검토에 즉시 필요한 소량 발췌는 예외로 화면에 낼 수 있다. 분량 기준은 요지 수준을 넘지 않는다.

F1. 산출물 저장 (DOC)

• 작성된 모든 문건은 DOC 폴더에 저장한다.
• 하위 분류는 유형축을 표준으로 한다. 표준 유형: 01_기획/ 02_분석/ 03_설계/ 04_실행/ 05_검증/ 06_보고서/ 99_기타/
  • 주제(공종·아이템 등)별 구분이 필요한 경우 2단계로 두되 유형이 상위가 된다: DOC/<유형>/<주제>/
  • 주제축과 유형축을 같은 계층에 혼재시키지 않는다.
  • 번호는 결번 없이 연속으로 사용하며, 유형 접두어는 위 7종 외로 임의 증식하지 않는다.
• 파일명은 [유형]_[핵심주제]_[YYYY-MM-DD]_v[버전].md 형식을 필수로 한다. (버전 규칙은 [F5] 참조)
• 파일명에는 폴더 경로·폴더 루트를 접두어로 포함하지 않는다. 폴더가 정상 생성·존재하는 경우 파일은 해당 폴더 안에 순수 파일명으로만 저장한다.
• DOC 루트에는 README·안내문 외의 산출물을 두지 않는다. 백업·복사본·임시 파일은 backup/·temp/로 이동한다.

F3. 산출 형식 (.md 원칙)

• 모든 문건은 Markdown(.md) 으로 작성한다. 아티팩트(artifact) 형태로 생성하지 않는다.
• 예외 — 스프레드시트: 표 형태로만 표현 가능하여 불가피하게 시트로 만들어야 하는 경우에만 .xlsx로 작성한다.
  • 단, .xlsx를 생성하기 전에 반드시 사용자에게 컨펌을 받는다. ([CLARIFICATION NEEDED] .md 표 대신 xlsx로 작성할까요?)
  • 프로젝트 성격상 xlsx가 기본 산출 형식인 경우(수량산출 등 셀 수식 기반), 프로젝트 단위 예외를 context-migration에 1회 등재하고 이후 건별 컨펌을 생략한다.
• 코드 관련 산출물(소스 코드, 스크립트, 설정 파일 등)은 모두 Code 폴더에 저장한다. 해당 언어의 표준 확장자로 저장하며, 코드에 대한 문서화·설명은 .md로 작성하여 DOC에 둔다.
• Code 폴더 내에서도 언어·모듈·기능별로 하위 폴더를 만들어 분리 저장한다.
• 산출물 생성·검증·변환에 사용한 스크립트는 결과 채택 여부와 무관하게 반드시 Code/에 보관한다. — v0.1.1 신설
  • 대상: 패치 스크립트, 검증 스크립트, 파서, 렌더러, 대조·집계 도구 등 일회성으로 작성한 것 포함.
  • 검증 스크립트가 보관되지 않은 경우 해당 [Step 3] 검증 결과는 무효로 간주하며, PASS 판정을 인용할 수 없다.
  • 코드베이스 파일(.html, .py, .js 등)과 바이너리(.pptx, .dxf 등)를 DOC/ 하위에 두지 않는다.
• 코드 작성과 관련된 세부 지침은 tea-coding 스킬을 반드시 참고한다. (정본 경로: .claude/skills/tea-coding/SKILL.md)

F5. 버전 관리 (Version Control)

• 모든 산출물은 아래 규칙에 따라 버전을 부여하고, 파일명 끝에 버전을 표기한다.

  • 파일명 형식: [유형]_[핵심주제]_[YYYY-MM-DD]_v[버전].md (예: 보고서_2분기실적분석_2026-07-23_v0.1.00.md)

• 버전은 vMAJOR.MINOR.PATCH (Semantic Versioning) 체계를 따른다.

• 문서 상단(또는 변경 이력 표)에 현재 버전과 변경 내역을 기록하며, 버전 변경 시 [Step 5]의 Prompt 로그에도 버전을 함께 남긴다.

• 자릿수별 승급 권한 (Bump Authority) — v0.2.00 개정. 버전 자릿수는 변경의 크기가 아니라 문서가 누구에게까지 나가는가를 나타낸다.

자리	표기	승급 조건	승급 권한
PATCH (세 번째)	v0.1.xx	기본값. 내용 수정·보완·오류 정정·조항 신설·구조 변경 등 공유 범위가 달라지지 않는 모든 개정	Agent 자율 ([G1-2] HOOTL)
MINOR (두 번째)	v0.x.00	내부 공유용으로 발행할 때	사용자가 요청한 경우에만 ([G1-2] HITL)
MAJOR (첫 번째)	vx.0.00	외부 공유용으로 발행할 때	사용자가 요청한 경우에만 ([G1-2] HITL)

• 개정은 언제나 PATCH가 기본값이다. v0.1.00을 고쳤으면 v0.1.01이 된다.
• Agent는 MINOR·MAJOR를 스스로 올리지 않는다. 변경 분량이 크든, 장(章)을 신설했든, 구조를 바꿨든 그 자체는 승급 사유가 아니다. 공유 범위가 달라지지 않았다면 PATCH다. (사고 사례: 「구조 변경 시 MINOR 승급」 규칙이 분량 판단만으로 MINOR를 올리게 만들어, 내부 공유 여부와 무관하게 두 번째 자리가 임의로 증가)
• 사용자가 "버전 올려줘"라고만 지시하면 PATCH로 올린다. 내부·외부 공유 목적이 있는지 명시되지 않았다면 [CLARIFICATION NEEDED]로 확인한 뒤 승급한다.
• 승급 시 하위 자리는 00으로 초기화한다. v0.1.07 → (내부 공유) → v0.2.00 → (외부 공유) → v1.0.00
• MINOR·MAJOR 승급 시에는 그 근거(사용자 지시 원문 또는 발행 사실)를 [F6] 변경 이력 비고와 [Step 5] DECISIONS에 함께 남긴다. 근거 없는 승급은 [Step 3] V4 FAIL로 판정한다.

상황	버전	승급 주체	설명
최초 작성	v0.1.00	Agent	새 문서의 시작 버전
내용 수정·보완·오류 정정	v0.1.01, v0.1.02 …	Agent	공유 범위 불변
장·절·시트·열 신설 등 구조 변경	v0.1.03 …	Agent	PATCH로 처리한다. 구조 변경은 승급 사유가 아니다
내부 공유용 발행	v0.2.00	사용자 요청	팀 내부 검토·배포를 위해 발행
내부 공유본 수정	v0.2.01, v0.2.02 …	Agent	검토 의견 반영
재차 내부 공유용 발행	v0.3.00	사용자 요청	내부 공유 회차가 바뀔 때
외부 공유용 발행 (최종본)	v1.0.00	사용자 요청	대외 확정·배포
최종본 수정	v1.0.01 …	Agent	공유 범위 불변
최종본의 재차 외부 발행	v2.0.00	사용자 요청	대외 개정판 배포

• PATCH는 두 자리 제로 패딩을 사용한다 (v0.1.09 → v0.1.10). — v0.1.1 신설
  • 사유: 패딩 없이는 v0.1.10이 v0.1.9보다 앞에 정렬되어 최신본 식별이 어긋난다. 실제로 이 문제를 회피하려고 -1·-5·b·c 같은 비표준 접미사가 발생했다.
  • 하이픈·알파벳 접미사(v0.1.9-5, v0.1.15b)를 금지한다. 기존 파일은 다음 개정 시 정규 버전으로 전환한다.
  • 버전 뒤에 자유 문자열을 덧붙이지 않는다(v0.3.1최종확인, v0.4.0_플로우형 등 금지). 성격 구분이 필요하면 [핵심주제]에 넣는다.
  • 파일명에 담당자명·최종)·(수정본) 등을 삽입하지 않는다.
• 파일명 내 버전 토큰은 1개만 허용한다. — v0.1.1 신설
  • 대상 산출물의 버전을 표기해야 하면 [핵심주제] 안에 하이픈으로 붙인다. 예: 진단보고서_모듈A-v0.1.0-문제점및개정내역_2026-07-29_v0.1.00.md
• 파일명에 표기된 버전과 문서 내 [F6] 변경 이력 표 최신 행의 버전은 항상 일치해야 한다. 불일치가 발견되면 [Step 3] V4(수치/데이터 정합성) 항목을 FAIL로 판정한다.
• "버전을 올리지 않고 기존 파일을 덮어쓰는" 처리를 하지 않는다. 사용자가 그렇게 지시하더라도 [CLARIFICATION NEEDED]로 변경 이력 소실 위험을 고지한 뒤 확인을 받는다. 선례가 있다는 이유로 자동 확대 적용하지 않는다.
• 판 올리기 절차 (Version Bump Procedure) — v0.2.05 신설. 구버전 보존은 선언만으로 성립하지 않는다. 아래 순서를 절차로 고정한다.
  1. 고치기 전에 먼저 복사한다. 현재 파일을 새 판 이름으로 복사하고, 그 새 파일을 편집한다.
     • 제자리에서 고친 뒤 사후에 복사하면 사본이 신판과 같아져 구판 본문이 남지 않는다. 보존이 성립하지 않는다. (사고 사례: 동일 프로젝트에서 같은 순서 역전이 3회 재발하여 v0.1.00·v0.2.00 본문 소실)
  2. 구판은 그 산출물이 속한 폴더의 backup/으로 옮긴다. — v0.2.06 개정
     • 폴더별 backup/이 표준이다. 예: DOC/02_분석/분석_X_2026-09-11_v0.1.01.md의 구판 → DOC/02_분석/backup/
     • 대상 폴더에 backup/이 없으면 만든다. 없다는 이유로 루트 backup/으로 보내지 않는다. ([SECTION 3] 폴더 자동 생성)
     • 기존 루트 backup/의 보관분은 재배치하지 않는다. 과거에 루트로 이관한 자료는 그 자리에 둔다. 지금부터 올리는 판만 폴더별로 보낸다.
     • 루트 backup/은 프로젝트 전역 백업(지침 적용 전 백업, 폴더 구조 개편 전 백업 등 특정 산출물 폴더에 귀속되지 않는 백업)에 계속 사용한다.
     • 이동은 mv(이동) 로 한다. 역방향 mv로 완전 원복 가능해야 한다.
     • rename으로 판을 올리지 않는다. 이름만 바꾸면 구판이 사라진다. ([G3-3] 복사 → 대조 → 삭제)
  3. 일괄 변환·자동 승급 스크립트는 <대상 폴더>/backup/<YYYY-MM-DD>/로 먼저 복사하고 시작한다.
     • 손으로 고칠 때는 파일을 하나씩 보므로 구판이 눈에 밟히지만, 스크립트는 이 절차를 통째로 건너뛴다. 스크립트의 첫 동작을 백업으로 고정한다. ([F13])
  4. 위 절차를 지키지 못했으면 [Step 3] V12(원본 무결성)를 FAIL로 판정하고 사유를 기재한다. 사후 정당화로 PASS 처리하지 않는다.
• 구버전 파일은 삭제하지 않고 보존한다. 정리가 필요하면 backup/으로 이동한다.
• 폴더 단위 버전과 파일 단위 버전을 병행하는 경우, 그 관계(예: 폴더=릴리스, 파일=내부 이력)를 context-migration에 1회 명문화한다.

F6. 변경 이력 (Change History)

• 모든 DOC 산출물은 문서 상단(제목 바로 아래)에 '변경 이력' 표를 반드시 포함한다. — v0.1.1 범위 개정
  • 적용 대상: DOC/ 하위 산출물, 지침·규정 문서, context-migration 중 개정이 반복되는 문서.
  • 적용 제외: prompt/ 로그. 로그는 Task 종료 시 1회 기록되는 append-only 감사 기록이므로 개정 이력 개념이 성립하지 않는다. 로그를 사후 보정한 경우에만 하단에 ## 로그 갱신 이력 절을 추가한다.
  • (근거: 실측 결과 산출물 부착률 90% vs 로그 3.2%. 로그 97%가 규정을 무시한 것은 규정과 실무의 범주 불일치를 뜻한다)
• 버전이 올라갈 때마다 이력 표에 한 행을 추가한다. 기존 행은 삭제하지 않고 오름차순으로 누적한다(최신 행이 맨 아래).
• 수정자는 [F4]에 따라 담당자명으로 기재한다.
• 이력 표 형식:

버전	수정일	수정자	주요 변경 내용	비고
v0.1.00	2025-06-05	홍길동	신규 작성	최초 버전
v0.1.01	2025-06-06	홍길동	2.3 항목 요구사항 문구 수정	내부 검토용 수정
v0.2.00	2025-06-07	김철수	초안 검토용으로 팀 공유	검토 요청
v0.2.01	2025-06-08	김철수	오탈자 수정 및 3.1 항목 이미지 추가	검토 의견 반영
v1.0.00	2025-06-09	김철수	최종본 확정 및 대외 공유용 배포	공식 배포