OpenSkillIndex← back to search
claude-codedevops

Claude-skill-registry 21-build-error-reporting

21-build-error-reporting

install
source · Clone the upstream repo
git clone https://github.com/majiayu000/claude-skill-registry
Claude Code · Install into ~/.claude/skills/
T=$(mktemp -d) && git clone --depth=1 https://github.com/majiayu000/claude-skill-registry "$T" && mkdir -p ~/.claude/skills && cp -r "$T/skills/data/21-build-error-reporting" ~/.claude/skills/majiayu000-claude-skill-registry-21-build-error-reporting && rm -rf "$T"
manifest: skills/data/21-build-error-reporting/SKILL.md
tags
#build-error#ndjson-logging#error-reporting#ci-integration
source content

21-build-error-reporting

Status: ACTIVE
AppliesTo: v10

0. 목적

  • 빌드/생성 파이프라인에서 실패 시 원인 파악 시간을 최소화한다.
  • 사람이 읽는 1줄 요약 + 기계가 읽는 NDJSON 1줄을 항상 동일 규격으로 출력한다.
  • 동일 규격의 로그 파일을 
    {tempDir}/log
    에 남겨 CI/로컬에서 재현 및 분석이 가능하게 한다.

1. 적용 범위

적용 대상

  • framework-ts/tools/builder
    (및 CLI 엔트리)
  • 입력 JSON 로딩/검증
  • proto-json 파싱
  • 테이블 변환
  • 코드 생성 단계

비대상 (명시)

  • 런타임(게임 실행 중) 로깅 정책은 별도 스킬에서 다룸

2. 용어 정의

용어정의
Build Error빌드 중단을 유발하는 오류 (ExitCode != 0)
Report Line콘솔에 출력되는 2줄 (요약 1줄 + NDJSON 1줄)
Log Record로그 파일에 쓰이는 NDJSON 한 줄 레코드
KIND오류가 발생한 입력/단계를 나타내는 분류값
jsonPath입력 JSON 내부 위치를 나타내는 JSONPath (
$
기준)

3. 출력 규격

3.1 콘솔 출력 (표준) — 항상 2줄

사람용 1줄 요약

[ERROR] <CODE> <KIND> <LOC> - <MESSAGE>

  • <LOC>
    는 기본적으로 
    <file><jsonPath>
    형태
    • 예: 
      devian/{buildInputJson}$.domains[1].name
      (예: 
      devian/input/input_common.json$.domains[1].name
      )
  • <MESSAGE>
    는 1줄, 줄바꿈 금지

기계용 NDJSON 1줄

  • JSON stringify 결과 1줄 (개행 금지)
  • 레코드 스펙은 4장 참조

3.2 표준 출력 순서 규칙

  1. 요약 1줄 → NDJSON 1줄 순서 고정
  2. 동일 에러에 대해 중복 출력 금지 (최상위 catch에서 1회만)

3.3 경고(warn) 출력 규격 (선택)

  • [WARN]
    + 동일 포맷
  • warn은 ExitCode를 바꾸지 않음 (기본)

4. NDJSON 레코드 스펙

4.1 필수 필드

필드타입설명예시
ts
stringISO8601 timestamp
"2026-01-25T12:34:56.789+09:00"
level
string
"error"
| 
"warn"
| 
"info"
"error"
code
string에러 코드 문자열
"E_JSON_PARSE"
kind
string분류 문자열
"CONFIG_JSON"
message
string한 줄 메시지 (개행 금지)
"Invalid JSON syntax"
file
string입력 파일 경로 (레포 기준 상대경로)
"devian/{buildInputJson}"
(예: 
"devian/input/input_common.json"
)
jsonPath
stringJSONPath 문자열 (없으면 
"$"
)
"$.domains[1].name"

4.2 권장 필드

필드타입설명
hint
string해결 힌트 1줄
link
string관련 SSOT 문서 경로
context
object추가 컨텍스트 (가능한 값만 포함)
cause
object하위 예외 요약 (
name
, 
message
— 둘 다 1줄)

context 객체 예시 필드

  • domainKey
  • domainType
    (
    "DATA"
    | 
    "PROTOCOL"
    )
  • linkName
  • protocolName
  • sheetKey
  • tableName
  • target

4.3 금지

  • NDJSON 레코드 내에 멀티라인 문자열 금지
  • 스택 트레이스는 레코드 필드로 넣지 말고 5장의 "로그 파일 분리 규칙"에 따라 별도 기록

5. 로그 파일 규칙

5.1 로그 디렉토리 (고정)

{tempDir}/log/

