ALPACA-FW #09｜Python을 이용한 기계 검사 관점・framework / project / trace / gate

서론

지난번에는 ALPACA-template의 tools/aissfw.py에 대해 CLI 전체가 어떻게 흐르는지 작성했습니다. Catalog를 읽고, 기계로 판별 가능한 것을 결정론적으로 검사하며, 결과를 공통 형식으로 반환합니다. 그 진입점으로서 하나의 Python CLI를 배치했다는 이야기입니다.

이번에는 그 안에서 빈번하게 사용되는 4가지 검사를 좀 더 구체적으로 살펴보겠습니다.

framework check

project check

trace check

gate preflight

이 4가지는 각각 Framework 자체, 프로젝트 산출물, 산출물 간의 연결성, Gate 통과 가능 여부를 별도의 검사로 보고 있습니다.

먼저, 4가지 검사를 한 장으로 정리하기

먼저 전체적인 그림을 내면 다음과 같이 분담되어 있습니다.

| 명령어 | 주로 보는 것 | 대략적인 질문 |
|---|---|
framework check | Catalog / Template / Role / Workflow / Framework 구조 | 애초에 검사하는 쪽의 Framework는 망가지지 않았는가 |
project check | 프로젝트 산출물의 존재・적용성・구조 | 현재 프로젝트에 필요한 산출물이 올바른 형태로 갖춰져 있는가 |
trace check | ID・관계・RTM | 요구사항 → 설계 → 시험 등의 연결이 끊기지 않았는가 |
gate preflight | 해당 Gate의 산출물・Evidence・승인・WVR | 이 상태를 Gate 심사로 가져갈 수 있는가

제 개인적인 생각으로는 다음 순서로 생각하는 것이 이해하기 쉽습니다.

Framework는 올바른가?
↓
프로젝트 산출물은 갖춰져 있는가?
...

여기서 중요한 것은, 마지막 두 가지는 CLI가 아니라는 것입니다.

기계 검사가 모두 통과해도 QA의 품질 판단이나 Project Owner의 진행 승인까지 자동으로 끝나는 것은 아닙니다. CLI는 '기계로 확인할 수 있는 부분까지'를 담당합니다.

framework check

――스스로가 망가지지 않았는지

가장 위에 있는 것이 framework check입니다.

이것은 개별 프로젝트를 보기 위한 명령어가 아닙니다. ALPACA-template 자체, 즉 검사에 사용하는 Framework 측이 일관성이 있는지를 보는 것입니다.

예를 들어, Catalog에서는 산출물 A가 필요하다고 적혀 있는데 Template가 존재하지 않는다거나. Role이나 Workflow에서 참조하는 파일이 사라진 경우. README에 적은 건수와 실제 정의 수가 맞지 않는 경우. 이런 상태에서 프로젝트에 '규칙 위반입니다'라고 말해도, 애초에 규칙 자체가 망가져 있습니다.

그래서 처음에 확인하고 싶었던 것은 상당히 단순한 이야기로, 사람이 점수를 매기기 전에 채점표가 올바른지 보자는 것이었습니다.

python tools/aissfw.py framework check

ALPACA-template에서는 Catalog, Template, 링크, Wrapper, README상의 정의 수, 게다가 버전이 진행된 후에는 Provenance 등도 이 검사 대상에 포함되었습니다.

편리해서 이것저것 추가한 결과, framework check 자체도 점차 무거워졌지만, 'Framework를 변경했다면, 먼저 Framework 자신을 검사한다'는 생각은 지금 돌이켜봐도 상당히 중요했다고 생각합니다.

project check

――프로젝트의 산출물이 '존재하는 것'만으로는 부족하다

다음은 project check입니다.

이것은 projects/<프로젝트명>/ 안을 봅니다. 다만, 단순한 파일 존재 확인이 아닙니다.

ALPACA-template에서는 적용 대상이 된 산출물에 대해 예를 들어 다음과 같은 부분까지 보았습니다.

