AI가 지원하는 코드는 요구 사항, 예상되는 파일, 필수 테스트 또는 수락 조건(acceptance condition)을 조용히 누락한 채로 완성된 것처럼 보일 수 있습니다. 녹색으로 보이는 diff(차이점)가 해당 변경 사항이 이를 생성한 요청에 부합한다는 것을 증명하지는 않습니다.

이 튜토리얼은 SpecTrace for AI Coding을 사용하여 작은 증거 확인(evidence check) 도구를 구축합니다. JSON으로 요구 사항을 기술하고, 구현 파일과 테스트 결과를 해당 요구 사항에 매핑한 다음, CI 검토를 위한 Markdown 보고서와 기계 판독 가능한 JSON 및 SARIF 출력을 생성하게 됩니다.

이 유용한 경계는 의도된 것입니다: SpecTrace는 LLM(대규모 언어 모델)에게 코드가 좋은지 묻지 않습니다. 버전 0.1.0 구현체는 Python 표준 라이브러리를 사용하여 증거 맵(evidence map)이 검토자가 정의한 요구 사항을 충족하는지 확인합니다.

구축하게 될 내용

예제는 결제 감사 추적(checkout audit trail)을 모델링합니다. 한 가지 요구 사항은 허용(allow) 및 거부(deny) 결정이 기록되어야 함을 요구합니다. 증거 맵은 해당 요구 사항을 기록기(recorder) 파일, 통과된 테스트, 그리고 두 가지 수락 기준(acceptance criteria)에 연결합니다.

흐름은 다음과 같습니다:

requirements JSON + change map JSON
                    |
                    v
...

필수 링크가 하나라도 누락되면 검증기(verifier)는 발견 사항(finding)을 보고하고 0이 아닌 상태 코드를 반환합니다. 변경 맵(change map) 자체가 워크플로의 일부로 생성되고 검토된다면, 이 확인 절차는 풀 리퀘스트(pull request) 게이트로 사용하기에 적합합니다.

사전 요구 사항

Python 3.10 이상과 PowerShell, macOS 또는 Linux 셸이 필요합니다. 이 프로젝트는 MIT license에 따라 배포되며, 버전 0.1.0은 현재 런타임 시 Python 표준 라이브러리만 사용합니다.

저장소를 클론하고 디렉터리로 이동하세요:

git clone https://github.com/paladini/spectrace-ai-coding.git
cd spectrace-ai-coding

아래 명령어들은 저장소에 현재 문서화된 예제들을 사용합니다. 클론 후에는 API 키, 모델 계정 또는 네트워크 호출이 필요하지 않습니다.

1. 증거 입력값 검증하기

SpecTrace는 요구 사항 정의 (requirement definition)를 변경 맵 (change map)과 분리하여 유지합니다. 번들로 제공되는 스펙 (spec)에는 요구 사항 ID (requirement IDs), 예상 파일 패턴 (expected file patterns), 수락 레이블 (acceptance labels), 그리고 필수 테스트 이름 (required test names)이 포함되어 있습니다. 변경 맵은 파일, 테스트 상태, 그리고 수락 증거 (acceptance evidence)를 제공합니다.

입력 검증 명령을 실행합니다:

$env:PYTHONPATH = "$PWD\src"
python -m spectrace_ai_coding validate `
  --spec examples\checkout-audit-spec.json `
...

두 개의 요구 사항, 세 개의 파일 링크, 그리고 두 개의 테스트 결과가 검증되었다는 메시지가 표시되어야 합니다. 이 단계는 보고서 생성 전에 구조를 확인하고 상호 참조 (cross-references)를 점검합니다. 이는 기반이 되는 애플리케이션이 올바르다고 주장하는 것은 아닙니다.

중요한 설계 세부 사항은 공유된 요구 사항 ID (requirement ID)입니다. 파일이나 테스트는 해당 requirement_ids 리스트에 스펙의 ID가 포함되어 있을 때만 증거를 제공합니다. 알 수 없는 ID는 조용한 불일치 (silent mismatch)가 아니라 상호 참조 오류 (cross-reference error)로 처리됩니다.

2. 리뷰어 및 CI 아티팩트 생성하기

이제 검증을 실행하고 세 가지 출력 형식을 모두 요청합니다:

$env:PYTHONPATH = "$PWD\src"
python -m spectrace_ai_coding verify `
  --spec examples\checkout-audit-spec.json `
...