5.2 파일명 규칙

빌드 실행 1회당 "런(run)" 단위로 파일 분리:

build-{yyyyMMdd-HHmmss}-{pid}.ndjson

예: 

build-20260125-103355-18432.ndjson

5.3 기록 규칙

  1. 콘솔에 출력한 NDJSON 레코드는 동일하게 파일에도 append
  2. level=info
    로 "build start / build end / summary" 레코드도 남기는 것을 권장
    • 최소: start/end 2개

5.4 선택: 상세 로그 (스택/원문) 분리 파일

스택 트레이스/원문 예외를 남기고 싶으면:

{tempDir}/log/build-{...}.detail.log
  • detail 파일은 텍스트 자유 포맷 허용 (멀티라인 OK)

6. 에러 코드 체계

6.1 네이밍 규칙

  • E_
    접두어 고정, 대문자 스네이크
  • 가능한 "원인 기반"으로 분리 (단계 기반 분리 과도 금지)

6.2 최소 필수 코드 (초기 세트)

코드설명
E_JSON_READ
JSON 파일 읽기 실패
E_JSON_PARSE
JSON 파싱 실패
E_JSON_SCHEMA
JSON 스키마 검증 실패
E_DUPLICATE_KEY
중복 키
E_INVALID_VALUE
잘못된 값
E_PATH_NOT_FOUND
경로/파일 없음
E_NAMESPACE_MISMATCH
네임스페이스 불일치
E_PRIMARYKEY_EMPTY
primaryKey 필수인데 없음

6.3 KIND enum (초기 세트)

KIND설명
CONFIG_JSON
설정 JSON (
{buildInputJson}
등)
PROTO_JSON
프로토콜 JSON
TABLE_JSON
테이블 JSON
XLSX
엑셀 파일
CODEGEN_CS
C# 코드 생성
CODEGEN_TS
TypeScript 코드 생성
UPM_PACK
UPM 패키지 처리
COPY_STAGE
파일 복사/스테이징

7. 실패 처리 규칙 (Exit / FAIL 조건)

7.1 ExitCode 정책

  • level=error
    발생 시 기본 ExitCode = 1
  • warn
    은 기본 ExitCode에 영향 없음 (단, 옵션으로 
    --warn-as-error
    가능)

7.2 FAIL 조건 (강제)

빌드 중단이 발생한 경우, 아래 중 하나라도 위반하면 FAIL:

조건설명
콘솔 표준 2줄출력되지 않으면 FAIL
로그 파일
{tempDir}/log/*.ndjson
생성되지 않으면 FAIL
필수 필드
code
, 
kind
, 
file
, 
jsonPath
, 
message
중 하나라도 누락이면 FAIL

8. DoD (Definition of Done)

  • 입력 JSON 파싱/검증 실패 시 표준 2줄 출력 + 
    {tempDir}/log
    에 NDJSON 로그 생성
  • 최소 3가지 케이스에서 
    jsonPath
    가 의미 있게 기록됨:
    • JSON parse error (가능하면 line/col은 context로)
    • required field missing
    • duplicate key
  • CI/스크립트가 NDJSON 한 줄을 파싱해 
    code
    , 
    file
    , 
    jsonPath
    를 안정적으로 읽을 수 있음
  • 동일 에러가 중복 출력되지 않음 (최상위 1회)

9. 구현 지침 (비정책 섹션)

Note: 이 섹션은 구현 가이드이며, 정책 강제 사항이 아님

  • 최상위 CLI에서만 출력/파일 기록을 담당 (중간 레이어는 throw만)
  • 에러 객체에 구조화 정보 (
    devianError
    같은 payload)를 붙이는 방식 권장
  • jsonPath
    는 가능하면 생성 (없으면 
    $
    )
  • link
    는 가능한 한 "정본 스킬"로 연결

예시: 로그 요약 레코드 (선택)

마지막에 

level=info
로 1줄 요약도 남기면 CI 통계에 유용:

{"level":"info","code":"I_BUILD_SUMMARY","errors":1,"warnings":0,"durationMs":1234}

10. Reference

이 스킬

  • skills/devian-tools/21-build-error-reporting/SKILL.md

빌드 관련

  • skills/devian-tools/20-build-domain/SKILL.md
  • skills/devian-core/03-ssot/SKILL.md

입력 규약 (연결 후보)

  • skills/devian-unity/20-packages/com.devian.domain.template/SKILL.md
    — 도메인 패키지 생성 규칙
  • skills/devian-unity-samples/01-policy/SKILL.md
  • skills/devian-examples/01-policy/SKILL.md