파일과 근거 기록 준비

근거를 찾을 수 있는 위치부터 만듭니다

회의에서 “다들 불편해합니다”라는 설명을 들었는데 누구의 어떤 사례인지 찾을 수 없다면 다음 판단을 이어가기 어렵습니다. 파일 기록 공간은 문서를 많이 보관하려는 장치가 아니라 판단의 출발점을 다시 찾는 장치입니다. 이번에는 제공된 가상 문의 E001과 그 문의를 바탕으로 한 조사 범위 결정 D001을 다른 폴더에 두고 서로 연결합니다. 파일 검사는 누락과 문법 오류를 알려 주며 실제 사실 여부는 사람이 읽습니다.

실습 패키지의 루트는 압축을 푼 뒤 workspace.json과 check.sh가 함께 보이는 폴더입니다. 상대 경로는 이 위치를 기준으로 해석됩니다. evidence/E001.json은 evidence 폴더 안의 E001.json이라는 뜻입니다. 파일명이 같은 복사본이 다운로드 폴더에 여러 개 있으면 고친 파일과 검사한 파일이 달라질 수 있습니다. 명령을 실행하기 전에 pwd로 위치를 보고 ls로 파일 이름을 확인하는 이유가 여기에 있습니다.

폴더 구조와 파일 이름을 읽습니다

workspace.json은 프로젝트 이름과 두 폴더의 이름을 연결합니다. evidence 폴더에는 근거를, decisions 폴더에는 결정 기록을 둡니다. E001은 근거의 식별자이며 이름이나 학번이 아닙니다. D001은 결정의 식별자입니다. 파일명을 바꾸거나 식별자를 재사용하면 뒤에서 같은 자료를 가리키기 어려워집니다. 오류가 있는 기록도 삭제해 번호를 돌려 쓰기보다 수정 이유를 남기는 편이 연결을 보존하기 쉽습니다.

workspace.json
evidence/E001.json
decisions/D001.json
check.sh
check.py

시작본에는 decisions/D001.json이 없습니다. 정상 자료 두 개를 그대로 두고 빠진 결정 기록을 완성하는 과제입니다. 폴더가 없는 상태에서 편집기의 저장 버튼을 누르면 다른 위치에 저장될 수 있으므로 decisions 폴더를 먼저 만듭니다. 명령을 이해하지 못한 채 저장소 전체에서 실행하기보다 이 실습 루트 하나를 기준으로 위치와 파일 이름을 반복해서 확인합니다.

JSON은 항목 이름과 값을 연결합니다

JSON 객체는 중괄호로 둘러싸고 항목 이름과 문자열 값에 큰따옴표를 씁니다. 콜론은 이름과 값을 연결하고 쉼표는 항목을 나눕니다. 마지막 항목 뒤에는 쉼표를 넣지 않습니다. evidenceId의 철자를 evidenceID로 바꾸면 사람 눈에는 비슷해도 검사기는 다른 이름으로 읽습니다. 파일은 UTF-8 텍스트로 저장하며 워드 프로세서의 문서 형식을 사용하지 않습니다.

{
  "id": "D001",
  "text": "승인 확인 흐름을 조사합니다.",
  "evidenceId": "E001"
}

위 객체에서 id는 현재 결정의 이름이고 evidenceId는 이 결정이 참고하는 근거의 이름입니다. E001을 썼다는 사실은 그 근거로 결론이 증명되었다는 뜻이 아닙니다. E001은 가상 신청자가 승인 여부를 다시 문의한 사례입니다. 한 사례를 참고해 다음 조사 범위를 정할 수 있지만 실제 신청자 전체의 문의 비율을 계산할 수는 없습니다. 참조의 존재와 판단의 타당성은 서로 다른 검토 대상입니다.

기록 유형과 출처를 보존합니다

근거 파일의 kind가 scenario인 이유는 교육용으로 제공된 상황이기 때문입니다. 실제 관찰을 하지 않고 fact로 바꾸면 파일 형식은 비슷해도 자료의 성격을 왜곡합니다. 이후 실제 조사에서는 관찰 사실, 사용자 의견, 작성자의 추측을 구분할 것입니다. 지금은 source에 제공된 가상 사례라고 남기고 text에는 그 사례에서 일어난 행동만 적습니다. 추측하는 원인은 결정 이유나 별도 가설에 둡니다.