| 관점 | 예 | |
|---|---|
존재 | 필수 산출물이 정해진 장소에 있는가 |
... | aiss-table, 필수 열이 올바른가 |
적용성 | Required / N/A / Replaced 가 프로젝트 계획과 일관성이 있는가 |
승인・증적 | 존재 문서에 필요한 기록이 있는가 |

즉 '파일이 있으니 OK'가 아니라, 공식적인 산출물로서 최소한의 형태를 유지하고 있는지를 보는 명령어입니다.

さらに工程途中에서는 --gate

을 붙입니다.

python tools/aissfw.py project check --project "projects/sample" --profile standard --gate QG3

여기서는 구현 도중에 상당히 신경 쓴 부분으로, QG3를 보고 싶은데 QG5나 QG6의 결과물까지 '아직 없습니다'라고 거절당하면 공정 중간에서는 사용할 수 없기 때문입니다.

따라서 --gate QG3

이라면, QG1부터 QG3까지 필요한 결과물을 누적하여 확인하고, 후속 Gate의 필수 결과물은 선제적으로 요구하지 않도록 했습니다.

반면, --gate

을 붙이지 않는 경우는 전체 라이프사이클을 대상으로 합니다. 이 두 가지를 같은 project check

안에서 처리할 수 있게 함으로써, 공정 중간 확인과 프로젝트 전체의 Full check를 구분하여 사용할 수 있도록 했습니다.

trace check

――결과물 간의 추적성(Traceability)을 본다

project check가 통과되었다고 해도 그것만으로는 충분하지 않습니다.

요건 정의서, 기본 설계서, 상세 설계서, 시험 사양서 등이 모두 존재하더라도, 그 요건이 어떤 설계에서 구현되고, 어떤 시험에서 확인되는지 알 수 없는 상태는 흔히 발생할 수 있습니다.

그래서 별도로 trace check를 만들었습니다.

python tools/aissfw.py trace check --project "projects/sample" --gate QG3

이것은 주로 ID와 관계를 봅니다.

• ID 중복
• 미정의 ID 참조
• 상류 근거가 없는 고아(Orphan)
• 전방 추적 누락(Forward Trace Missing)
• 후방 추적 누락(Backward Trace Missing)
• 원본 관계와 파생 RTM의 드리프트(Drift)

이전 기사에서도 언급했듯이, ALPACA-template에서는 RTM을 수기로 작성된 2차 원본으로 하지 않고, 각 결과물에 있는 관계를 모은 파생 인덱스로 만들었습니다.

따라서 trace check가 보는 것은 'RTM 셀이 채워져 있는지'가 아니라, 원본 측의 관계가 일관성이 있고 필요한 방향으로 추적할 수 있는지입니다.

여기를 project check에 전부 녹여내지 않은 이유는 질문 자체가 다르기 때문입니다.

project check
이 결과물은 공식적인 형태로 존재하는가?
trace check
...

비슷해 보이지만, 실제로 결함을 추적할 때는 분리되어 있는 편이 원인을 찾기 쉽습니다.

gate preflight

――Gate 심사로 가져갈 수 있는 상태인지 본다

마지막이 gate preflight입니다.

gate preflight는 Gate 심사의 전제 조건들이 기계적으로 갖춰져 있는지 집계하는 명령어입니다.

python tools/aissfw.py gate preflight --project "projects/sample" --gate QG3 --profile standard

예를 들어, 해당 Gate에 필요한 결과물(Evidence), 승인 상태, Waiver(WVR) 등을 확인합니다. QG2 이후라면, 직전 Gate의 Approved QGR이나 Project Owner의 진행 승인도 전제 조건이 됩니다.

여기까지 오면 project check와 상당히 비슷해 보입니다.

실제로 저 자신도 여기는 이해하기 어려운 설계였다고 생각합니다. 다만, 역할로는 다음과 같은 차이가 있습니다.

