교재 홈: 바이브 코더를 위한 코딩 기초 학습
지금까지의 내용을 독서 기록을 요약하는 하나의 프로그램으로 연결합니다. 입력을 읽고, 잘못된 기록을 구분하고, 계산한 결과를 파일로 저장한 뒤 예상한 값과 비교합니다.
코드는 06. 파일과 데이터 — 읽기·정제·저장을 구분하기의 읽기·검증·저장 모듈에 08. 테스트와 검증 — ‘맞다’의 기준을 코드 밖에서 정하기의 테스트와 09. 버전 관리 — 변경을 읽고 필요한 상태를 복구하기의 변경 확인 방법을 연결합니다. 모듈은 다시 가져다 쓸 기능을 모은 코드 파일, 테스트는 정한 입력과 기대 결과로 동작을 확인하는 코드입니다. 이 장부터 열었다면 해당 장의 개념과 실행 파일을 먼저 준비합니다.
이 프로젝트의 문제는 가상의 개인 독서 기록에 누락·중복·잘못된 시간이 섞여 있다는 것입니다. 프로그램은 원본을 보존하면서 유효한 기록을 추려 합계와 평균을 계산하고, 제외된 기록의 이유를 남겨야 합니다.
아래의 입력 계약·출력 계약은 어떤 자료를 받고 무엇을 만들겠다는 프로그램의 약속입니다. 정상 사례는 허용한 조건의 예, 실패 조건은 처리를 계속하지 않거나 별도로 보고할 상황입니다. 파일의 열 이름·순서·값 종류처럼 정한 구조를 **스키마(schema)**라고도 부릅니다. 이 예제에서는 어려운 형식 도구 없이 열 이름과 검증 규칙으로 그 구조를 명시합니다.
입력은 6장의 data/reading.csv입니다. 열은 id,title,minutes,completed이고 6장의 검증 규칙을 그대로 사용합니다. 출력은 새 폴더의 clean.csv, errors.json, summary.json, COMPLETE.txt입니다. 마지막 파일은 앞의 세 파일을 모두 쓴 뒤 생성하는 완료 표시입니다. 이것이 있어야 해당 실행이 끝났다고 판단합니다.
정상 사례의 정답은 전체 7건·유효 3건·오류 4건·합계 75분·평균 25분·완료 1건입니다. 헤더만 있고 데이터가 없는 CSV는 전체·유효·오류·합계·완료가 0이고 평균은 JSON의 null입니다. 필수 열이 없거나 입력 파일을 열 수 없으면 중단합니다. 출력 폴더가 이미 있으면 덮어쓰지 않고 중단합니다.
이 정책은 ‘행 오류를 별도로 보고하면서 나머지를 집계한다’는 학습용 결정입니다. 전체 자료의 완전성이 필수인 작업에서는 행 오류가 하나라도 있으면 결과 채택을 보류하는 정책이 적합할 수 있습니다.
**AI 에이전트(agent)**는 답을 적는 데 더해 연결된 도구로 코드를 작성·실행하거나 파일·서비스에 작업을 수행할 수 있는 AI 도구입니다. AI에게 주는 요청이나 작업 지시를 **프롬프트(prompt)**라고 합니다. 요구사항은 프로그램이 해야 할 일이며 제약조건은 사용할 환경·변경 범위처럼 지켜야 할 조건입니다. 성공 기준은 실제로 어떤 결과를 보면 요구를 충족했다고 판단할지 적은 것입니다. 다음 명세의 용어를 모르면 06. 파일과 데이터 — 읽기·정제·저장을 구분하기의 「실습 데이터와 처리 규칙」절, 08. 테스트와 검증 — ‘맞다’의 기준을 코드 밖에서 정하기, 09. 버전 관리 — 변경을 읽고 필요한 상태를 복구하기를 먼저 확인합니다.
다음은 이 프로젝트의 요구를 구조화한 예시입니다. 역할을 과장하기보다 관측 가능한 결과와 작업 범위를 적습니다.
목적: 가상의 개인 독서 CSV에서 유효 기록과 오류 기록을 분리하고 통계를 산출합니다. 기존 구성: data_tools.py의 read_records, clean_records, write_clean_csv를 사용합니다. 입력 계약: 6장의 열 구조·범위·중복 정책을 유지합니다. 출력 계약: 새 폴더에 clean.csv, errors.json, summary.json을 쓰고 성공 시 COMPLETE.txt를 생성합니다. 실행 조건: Python 3.12 이상, 기본 기능은 표준 라이브러리만 사용합니다. 경로는 실행 인수로 받습니다. 변경 범위: main.py와 종합 테스트에 한정합니다. 기존 함수의 계약을 바꿀 필요가 있으면 이유와 대안을 먼저 제시합니다. 검증: 제공한 7건의 정답, 빈 데이터, 잘못된 헤더, 출력 폴더 충돌, 원자료 보존을 확인합니다. 보고: 변경한 파일, 실행한 명령, 실제 결과, 실행하지 못한 검증을 구분합니다. 커밋·푸시는 별도 지시가 있을 때 수행합니다.
먼저 입력 규칙과 기대 결과를 확정합니다. 그다음 읽기·검증, 집계, 출력, 실행 인수, 테스트 순서로 붙입니다. 각 단계에서 눈으로 확인할 결과가 있어야 다음 단계의 문제가 앞 단계의 문제와 섞이지 않습니다.
이 규모에서는 기본 포함 기능인 표준 라이브러리 csv로 필요한 처리를 구현할 수 있습니다. **데이터프레임(data frame)**은 행과 열로 된 표를 프로그램 안에서 다루기 위한 자료구조이며, 이를 제공하는 외부 도구를 쓰면 복잡한 표 연산이 편해질 수 있습니다. 동시에 설치·버전·결측값 처리 규칙을 더 관리해야 합니다. 자료를 자주 수정하고 관계를 관리해야 하면 SQLite 같은 데이터베이스와 비교할 수 있습니다. 선택은 데이터 크기, 필요한 작업, 검증 가능성, 관리 부담을 근거로 합니다.
코드 읽기 안내입니다. summarize는 유효 기록과 오류 개수로 요약을 계산하고, write_json은 JSON 형식으로 파일을 씁니다. run은 읽기부터 저장까지 연결하고, main은 터미널에서 받은 지시를 처리합니다. 이름에 특별한 수학적 의미가 있는 것은 아닙니다.
argparse는 명령줄 인수, 즉 실행 명령 뒤에 붙여 전달한 입력 파일·출력 폴더 같은 값을 읽는 표준 모듈입니다. json.dump()는 값을 JSON 글로 바꾸어 파일에 쓰고 json.dumps()는 JSON 문자열을 만듭니다. **직렬화(serialization)**는 이런 식으로 프로그램 안의 값을 저장·전달할 형식으로 바꾸는 일입니다. allow_nan=False는 일반적인 숫자값이 아닌 특수한 계산 결과를 JSON 숫자로 쓰지 않도록 합니다. **NaN(Not a Number)**은 숫자로 정의되지 않는 계산 결과를 나타내는 특별한 값의 이름입니다.