마크다운 (Markdown) 보고서는 사람이 검토하기 위한 용도입니다. 여기에는 요약, 추적 매트릭스 (trace matrix), 그리고 요구 사항 상세 정보가 포함됩니다. JSON 보고서는 개수 산출 및 객체 탐색이 필요한 스크립트에 유용합니다. SARIF 문서는 SARIF 2.1.0 형식을 따르므로, SARIF를 이해하는 CI 플랫폼은 다른 분석 결과와 함께 탐지 결과 (findings)를 표시할 수 있습니다.

번들 예제의 경우, 검증 결과 두 개의 요구 사항이 통과되었음을 출력하고 상태 코드 0을 반환합니다. 해당 결과를 유용한 검토 증거로 취급하기 전에 생성된 마크다운을 검사하십시오:

Get-Content build\spectrace-report.md

보고서는 체크아웃 감사 요구 사항(checkout audit requirement), 연결된 파일, 필수 테스트 및 수락 증거(acceptance evidence)를 식별해야 합니다. 이는 단순히 통과 횟수만 보여주는 것보다 검토자가 변경 맵(change map)이 실제로 무엇을 주장하고 있는지 확인할 수 있어 더 유용합니다.

3. 녹색 결과(green result)를 신뢰하는 대신 실패를 확인하기

검증기(verifier)는 누락된 증거와 통과된 증거를 구분합니다. 예를 들어, 변경 맵에 필수 테스트가 없는 경우, 해당 요구 사항은 missing-required-test 결과(finding)를 받습니다. 만약 테스트가 존재하지만 상태가 passed가 아닌 경우, required-test-not-passed 결과(finding)를 받습니다.