project check
프로젝트 결과물이 Framework 계약을 충족하는가?
trace check
...

즉 gate preflight는 '프로젝트가 올바른 구조인가'보다는, 이 심사 회차를 성립시키는 조건들이 갖춰졌는지를 보는 것입니다.

그리고 여기에서도 승인 자체는 만들지 않습니다.

gate preflight = PASS
≠
QA 합격 권장
...

여기를 함께 하지 않은 이유는, 기계 검사와 책임 있는 판단을 섞고 싶지 않았기 때문입니다.

공정 중간에서는 세 가지를 같은 Gate로 본다

ALPACA-template에서는, 공정 중간 확인 시 다음 세 가지에 동일한 Gate를 지정하도록 했습니다.

python tools/aissfw.py project check --project "projects/sample" --profile standard --gate QG3
python tools/aissfw.py trace check --project "projects/sample" --gate QG3
python tools/aissfw.py gate preflight --project "projects/sample" --profile standard --gate QG3

언뜻 보면 '세 번이나 비슷한 검사를 하는 건가?'라는 느낌이 듭니다.

하지만 저 자신에게는 각각 질문하는 바가 다릅니다.

① 필요한 산출물은 올바른 형태로 갖춰졌나?
② 상류부터 하류까지 제대로 연결되었나?
③ 증적이나 승인까지 포함하여 Gate 심사에 가져갈 수 있나?

이 세 가지를 분리하면, 실패했을 때도 원인을 파악하기가 쉬워집니다.

'산출물 자체가 부족한지', '산출물은 있지만 Trace가 끊겨 있는지', '내용과 Trace는 있지만 Evidence나 승인이 부족한지'. 전부 묶어서 check = false만 반환하는 것보다 훨씬 개선할 수 있습니다.

가상의 CSV 수정 사례로 보면 차이점이 명확합니다

예를 들어, '담당자가 매출 CSV를 다운로드할 수 있는 기능'을 만들고 있다고 가정하고, QG3 직전이라고 해봅시다.

기본 설계, 상세 설계, API 사양, 테스트 계획은 일련의 과정을 거쳐 완성했다고 합시다.

project check
에서 실패하는 경우

케이스 1: API 상세 사양서는 있지만, Template에서 필수인 오류 사양(Error Specification) 섹션이 빠져 있는 경우.

산출물은 있다
하지만 공식적인 구조를 충족하지 못했다

이것이 project check의 역할입니다.

project check는 통과했지만 trace check에서 실패하는 경우

케이스 2: 기능 요구사항 REQ-F-001도 있고 기본 설계 DSN-B-101도 있습니다. 하지만 이 둘의 관계가 기록되어 있지 않은 경우.

산출물은 있다
하지만 왜 이 설계가 존재하는지 추적할 수 없다

이것이 trace check의 역할입니다.

gate preflight에서 실패하는 경우

케이스 3: 구조도 Trace도 통과했지만, 필요한 설계는 갖춰져 있고 요구사항과의 관계도 추적할 수 있습니다. 하지만 직전 Gate 진행 승인이 없거나, 필요한 Evidence가 부족한 경우.

산출물은 만들어졌다
하지만 심사를 성립시키기 위한 전제가 갖춰지지 않았다

이것이 gate preflight의 역할입니다.

이렇게 나열해 보면, 네 가지로 나눈 이유가 조금 이해하기 쉬워집니다.

검사 커맨드는 기본적으로 임의로 수정하지 않는다

이 4가지 모두 읽기 전용(read-only)입니다.

ALPACA-template에서 명시적으로 쓰기를 허용한 것은, 원본과의 관계로부터 파생 RTM을 만드는 trace render --write 정도였습니다.

이것은 저 자신에게는 상당히 중요한 규칙입니다.