기록을 수정할 때는 먼저 원문과 요약의 역할을 구분합니다. 이번 작은 실습은 하나의 짧은 제공 사례만 보관하므로 원문 복사본을 더 만들 필요가 없습니다. 미션에서는 근거와 결정을 한 제출 JSON에 묶지만 식별자는 유지합니다. 폴더가 달라져도 같은 E001이 같은 사례를 가리키게 하면 다음 모듈에서 새 조사 기록을 추가할 때 자료의 출발점을 설명할 수 있습니다.

오류 메시지를 수정 행동으로 바꿉니다

bash check.sh는 셸 스크립트를 읽고 Python 검사기를 실행합니다. FAIL 뒤의 파일명과 필드명이 수정 위치입니다. 파일 누락이면 JSON 내용을 고칠 차례가 아니라 파일이 존재하는지 확인할 차례입니다. JSON 또는 UTF-8 오류라면 파일이 있어도 읽을 수 없는 상태입니다. 빈 값은 해당 항목이 없거나 문자열이 공백뿐인 상태입니다. 근거 참조 오류는 연결할 식별자가 약속과 다르다는 뜻입니다.

터미널이 check.sh: No such file or directory를 표시한다면 검사 내용에 들어가기 전에 경로를 확인합니다. python3: command not found라면 데이터의 잘못이 아니라 실행 환경을 준비할 문제입니다. 검사 실패: 1처럼 요약이 나온 뒤 종료 코드가 1이면 의도한 제출 검사 실패입니다. 화면에 문장이 출력되었다고 모두 통과한 것은 아닙니다. 수정 뒤 같은 명령을 다시 실행해 실패가 사라지는지 봅니다.

python3 -m json.tool decisions/D001.json은 JSON 문법을 읽어 정돈된 내용을 출력합니다. 이 명령은 evidenceId가 실제 존재하는지 확인하지 않으므로 문법 통과 뒤에도 check.sh를 실행합니다. 반대로 check.sh를 통과해도 문장 속 근거가 부풀려져 있는지, 다른 참여자를 알아볼 정보가 섞였는지는 사람이 읽습니다. 검사 목적을 구분하면 어떤 도구가 알려 주지 못한 내용을 빠뜨리지 않을 수 있습니다.

읽을 수 있는 인계 자료로 마무리합니다

완료할 때는 루트 위치, 변경한 파일, 실행한 명령, 실패 수를 짧게 기록합니다. ‘잘 됩니다’보다 ‘D001 파일을 만들고 evidenceId를 E001로 지정한 뒤 bash check.sh를 실행했다’가 다른 사람이 따라 하기 좋습니다. 실습 파일에는 실제 이름이나 연락처를 더하지 않습니다. 근거 내용을 보충하고 싶다면 제공 자료에 없는 사실을 만들어 넣는 대신 조사에서 확인할 질문으로 남깁니다.

폴더와 식별자의 이름은 작은 팀의 공유 언어입니다. 의미 없는 이름이라고 느껴져도 이름을 바꿀 때는 참조하는 곳을 함께 확인해야 합니다. 다음 사람이 E001을 읽고 D001의 판단을 재검토할 수 있는 상태가 이번 레슨의 결과입니다. 새 프로그램을 작성하는 능력보다 위치를 확인하고 메시지를 읽어 필요한 파일 하나를 정확하게 고치는 능력을 먼저 익힙니다.

pwd
ls

bash check.sh

FAIL decisions/D001.json: 파일 누락
검사 실패: 1

mkdir -p decisions

{
  "id": "D001",
  "text": "승인 확인 흐름을 조사합니다.",
  "evidenceId": "E001"
}

python3 -m json.tool decisions/D001.json
bash check.sh

{
    "id": "D001",
    "text": "\uc2b9\uc778 \ud655\uc778 \ud750\ub984\uc744 \uc870\uc0ac\ud569\ub2c8\ub2e4.",
    "evidenceId": "E001"
}
검사 실패: 0
PASS 파일 3개·JSON·근거 연결

bash check.sh