다른 검사 항목으로는 누락된 연결 파일, 커버되지 않은 예상 파일 패턴, 누락된 수락 증거 및 알 수 없는 요구 사항 ID 등이 있습니다. 구현 시 예상 파일에 대해 파일 패턴 매칭(file-pattern matching)을 사용하므로, src/checkout_audit/*.py와 같은 패턴은 최소 하나 이상의 연결된 경로와 일치해야 합니다.

이것이 핵심 교훈입니다: 추적성 도구(traceability tool)는 누락된 부분을 가시화할 수는 있지만, 증거를 직접 만들어낼 수는 없습니다. 테스트가 통과되었다고 말하는 변경 맵은 여전히 여러분의 워크플로(workflow)가 생성해야 하고 검토자가 신뢰해야 하는 주장(assertion)일 뿐입니다.

명세(spec)와 변경 맵(change map)을 분리하는 것이 중요한 이유

요구 사항 명세(requirement spec)는 검토 요청서입니다. 무엇이 참이어야 하는지, 어떤 증거가 존재해야 하는지를 기술합니다. 변경 맵(change map)은 구현 기록입니다. 어떤 파일이 변경되었는지, 어떤 테스트가 통과된 것으로 보고되었는지, 그리고 왜 수락 기준(acceptance criteria)이 충족된 것으로 간주되는지를 나타냅니다.

이 두 문서를 분리해 두면 코드 리뷰를 위한 안정적인 질문을 던질 수 있습니다: "이 변경 맵이 요구 사항을 증명하는가, 아니면 단순히 수정된 파일들을 기술하고 있는가?"

SpecTrace는 각 요구 사항에 대해 RequirementTrace를 구축합니다. 일치하는 파일, 테스트 및 수락 항목을 수집한 다음, 누락되거나 유효하지 않은 각 항목에 대해 결과(findings)를 적용합니다. 요구 사항은 해당 결과(findings) 목록이 비어 있을 때만 통과(passed)로 표시됩니다. 전역 교차 참조 오류(Global cross-reference errors) 또한 최종 결과에 포함됩니다.

대비해야 할 실패 모드(Failure modes)

유효한 JSON 파일이라도 취약한 증거를 기술할 수 있습니다

검증(Validation)은 데이터 모델과 참조를 확인합니다. 애플리케이션 소스 코드를 조사하거나, 변경 맵(change map)에 명시된 테스트를 다시 실행하거나, 요약 내용이 진실인지 확인하지는 않습니다. 맵을 검증기(verifier)에 의해 생성된 증명서(attestation)가 아닌, 검토용 자료로 취급하십시오.

통과된 추적(trace)이 코드 품질을 판단하지는 않습니다

이 프로젝트는 의미론적 정확성(semantic correctness)을 평가하기 위해 LLM을 명시적으로 사용하지 않습니다. 또한 제공된 증거 맵(evidence map) 이상의 정보를 바탕으로 실제 풀 리퀘스트(pull request)가 올바른지 판단할 수 없습니다. 이를 일반적인 테스트, 코드 리뷰 및 도메인 특화 검사(domain-specific checks)와 병행하여 사용하십시오.

입력값에 민감한 데이터가 포함될 수 있습니다

저장소의 보안 정책(security policy)에 따르면 요구 사항 문서, 파일 경로, 테스트 로그 및 AI 코딩 증거는 민감할 수 있다고 경고합니다. 이슈(issue) 및 테스트에는 합성 예시(synthetic examples)를 사용하십시오. 토큰, 비공개 소스 코드, 고객 경로 또는 운영 로그를 공개된 변경 맵(change map)에 배치하지 마십시오.

검증 실패는 의도적으로 테스트 실패가 아닙니다

요구 사항이 실패하거나 전역 결과(global findings)가 존재하는 경우 명령은 상태 코드 2(status 2)를 반환합니다. 이는 상태 코드 1(status 1)을 반환하는 입력 유효성 검사 오류(input validation error)와는 다릅니다. 귀하의 CI 래퍼(wrapper)가 수정 힌트(remediation hints)를 보고한다면 이 차이를 유지해야 합니다.

재현 가능한 검증

예시 명령을 실행한 후 저장소의 테스트를 실행하십시오:

python -m unittest discover -s tests

현재 저장소의 테스트 스위트(test suite)에는 7개의 테스트가 포함되어 있습니다. 번들된 명령 경로는 두 개의 요구 사항을 검증하고, Markdown, JSON 및 SARIF 파일을 작성하며, 확인된 작업 트리(working tree)에서 상태 코드 0(status 0)으로 통과합니다.

실제적인 CI 통합을 위해, 사양(spec)과 변경 맵(change map)을 저장소에 유지하고, 먼저 validate를 실행한 다음, verify를 실행하고 플랫폼의 SARIF 지원 기능을 사용하여 build\spectrace.sarif.json을 업로드하십시오. 정확한 업로드 동작은 플랫폼마다 다르며 SpecTrace의 범위를 벗어납니다.

FAQ

SpecTrace에 AI 제공자(AI provider)가 필요한가요?

아니요. Version 0.1.0은 Python의 표준 라이브러리 (standard library)를 사용하며 모델 API를 호출하지 않습니다.

이것이 테스트를 대체하나요?

아니요. 이 도구는 필요한 테스트들이 변경 맵 (change map) 내에 passed 상태로 표현되어 있는지 확인합니다. 도구 자체가 해당 테스트를 직접 실행하지는 않습니다.

AI가 생성한 변경 사항이 정확하다는 것을 증명할 수 있나요?

아니요. 이 도구는 제공된 증거 맵 (evidence map)이 구현된 규칙에 따라 선언된 요구 사항 (requirements)을 충족한다는 사실만을 증명합니다.

왜 SARIF를 생성하나요?

SARIF는 CI 및 코드 스캐닝 (code-scanning) 도구에 발견 사항을 표시하기 위한 공통 형식을 제공합니다. Markdown 및 JSON 파일은 로컬 검토 및 자동화에 여전히 유용하게 사용됩니다.

요점 (Takeaway)

AI 지원 개발을 위한 가장 작으면서도 유용한 안전장치는 종종 또 다른 모델 호출이 아닙니다. 그것은 요구 사항 (requirement), 이를 해결하는 파일, 이를 뒷받침하는 테스트, 그리고 검토자가 조사할 수 있는 수락 증거 (acceptance evidence) 사이의 구체적인 연결입니다.

SpecTrace는 그 연결을 결정론적 (deterministic)이고 검토 가능하게 만듭니다. 가치가 높은 요구 사항 하나로 시작하여, 증거 맵을 정직하게 유지하고, 팀이 각 증거의 출처를 설명할 수 있을 때만 검사 범위를 확장하십시오.

귀하의 AI 코딩 워크플로에서 변경 맵을 생성하고 검토하는 신뢰할 수 있는 방법을 찾으셨나요, 아니면 여전히 주로 diff와 테스트 출력에 의존하고 계신가요?

AI 지원 공개: 이 튜토리얼을 정리하고 편집하는 데 AI가 사용되었습니다. 명령어, 리포지토리 (repository) 상세 정보, 구현 주장 및 검증 결과는 공개된 SpecTrace 리포지토리와 그에 포함된 예제들을 바탕으로 확인되었습니다.