검사하는 도중에 툴이 산출물을 수정해 버리면, 마지막에 PASS하더라도 '처음부터 올바른 것이었는지, 중간에 툴이 수정한 덕분에 통과한 것인지' 알 수 없게 됩니다.

특히 QA나 CI에서 사용할 거라면, 검사하는 것은 검사에 충실해야 설명하기가 쉽습니다.

AI에게 전부 맡기면, '부족한 부분이 있어서 수정해 두었습니다. 문제없습니다'라는 움직임이 오히려 자연스럽습니다. 하지만 품질 확인으로서는 곤란할 때가 있습니다.

그래서 ALPACA-template에서는 만드는 측과 확인하는 측을 가능한 한 분리했습니다.

네 가지로 나눈 것이 좋았던 점

가장 좋았던 것은, 무엇이 잘못되었는지 분류할 수 있게 된 것입니다.

프레임워크 자체의 불일치와 프로젝트 측의 미비점이 섞이지 않습니다. 산출물의 구조적 결함과 Trace의 누락이 섞이지 않습니다. Gate 조건의 부족을 '설계서가 나쁘다'고 오해하지 않습니다.

AI에게 수정을 요청할 때도, 원인이 분리되어 있는 편이 지시하기 쉽습니다.

PROJECT_* 계열의 미비점
→ 산출물 구조/적용성을 수정한다
TRACE_* 계열의 미비점
...

'어디가 전반적으로 품질이 나쁘다'가 아니라, 기계적으로 확인할 수 있는 문제를 먼저 좁혀나갈 수 있게 된 것이 컸습니다.

한편으로는 사용자 입장에서 조금 이해하기 어렵다

하지만 완성판까지 사용해 보니 약점도 보였습니다.

우선, project check와 gate preflight의 경계는 이름만으로는 상당히 모호합니다.

게다가, Gate 앞에는 project check, trace check, 그리고 gate preflight을 순차적으로 실행하기 때문에, 사용자 입장에서는 '결국 전부 다 들어있는 check QG3 같은 것이 있으면 좋지 않을까?'라고 생각하는 것도 자연스럽습니다.

실제로 내부적인 책임 분리와 사용자에게 여러 개의 커맨드를 인지시키는 것은 별개의 문제입니다.

저는 이 기능을 만들면서, 내부적으로는 나누고 싶지만, 사용자에게는 하나의 검증으로 보여주고 싶다라는 두 가지 요구사항이 있다는 것을 깨달았습니다.

이는 aissfw.py가 커진 문제와도 연결됩니다. 책임은 개념상 분리되어 있음에도 불구하고, 구현은 하나의 Python 파일에 모여 있고, 사용자는 여러 개의 커맨드를 순서대로 호출합니다. 외부에서 보든 내부에서 보든, 경계가 조금씩 애매해지고 있었습니다.

기계 검사를 늘릴수록 책임 경계도 설계해야 한다

또 하나 배운 것은, Validator를 늘리는 것만으로는 품질 모델이 될 수 없다는 것입니다.

체크 항목을 늘리면 발견할 수 있는 결함은 늘어납니다. 하지만 '누가 수정하는지', '누가 의미를 판단하는지', '무엇을 가지고 진행 가능하다고 할지'가 모호하다면, 오류 목록만 늘어날 뿐입니다.

ALPACA-template에서는 적어도 다음의 경계는 나누려고 노력했습니다.

기계 검사
구조・정합성・증적 조건을 본다
Independent QA
...

이러한 생각은 지금도 상당히 중요하다고 생각합니다.

'AI가 모든 것을 체크해 줍니다'라고 할 수도 없고, 'Python이 PASS니까 품질 OK입니다'라고 할 수도 없습니다. 기계에 맡기는 판단과 사람이 책임지는 판단을 분리해야 합니다.

구(舊) ARPCA에서 그대로 온 메커니즘은 아니다

이 4가지 CLI 검사는 예전 ARPCA에 있던 메커니즘이 아닙니다.

