셸과 COBOL 배치 호출 계층을 Kiro의 steering/skills로 자동 문서화하기

셸 스크립트가 COBOL이나 SQL을 호출하고, 그 셸이 또 다른 셸을 호출하는 경우—. 오랫동안 운영되어 온 배치 처리에는 이런 '호출 계층이 머릿속에만 존재하는' 자원이 흔합니다.

AWS Kiro의 steering(프로젝트의 전제 지식을 AI에게 가르치는 메커니즘)와 skills(반복적으로 사용하는 절차를 커맨드로 만드는 메커니즘)을 결합하여, 배치 호출 계층을 자동으로 문서화하는 시스템을 만들어 보았습니다. 본 기사에서는 가상의 배치 구성을 소재로 삼아 설계 과정과 구현 중 어려웠던 점들을 소개합니다.

설명을 위해 간략화한, 가상의 수주 출하 배치 시스템을 가정하겠습니다.

batch-sample/
├── shell/ # 시작 작업 + 업무 셸(.sh)
├── cobol/ # COBOL 소스(.cbl)
...

명명 규칙은 {블록2글자}{종류1글자}{일련번호3자리}로 했습니다. 블록은 수주(OR)・출하(SH)・재고(IV)・청구(BL)・공통(CM), 종류는 셸(S)・SQL(Q)・SQL*Loader 제어(C)로 정했습니다.

• steering: 리포지토리 구성・명명 규칙・호출 추출 패턴 등 '전제 지식' -
• skills: 콜 트리 문서 생성 절차・출력 포맷 등 '작업 절차'

전제 지식과 절차를 분리해 두면, 명명 규칙이 바뀌어도 steering만 수정하면 되고, skills 쪽의 절차는 변경할 필요가 없습니다.

분석 로직의 골격은 다음과 같습니다(본 기사용으로 간략화했지만, 실제로 작동시켜 아래 출력을 확인한 코드입니다).

function Classify-Line([string]$line, [hashtable]$vars) {
# 자식 셸 호출 (변수 경유): . $SHELLDIR/$BIN_NAME
if ($line -match '^\.\s+\\$?SHELLDIR\/?\$?([A-Za-z0-9_]+)\?\s*$') {
...
}

가상의 '수주 집계 배치(ORS010)'의 셸 스크립트를 이 로직에 실제로 읽히게 하면, 다음과 같은 Markdown이 생성됩니다.

# ORS010.sh 수주 집계 배치
## 호출 계층
- ORS010.sh 수주 집계 배치 ( shell/ORS010.sh )
...

자식 셸(SHS010.sh)은 내용을 전개하지 않고, 별도의 문서로 연결되는 링크에 그칩니다. 동일한 자식 셸을 여러 부모 배치가 호출하더라도, 문서가 중복 관리되지 않게 할 수 있습니다.

if [ $ENV_NAME = PRD ]; then . shell/CMS000_prd.sh
elif [ $ENV_NAME = DEV ]; then . shell/CMS000_dev.sh
fi

단순히 파싱하면, 운영(PRD)과 개발(DEV) 양쪽의 설정을 계속 읽어들이는 것처럼 보일 수 있습니다. 실행 시에는 둘 중 한 계통만 통하므로, '분기'임을 명시하는 표현으로 수정했습니다.

- [분기] 실행 환경에 따라 아래 두 가지 중 하나를 실행
- 운영(PRD): [ENV] CMS000_prd.sh
- 개발(DEV): [ENV] CMS000_dev.sh

구현 시에는 if부터 fi의 범위를 하나의 블록으로 읽어 나가고, 각 가지의 호출 라인만 Classify-Line에 전달하여 취합하는 방식으로 했습니다.

if ($s -match '^if\s+\[\s*\$ENV_NAME') {
$branches = New-Object System.Collections.Generic.List[string]
$j = $i
...
}

BIN_NAME=SHS010.sh
. $SHELLDIR/$BIN_NAME

단순한 정규 표현식으로는 $BIN_NAME이 무엇을 가리키는지 알 수 없어, 호출을 놓치게 됩니다. 대책으로, 동일 셸 내의 변수 할당(BIN_NAME=SHS010.sh)을 먼저 수집해 두고, 호출 지점에서 변수 이름을 실제 값으로 치환한 후 판별하는 2단계 처리를 했습니다.

# 1단계: 변수 할당 라인을 먼저 잡아 $vars에 기록
if ($s -match '^([A-Z_][A-Z0-9_]*)=([A-Za-z0-9_.]+)\s*$') {
$vars[$matches[1]] = $matches[2]
...
}

호출 이름을 가져온 직후, 그 이름의 종류(ENV/SHELL 등)를 판별하기 위해 다시 -match를 사용했더니, 얻어왔던 이름이 사라지는 사고를 겪었습니다.

# NG: 종류 판별의 -match로 $matches가 덮어씌워져 Name이 비게 됨
if ($line -match '^\.\s+\\\\$?SHELLDIR?/([A-Za-z0-9_]+\.sh)\s*$') {
$kind = if ($matches[1] -match '^CMS000') { 'ENV' } else { 'SHELL' } 
...

# OK: 이름을 먼저 변수에 임시 저장한 후, 두 번째 -match를 수행
if ($line -match '^\.\s+\\\\$?SHELLDIR?/([A-Za-z0-9_]+\.sh)\s*$') {
$name = $matches[1]
...

$matches는 PowerShell의 내장 변수로, -match를 사용할 때마다 전역적으로 덮어씌워집니다. 하나의 처리 과정에서 -match를 여러 번 사용해야 할 때는 필요한 값을 먼저 변수에 임시 저장한 후 다음 판별로 넘어가는 것이 안전합니다.

종료 로그 출력과 같은 공통 처리는 거의 모든 배치 스크립트의 끝부분에 등장합니다. 모든 배치 문서에 이 내용을 그대로 적으면, 정말 보고 싶은 단계 정보가 묻히기 때문에, 중복되는 공통 처리는 한 번만 표시하고 반복된다는 주석을 다는 방식으로 처리했습니다.

자동 생성은 '구조를 기계적으로 정확하게 파악'하는 데는 강하지만, '왜 이 조건 분기가 있는지', '장애 조사 시 가장 먼저 의심해야 할 부분은 어디인지'와 같은 업무적인 의미 부여까지는 할 수 없습니다.

따라서 장애 조사의 대상이 되기 쉬운 중요 배치만 자동 출력물을 기반으로 사람이 의미를 추가하는 '수동 보완 모드(手加筆モード)'를 준비했으며, 이미 수동 보완된 배치는 재생성 시 덮어쓰이지 않도록 보호 목록에 등록하는 2단계 구조로 만들었습니다.

• steering에는 '선행 지식', skills에는 '작업 절차'를 나누어 작성하면 규칙 변경에 강한 구성이 됩니다.
• 셸 스크립트를 정규 표현식으로 분석할 때는, 환경 분기 집약, 변수 경유 호출 해결, 공통 처리 중복 제거, 그리고 $matches 덮어쓰기 사고가 자주 발생하는 지점이 핵심 포인트입니다. '전부 자동 생성'과 '중요한 부분만 사람이 보완'을 분리하면 포괄성과 정확성을 모두 갖출 수 있습니다.

Kiro의 기본 기능(Spec・Vibe・Steering・Hook・Skills) 설명이나, 이 기사의 전체 내용(도서 소개 등)은 원문에 모아두었습니다.

→ 【Kiro 활용】셸×COBOL의 오래된 배치 자원을 자동으로 문서화하는 Skill을 만든 이야기 | Steering×Skills 실천 예시