구(舊) ARPCA에는 산출물을 정의하고, 리뷰하고, 품질을 평가하고, 다음 단계로 진행한다는 개념은 있었습니다. 다만, 당시에는 당연히 그것을 Python CLI로 결정론적으로 검사하는 수준까지는 하지 않았습니다.

따라서 이곳은 예전 방법론을 그대로 구현한 것이 아니라, 예전부터 하고 싶었던 '업무 상태를 모호하게 두지 않는다'라는 것을 AI와 Repository 중심의 개발에 맞춰 기계화한 부분이라고 생각합니다.

사람이 '아마 괜찮겠지'라고 판단했던 일부를, 기계가 동일한 기준으로 반복적으로 확인할 수 있게 만든 것입니다. 그 의미에서는 사상의 연장선상에 있지만, 구현 자체는 ALPACA-template에서 새로 추가한 것입니다.

지금이라면 개선하고 싶은 점

이 시리즈에서는 아직 현재의 ALPACA-FW로 어떻게 재설계했는지 답을 맞추기까지는 나아가지 않습니다. 여기서는 ALPACA-template를 완성했을 때 '다음에 고치고 싶다'라고 느낀 것만 적겠습니다.

한 가지는, 내부 검사 책임은 분리한 채, 사용자에게는 더 단순한 진입점을 보여주는 것입니다. 내부적으로는 Project, Trace, Gate를 개별적으로 평가하더라도, 사용자가 매번 그 순서를 기억할 필요가 없을 수도 있습니다.

또 하나는, Validator별의 입력・출력・의존 관계를 더 명확히 하는 것입니다. 하나의 거대한 CLI 안에서 '이 검사가 먼저 필요하다'라는 암묵적인 순서보다는, 기계적으로 실행 순서를 구성하는 것이 유지보수하기에 더 좋습니다.

그리고 구조 검사와 의미 검사를 더욱 명확하게 분리하는 것입니다. Python이 볼 수 있는 범위를 늘려도, '그 설계 판단은 타당한가'까지 같은 Validator에게 떠맡기지 않아야 합니다. 이 선 긋기는 무너뜨리지 않는 것이 좋다고 생각합니다.

참고로, 여기서 적은 것은 어디까지나 template 버전을 되돌아본 시점의 개선 요구사항입니다. 현재 ALPACA-FW에서 무엇을 남기고, 무엇을 분할하며, 어떻게 기계 계약으로 재설계했는지는 이 시리즈의 Phase C에서 Repository 구현을 보면서 다시 다룰 것입니다.

맺음말

ALPACA-template의 4가지 주요 검사는 같은 '체크'를 다른 이름으로 부른 것이 아닙니다.

framework check는, 검사하는 Framework 자체를 본다 -
project check는, 프로젝트 산출물의 존재・적용성・구조를 본다 -
trace check는, 산출물 간의 ID와 관계를 본다 -
gate preflight은, Gate 심사를 성립시키는 Evidence・승인 조건을 본다

그리고 그 다음에 독립적인 QA(Independent QA)와 Project Owner의 판단이 있습니다.

작업을 진행하는 도중에는 솔직히 '조금 너무 많이 나눈 것 같다'고 느끼는 장면도 있었습니다. 하지만 이렇게 한번 나누어 놓으니, '품질'이라는 한 단어 안에 사실은 다른 종류의 확인들이 섞여 있다는 것이 상당히 보이게 되었습니다.

다음 시간에는 이 네 가지 검사가 마지막으로 모이는 **Quality Gate(QG1~QG6)**를 다룰 예정입니다. 단순히 공정 끝에 체크리스트를 두었다는 것을 넘어, 왜 QA의 품질 권고와 Project Owner의 진행 승인을 분리했는지, 게이트를 '공정을 멈추게 하는 메커니즘'으로서 어떻게 설계했는지 깊이 파헤쳐 보겠습니다.

Discussion