5강. 테이블 명세서와 AI 프로젝트 Context 생성하기
0. 학습 목표
→ 실제 MySQL 스키마를 한 번 수집하여 사람 검토용 테이블 명세서와 Claude Code용 데이터베이스 문맥을 함께 생성합니다.
0.1 학습 목적과 선수 조건
이 강의의 목적은 Excel 문서 작성 방법을 익히는 것이 아닙니다.
실제 MySQL 스키마를 한 번 수집하여 개발자용 문서와 AI용 Context로 변환하고,
스키마가 변경되어도 같은 절차로 두 문서를 다시 생성할 수 있는 상태를 만드는 것입니다.
수동 문서 작성
MySQL 조회 → 사람이 Excel에 복사 → 별도로 AI에 다시 설명
자동화된 문서와 문맥 생성
MySQL 조회 → 구조화된 스냅샷 → Excel 명세서와 schema.md 동시 생성
이 강의는 다음 상태에서 시작합니다.
- 1강에서 구축한
inventoryDB에products8건,stock_logs16건,operation_requests0건이 존재합니다. - 2강에서 분리한
inventory_reader,inventory_operator,inventory_app계정이 존재합니다. - 3강에서 Claude Code에
mysql-inventoryMCP가inventory_reader계정으로 연결되어 있습니다. - 4강에서 MCP의 조회 성공과
UPDATE차단을 확인했습니다. - 강사가 배포한
table_spec_template.xlsx파일을 내려받아 두었습니다.
0.2 진행 순서
실습은 다음 순서로 진행합니다.
4강 실습 상태 확인
↓
같은 스냅샷에서 두 문서를 생성하는 이유 이해
↓
프로젝트 구조와 Excel 템플릿 준비
↓
읽기 전용 MCP로 스키마 스냅샷과 설명 파일 생성
↓
논리명과 업무 설명 검토
↓
테이블 명세서와 schema.md 생성과 일치 검증
↓
CLAUDE.md에 데이터베이스 작업 규칙 등록
0.3 완성할 결과물
5강 완료 시 프로젝트는 다음 상태가 됩니다.
inventory-mysql-app/
├── CLAUDE.md # 신규: DB 작업 규칙
├── db/
│ ├── schema.sql
│ └── roles.sql
├── templates/
│ └── table_spec_template.xlsx # 신규: 강사 배포 양식
├── docs/
│ └── database/
│ ├── schema_snapshot.json # 신규: 실제 스키마 기록
│ ├── schema_descriptions.yaml # 신규: 논리명과 업무 설명
│ ├── table_spec.xlsx # 신규: 사람 검토용 명세서
│ └── schema.md # 신규: Claude Code용 문맥
├── tools/
│ └── generate_table_spec.py # 신규: 문서 생성 도구
├── harness/
└── app/
0.4 학습 목표
5강을 마치면 다음 작업을 수행할 수 있습니다.
- 테이블 명세서에서 자동 수집할 항목과 사람이 검토할 항목을 구분할 수 있습니다.
- Claude Code가 읽기 전용 MySQL MCP로 실제 스키마를 조회하도록 요청할 수 있습니다.
- 문서 생성 도구가 사용할
schema_snapshot.json을 생성할 수 있습니다. - 템플릿 양식에 맞는
table_spec.xlsx를 생성할 수 있습니다. - 동일한 스키마 정보로
schema.md를 생성할 수 있습니다. CLAUDE.md에 데이터베이스 문맥 사용 규칙을 등록할 수 있습니다.- 생성한 문서와 실제 MySQL 스키마의 일치 여부를 검증할 수 있습니다.
1. 실습 준비 상태 확인
→ MCP 연결과 기준 데이터 8 / 16 / 0, 상품 1번 재고 25를 확인하고 실습을 시작합니다.
1.1 MCP 연결 상태 확인하기
쉘 프롬프트에서 프로젝트 폴더로 이동한 후 Claude Code를 실행합니다.
cd ~/projects/inventory-mysql-app
claude
클로드 코드 프롬프트에서 MCP 연결 상태를 확인합니다.
/mcpmysql-inventory가 connected 상태로 표시되어야 합니다.
1.2 기준 데이터 확인하기
클로드 코드 프롬프트에 다음과 같이 요청합니다.
inventory DB의 products, stock_logs, operation_requests의
행 수와 product_id가 1인 상품의 stock_quantity를 확인해줘.
조건:
- 실행할 SELECT SQL을 먼저 보여준다.
- 확인하지 못한 값은 추측하지 않는다.
내가 SQL을 검토하고 승인하기 전에는 실행하지 마.
기대 결과는 다음과 같습니다.
| 확인 항목 | 기대 값 |
products 행 수 |
8 |
stock_logs 행 수 |
16 |
operation_requests 행 수 |
0 |
상품 1번의 stock_quantity |
25 |
▶ 지금 해보세요
- 프로젝트 폴더에서 Claude Code를 실행하고
/mcp로 연결 상태를 확인합니다. - 세 테이블의 행 수와 상품 1번 재고를 MCP로 조회합니다.
- 기대 값과 다른 항목이 있으면 4강의 완료 기준으로 돌아가 먼저 해결합니다.
✔ 확인 기준:
· mysql-inventory MCP가 연결 상태로 표시됩니다.
· 세 테이블의 행 수가 8 / 16 / 0입니다.
· 상품 1번의 stock_quantity가 25입니다.
2. 테이블 명세서와 AI 문맥을 같은 스냅샷에서 생성하는 이유
→ 자동으로 수집할 구조 정보와 사람이 검토할 업무 정보를 구분하고, 파일별 역할과 정보의 기준 순서를 확인합니다.
2.1 Excel에 직접 입력하는 방식의 문제
테이블 명세서를 사람이 처음부터 Excel에 입력하면 데이터베이스 구조를 한 번 확인하는 데에는 도움이 됩니다. 그러나 실제 프로젝트에서는 다음 문제가 발생합니다.
- 테이블이나 컬럼이 변경될 때마다 Excel 파일을 다시 수정해야 합니다.
- 컬럼 타입,
NULL허용 여부, 기본값, 기본 키, 외래 키를 잘못 옮기는 실수를 할 수 있습니다. - Excel 문서와 실제 데이터베이스가 서로 다른 상태로 남을 수 있습니다.
- 같은 구조를 Claude에 설명하기 위해 DDL이나 조회 결과를 대화마다 다시 복사해야 합니다.
- 명세서와 코드가 같은 테이블을 서로 다른 이름이나 타입으로 해석할 수 있습니다.
따라서 이 강의에서는 Excel 입력 속도를 높이는 방법이 아니라 다음 개발 절차를 학습합니다.
실제 MySQL 스키마
↓
구조화된 스키마 정보 수집
↓
동일한 스키마 정보로 두 종류의 문서 생성
├─ table_spec.xlsx : 사람의 검토, 협업, 제출에 사용
└─ schema.md : Claude Code의 프로젝트 문맥에 사용
이 구조에서는 Excel 문서와 AI 문맥을 각각 작성하지 않습니다. 같은 스키마 스냅샷에서 두 문서를 생성하여 구조 정보의 불일치를 줄입니다.
이 절에서 사용하는 용어는 다음과 같습니다.
- 스냅샷(snapshot): 특정 시점의 데이터베이스 구조를 그대로 저장한 기록입니다.
- 물리명: 데이터베이스에 실제로 저장된 테이블과 컬럼 이름입니다. 예:
products - 논리명: 화면과 문서에서 사용하는 업무 용어 명칭입니다. 예: 상품
2.2 자동 수집 항목과 사람 검토 항목 구분하기
다음 정보는 MySQL에서 자동으로 수집합니다.
| 자동 수집 항목 | MySQL에서 확인할 정보 |
| 테이블 물리명 | 실제 테이블 이름 |
| 컬럼 물리명 | 실제 컬럼 이름 |
| 데이터 타입과 길이 | DATA_TYPE, COLUMN_TYPE, 길이와 정밀도 |
| 필수 입력 여부 | IS_NULLABLE |
| 기본값 | COLUMN_DEFAULT |
| 키와 제약 조건 | PK, FK, UK, CK |
| 인덱스 | 인덱스명, 컬럼 순서, 고유 여부 |
| 테이블 생성 SQL | SHOW CREATE TABLE 결과 |
다음 정보는 담당자가 검토하고 승인합니다.
| 사람이 검토할 항목 | 판단이 필요한 이유 |
| 테이블 논리명 | 조직과 프로젝트에서 사용하는 업무 용어가 필요합니다. |
| 컬럼 논리명 | 화면과 문서에서 사용할 자연스러운 한국어 명칭이 필요합니다. |
| 테이블 설명 | 테이블의 업무 목적은 스키마만으로 확정할 수 없습니다. |
| 컬럼 설명 | 값의 범위와 업무 규칙은 코드와 요구사항 확인이 필요합니다. |
| 비고 | 개인정보, 단위, 상태 코드 등 프로젝트별 정보가 필요합니다. |
✔ 핵심: 자동으로 판단할 수 없는 논리명과 업무 설명을 Claude가 임의로 확정하지 않습니다. 근거가 없는 항목은 검토 필요로 표시하고, 학습자가 요구사항과 실제 사용 코드를 확인하여 직접 수정합니다.
2.3 파일별 역할과 정보의 기준 순서
이 강의에서 만드는 파일들은 다음 순서로 관리합니다. 위에 있는 자료가 아래 자료의 기준입니다.
실제 MySQL 스키마 (최종 기준)
↓ 읽기 전용 MCP로 조회
schema_snapshot.json (특정 시점의 구조 기록)
+ schema_descriptions.yaml (사람이 승인한 논리명과 설명)
↓ generate_table_spec.py로 생성
table_spec.xlsx (사람 검토·협업·제출용)
schema.md (Claude Code·개발자용)
| 파일 | 주요 사용자 | 사용 목적 | 수정 방식 |
table_spec_template.xlsx |
강사, 문서 생성 도구 | 시트 구성, 셀 위치, 서식 등 양식 정의 | 양식 변경 시에만 수정 |
schema_snapshot.json |
생성 도구, Claude Code | 실제 스키마 정보를 구조화하여 저장 | MySQL에서 다시 생성 |
schema_descriptions.yaml |
학습자, 담당자 | 논리명과 업무 설명 관리 |
사람이 검토 후 수정 |
table_spec.xlsx |
학습자, 강사, 협업자 | 테이블 구조 검토와 제출 |
스냅샷과 설명 파일로 다시 생성 |
schema.md |
Claude Code, 개발자 | 코드 생성 전에 테이블 관계와 제약 조건 확인 | 스냅샷과 설명 파일로 다시 생성 |
CLAUDE.md |
Claude Code | 문서 사용 순서와 데이터베이스 권한 규칙 적용 | 프로젝트 정책 변경 시 수정 |
table_spec.xlsx와 schema.md는 생성 결과물이므로 직접 수정하지 않습니다.
내용을 바꾸려면 schema_descriptions.yaml을 수정하거나 스냅샷을 다시 만든 후 두 문서를 다시 생성합니다.
✔ 정리: 문서와 실제 데이터베이스가 다르면 문서를 근거로 코드를 작성하지 않습니다. 읽기 전용 MCP로 실제 스키마를 확인하고 문서를 다시 생성합니다.
3. 프로젝트 구조와 Excel 템플릿 준비
→ docs, tools, templates 폴더를 만들고, 강사가 배포한 템플릿에서 사용할 양식 요소를 확인합니다.
3.1 폴더 구조 만들기
쉘 프롬프트에서 프로젝트 폴더로 이동한 후 새 폴더 3개를 만듭니다.
# 새 폴더 생성
cd ~/projects/inventory-mysql-app
mkdir -p docs/database tools templates
ls -R docs tools templates| 폴더 |
사용 목적 |
| docs/database | 생성된 테이블 명세서와 데이터베이스 문맥 파일 저장 |
| tools | 테이블 명세서 생성 프로그램 저장 |
| templates | 강사가 배포한 Excel 명세서 양식 저장 |
강사가 배포한 템플릿 파일을 templates 폴더로 복사합니다. 내려받은 위치가 다르면 경로를 실제 위치로 바꿔서 실행합니다.
# 템플릿 파일 복사
cp ~/Downloads/table_spec_template.xlsx templates/
ls templates/
3.2 문서 생성에 사용할 라이브러리 설치하기
문서 생성 도구는 Excel 파일 처리에 openpyxl, 설명 파일 처리에 PyYAML을 사용합니다.
- openpyxl: Python에서
xlsx파일을 읽고 쓰는 라이브러리입니다. 3.1 이상을 사용합니다. - PyYAML: Python에서 YAML 파일을 읽고 쓰는 라이브러리입니다. 6.0 이상을 사용합니다.
- YAML: 들여쓰기로 구조를 표현하는 텍스트 형식입니다. 사람이 직접 읽고 수정하기 쉬워 설명 파일에 사용합니다.
프로젝트 루트에 .venv 가상환경을 생성합니다.
python3 -m venv .venv
다음 명령으로 가상환경을 활성화합니다.
source .venv/bin/activate
가상환경이 활성화되면 터미널 프롬프트 앞에 (.venv)가 표시됩니다.
(.venv) 사용자명@컴퓨터:~/projects/inventory-mysql-app$
쉘 프롬프트에서 설치합니다.
# 패키지 설치
pip install "openpyxl>=3.1" "PyYAML>=6.0"
프로젝트 루트의 requirements.txt에 기록합합니다.
# 실제 설치된 버전을 requirements.txt에 기록
python -m pip freeze > requirements.txt
💡 참고: 프로젝트에서 Python 가상 환경을 사용하고 있다면 가상 환경을 활성화한 상태에서 설치합니다. 설치 후 pip show openpyxl로 버전을 확인할 수 있습니다.
3.3 템플릿에서 사용할 양식 요소 확인하기
templates/table_spec_template.xlsx를 열어 시트 구성을 확인합니다.
템플릿에서는 다음 양식 요소만 사용합니다.
- 테이블 목록 시트
- 테이블별 명세 시트
- 문서 제목, 작성일, 작성자 영역
- 테이블명, 테이블 ID, 테이블 설명 영역
- 컬럼명, 컬럼 ID, 타입, 길이,
Not Null, PK, FK, UK, CK, 비고 열 - 인덱스 정의 영역
CREATE TABLE스크립트 영역- 셀 병합, 열 너비, 글꼴, 채우기 색상, 테두리와 인쇄 영역
⚠ 주의: 템플릿에 남아 있는 기존 테이블명, 컬럼명, 설명, SQL은 다른 프로젝트의 예시 데이터입니다. 이 내용을 실습 결과물에 복사하면 실제 inventory DB와 다른 명세서가 만들어집니다. 템플릿은 양식만 사용하고, 내용은 1강에서 만든 실습 데이터베이스의 구조로만 채웁니다.
▶ 지금 해보세요
docs/database,tools,templates폴더를 만듭니다.- 배포받은 템플릿을
templates/table_spec_template.xlsx로 복사합니다. - openpyxl과 PyYAML을 설치하고
requirements.txt에 추가합니다. - 템플릿을 열어 시트 구성과 입력 영역을 확인합니다.
✔ 확인 기준:
· docs/database, tools, templates 폴더가 존재합니다.
· templates/table_spec_template.xlsx가 존재합니다.
· pip show openpyxl과 pip show PyYAML이 버전을 출력합니다.
· 템플릿의 시트 구성과 양식 요소를 설명할 수 있습니다.
4. 읽기 전용 MCP로 스키마 스냅샷과 설명 파일 생성
→ Claude Code가 MCP로 실제 스키마를 조회하여 schema_snapshot.json과 schema_descriptions.yaml을 생성합니다.
4.1 Claude Code에 스냅샷 생성 요청하기
클로드 코드 프롬프트에 다음과 같이 요청합니다.
읽기 전용 MySQL MCP로 inventory DB의 실제 스키마를 조회해서
docs/database/schema_snapshot.json을 생성해줘.
조건:
- 테이블, 컬럼, 타입, NULL 허용 여부, 기본값을 포함한다.
- PK, FK, UK, CK와 인덱스 정보를 포함한다.
- 각 테이블의 SHOW CREATE TABLE 결과를 포함한다.
- 실행할 SELECT SQL을 먼저 보여준다.
사람이 관리할 논리명과 업무 설명은
docs/database/schema_descriptions.yaml로 분리해서 생성하고,
확정할 근거가 없는 설명은 추측하지 말고 '검토 필요'로 표시해줘.
내가 SQL과 생성 계획을 승인하기 전에는 실행하지 마.
Claude Code가 제시한 SQL과 계획에서 다음 내용을 확인한 후 승인합니다.
- 조회 SQL이
SELECT와SHOW CREATE TABLE만 포함하는가? - 조회 대상이
inventoryDB로 제한되어 있는가? - 생성할 파일이
docs/database아래 두 파일뿐인가? - 기존 파일을 변경하는 작업이 없는가?
4.2 스냅샷 내용 검토하기
생성된 docs/database/schema_snapshot.json을 소스코드 에디터에서 열어 구성을 확인합니다.
테이블마다 다음 형태의 정보가 있어야 합니다.
{
"database": "inventory",
"generated_at": "2026-07-19 10:30:00",
"tables": [
{
"table_name": "products",
"columns": [
{
"column_name": "product_id",
"column_type": "int unsigned",
"is_nullable": "NO",
"column_default": null,
"extra": "auto_increment"
}
],
"primary_key": ["product_id"],
"foreign_keys": [],
"unique_keys": [{"name": "product_name", "columns": ["product_name"]}],
"check_constraints": ["chk_products_unit_price"],
"indexes": [],
"create_table": "CREATE TABLE `products` (...)"
}
]
}
키 이름은 Claude Code의 구현에 따라 다를 수 있습니다. 이름 자체보다 실제 스키마의 수치와 일치하는지를 확인합니다.
| 테이블 | 컬럼 수 | 기본 키 | 외래 키와 고유 키 |
products |
8 | product_id |
UK: product_name |
operation_requests |
10 | request_id |
FK: product_id → products |
stock_logs |
9 | log_id |
FK: product_id → products, request_id → operation_requests / UK: request_id |
💡 참고: 외래 키를 만들면 MySQL이 해당 컬럼에 인덱스를 자동으로 생성합니다. 스냅샷의 인덱스 목록에 직접 만들지 않은 인덱스가 보이는 것은 정상입니다.
4.3 설명 파일의 검토 필요 표시 확인하기
docs/database/schema_descriptions.yaml을 열어 구성을 확인합니다.
논리명과 설명이 확정되지 않은 항목은 다음처럼 검토 필요로 표시되어 있어야 합니다.
products:
logical_name: 검토 필요
description: 검토 필요
columns:
product_id:
logical_name: 검토 필요
description: 검토 필요
product_name:
logical_name: 검토 필요
description: 검토 필요
Claude Code가 일부 항목에 논리명을 미리 채웠다면 그 값을 확정된 것으로 간주하지 않습니다. 채워진 값도 5.2에서 학습자가 근거를 확인하고 직접 승인합니다.
▶ 지금 해보세요
- Claude Code에 스냅샷과 설명 파일 생성을 요청하고, 제시된 SQL과 계획을 검토한 후 승인합니다.
schema_snapshot.json의 테이블 수, 컬럼 수, 키 정보를 위 표와 대조합니다.schema_descriptions.yaml에서검토 필요표시를 확인합니다.
✔ 확인 기준:
· schema_snapshot.json에 테이블 3개가 있고 컬럼 수가 8 / 10 / 9입니다.
· PK, FK, UK, CK, 인덱스, CREATE TABLE 정보가 포함되어 있습니다.
· schema_descriptions.yaml에서 근거가 없는 설명이 검토 필요로 표시되어 있습니다.
· 생성 과정에서 MCP가 SELECT와 SHOW CREATE TABLE만 실행했습니다.
5. 논리명과 업무 설명 검토
→ 검토 필요 항목을 요구사항과 실제 데이터를 근거로 직접 수정하여 설명 파일을 확정합니다.
5.1 검토 근거 준비하기
논리명과 업무 설명은 다음 자료를 근거로 작성합니다. 추측으로 채우지 않습니다.
- 1강에서 확정한 테이블 구조와
db/schema.sql의 제약 조건 - 기준 데이터의 실제 값 (예:
movement_type에 저장된IN,OUT) - 이 과정에서 구현할 기능 요구사항 (재고 조회, 출고 처리)
실제 값이 필요하면 MCP로 조회합니다. 예를 들어 movement_type에 사용 중인 값을 확인할 때 다음 SQL을 승인하고 실행합니다.
SELECT DISTINCT movement_type
FROM stock_logs;
5.2 Claude Code에 설명 파일 생성을 요청하기
Claude Code 대화 입력창에 다음 내용을 입력합니다.
docs/database/schema_descriptions.yaml을 다음 근거에 따라 수정해 줘.
작업 전에 다음 자료를 확인해.
1. db/schema.sql
- 테이블과 컬럼 구조
- 데이터 타입
- PK, FK, UNIQUE, CHECK 제약조건
- 기본값
- AUTO_INCREMENT
- CURRENT_TIMESTAMP와 ON UPDATE 조건
2. 읽기 전용 MySQL MCP의 실제 inventory 데이터베이스
- 실제 생성된 테이블과 컬럼
- SHOW CREATE TABLE 결과
- ENUM 컬럼에 정의된 값
- 기준 데이터에 실제로 저장된 값
- products.category의 실제 값
- stock_logs.movement_type의 실제 값
3. 이후 구현할 기능 요구사항
- 현재 재고 수량이 재주문 기준 이하인 상품을 조회한다.
- 상품 출고 시 현재 재고를 확인하고 출고 수량만큼 차감한다.
- 재고 차감과 출고 이력 저장은 하나의 트랜잭션으로 처리한다.
- 출고 실행 전 요청 내용과 처리 상태를 기록한다.
- 같은 요청 ID가 반복 실행되지 않도록 차단한다.
- 재고가 변경되면 변경 전 수량과 변경 후 수량을 기록한다.
- 금액 단위는 원이고 재고와 변경 수량의 단위는 개이다.
위 자료를 근거로 db/schema_descriptions.yaml을 생성해.
작성 규칙:
- 실제 존재하는 모든 테이블과 컬럼을 포함한다.
- 테이블마다 logical_name과 description을 작성한다.
- 컬럼마다 logical_name과 description을 작성한다.
- 물리 테이블명과 컬럼명은 변경하지 않는다.
- 컬럼 설명에는 필요한 경우 단위, 기본값, 자동 입력 조건,
값의 범위와 다른 테이블과의 관계를 포함한다.
- 제약조건에서 확인할 수 있는 내용을 설명에 반영한다.
- 기준 데이터에서 확인한 실제 값의 의미를 설명한다.
- 데이터베이스 구조만으로 확정할 수 없는 업무 의미는 추측하지 말고
'검토 필요'라고 표시한다.
- operation_requests가 비어 있으므로 실제 데이터에서 확인하지 못한
operation_type의 허용값을 임의로 만들지 않는다.
- 데이터베이스와 db/schema.sql은 수정하지 않는다.
- MySQL MCP를 사용하여 INSERT, UPDATE, DELETE 또는 DDL을 실행하지 않는다.
상태와 구분값은 다음 기능 요구사항을 기준으로 설명한다.
operation_requests.status:
- PLANNED: 변경 요청이 생성되었지만 아직 실행 승인을 받지 않은 상태
- APPROVED: 요청 내용이 승인되었지만 아직 데이터 변경이 완료되지 않은 상태
- COMPLETED: 승인된 재고 변경과 이력 저장이 정상적으로 완료된 상태
- FAILED: 실행 중 오류가 발생하여 트랜잭션이 완료되지 않은 상태
stock_logs.movement_type:
- IN: 입고로 재고가 증가한 경우
- OUT: 출고로 재고가 감소한 경우
- ADJUSTMENT: 재고 실사나 오류 정정으로 수량을 조정한 경우
파일을 생성하기 전에 다음 내용을 먼저 보여 줘.
1. 확인한 테이블 목록
2. 설명 작성에 사용한 근거
3. 자동으로 확정할 수 있는 항목
4. 검토가 필요한 항목
5. 생성할 파일의 구조
내가 내용을 확인한 후에만 docs/database/schema_descriptions.yaml을 생성해.
5.3 생성 결과 예시와, 설명 파일 수정
소스코드 에디터에서 schema_descriptions.yaml의 검토 필요 항목을 수정합니다. products 테이블의 수정 예는 다음과 같습니다.
products:
logical_name: 상품
description: 판매 상품의 기본 정보와 현재 재고 수량을 관리한다.
columns:
product_id:
logical_name: 상품 번호
description: 상품을 구분하는 고유 번호. 자동 증가한다.
product_name:
logical_name: 상품명
description: 상품 이름. 중복을 허용하지 않는다.
category:
logical_name: 분류
description: 상품 분류 명칭. 예) 주변기기, 디스플레이, 저장장치, 오디오
unit_price:
logical_name: 단가
description: 상품 1개의 판매 가격. 단위는 원이며 0 이상만 허용한다.
stock_quantity:
logical_name: 현재 재고 수량
description: 현재 보유 수량. 단위는 개이며 0 이상만 허용한다.
reorder_level:
logical_name: 재주문 기준 수량
description: 재고가 이 수량 이하로 내려가면 재주문 대상으로 판단한다.
created_at:
logical_name: 등록 일시
description: 상품이 등록된 일시. 자동으로 입력된다.
updated_at:
logical_name: 수정 일시
description: 상품 정보가 마지막으로 수정된 일시. 자동으로 갱신된다.
같은 방식으로 operation_requests와 stock_logs를 수정합니다. 이때 다음 항목은 설명에 반드시 포함합니다.
operation_requests.status:PLANNED,APPROVED,COMPLETED,FAILED각 상태의 의미stock_logs.movement_type:IN(입고),OUT(출고),ADJUSTMENT(조정)의 의미stock_logs.stock_before,stock_after: 변동 전후 수량이라는 기준- 수량 컬럼의 단위 (개)
💡 팁: YAML은 들여쓰기로 구조를 구분합니다. 항목을 수정할 때 들여쓰기 칸 수를 바꾸거나 콜론 뒤 공백을 지우면 이후 문서 생성이 실패합니다. 기존 항목과 같은 들여쓰기를 유지합니다.
근거를 확인하지 못한 항목은 검토 필요로 남겨 둡니다. 비워 두거나 추측으로 채우는 것보다 검토가 끝나지 않았다는 상태를 남기는 것이 정확합니다.
5.4 수정된 YAML 문법 확인하기
파일이 생성되면 Python에서 YAML 문법을 검사합니다. 만약 필요하다면 수동으로 진행합니다.
python -c "import yaml; yaml.safe_load(open('db/schema_descriptions.yaml', encoding='utf-8'));
print('YAML 문법 확인 완료')"
다음 메시지가 출력되어야 합니다.
YAML 문법 확인 완료
▶ 지금 해보세요
- 세 테이블의 논리명과 테이블 설명을 수정합니다.
- 모든 컬럼의 논리명을 수정하고, 상태 코드·단위·날짜 기준이 있는 컬럼은 설명에 포함합니다.
- 근거가 없는 항목은
검토 필요로 남깁니다.
✔ 확인 기준:
· 세 테이블의 논리명과 설명이 실습 DB의 업무 목적과 일치합니다.
· status와 movement_type의 상태 코드 의미가 설명에 포함되어 있습니다.
· 남아 있는 검토 필요 항목은 근거를 확인하지 못한 항목뿐입니다.
· 수정 후에도 YAML 들여쓰기 구조가 유지되어 있습니다.
6. 테이블 명세서와 schema.md 생성과 일치 검증
→ generate_table_spec.py를 구현하고 실행하여 두 문서를 생성한 뒤 실제 스키마와 대조합니다.
6.0 임시 파일
다음 "6.1 Claude Code에 문서 생성 도구 구현 요청하기" 진행 단계에서, 토큰 및 실습 시간 절약을 위해 파일을 우선 첨부합니다. 다음 경로에 추가하고, 검토 요청 후 6.2 실행으로 진행합니다.
- tools/generate_table_spec.py
tools/generate_table_spec.py는 강사가 미리 작성해서 제공한 파일이다.
이 파일을 읽고 다음을 확인해줘.
조건:
- MySQL에 직접 접속하는 코드가 있는가?
- 입력으로 schema_snapshot.json과 schema_descriptions.yaml만 사용하는가?
- templates/table_spec_template.xlsx의 기존 테이블명·컬럼명·SQL을
그대로 복사하는 코드가 있는가?
- 실행하면 어떤 경로에 어떤 파일이 생성되는가?
파일을 수정하지 말고 분석 결과만 알려줘.
파일을 복사하더라도 이 단계가 필요한 이유는, CLAUDE.md 원칙(“AI 생성 결과를 검증 없이 승인하지 않는다”)이 지켜지지 않기 때문입니다. 학생이 코드를 한 줄씩 읽는 대신, Claude Code에게 위 네 가지 질문에 대한 답을 받아 그 설명이 실제 코드와 맞는지 훑어보는 정도로 검토 부담을 줄일 수 있습니다.
6.1 Claude Code에 문서 생성 도구 구현 요청하기
클로드 코드 프롬프트에 다음과 같이 요청합니다.
tools/generate_table_spec.py를 구현해줘.
조건:
- templates/table_spec_template.xlsx는 시트 구성, 셀 위치, 서식 등 양식만 사용한다.
- 템플릿에 남아 있는 테이블명, 컬럼명, 설명, SQL은 결과물에 복사하지 않는다.
- 입력은 docs/database/schema_snapshot.json과 docs/database/schema_descriptions.yaml만 사용한다.
- 출력으로 docs/database/table_spec.xlsx와 docs/database/schema.md를 생성한다.
- 실행 마지막에 테이블 수, 테이블별 컬럼 수, 키 개수를 스냅샷과 대조한 검증 결과를 출력한다.
- MySQL에 직접 접속하지 않는다.
- openpyxl과 PyYAML을 사용하고, 파일이 없거나 형식이 잘못된 경우 원인을 알 수 있는 오류 메시지를 출력한다.
구현 전에 생성할 파일, 변경하지 않을 파일, 검증 방법을 먼저 설명해.
계획을 승인한 뒤에도 한 번에 모든 파일을 수정하지 말고
단계별로 진행해.
제시된 계획에서 다음 내용을 확인한 후 승인합니다.
- 생성 파일이
tools/generate_table_spec.py뿐인가? - 입력이 스냅샷과 설명 파일로 제한되어 있는가?
- MySQL 접속 코드가 포함되어 있지 않은가?
- 템플릿의 기존 데이터를 지우거나 복사하지 않는 방식인가?
6.2 문서 생성 도구 실행하기
쉘 프롬프트에서 프로젝트 루트를 기준으로 실행합니다.
cd ~/projects/inventory-mysql-app
source .venv/bin/activate
python tools/generate_table_spec.py
실행이 끝나면 검증 결과가 출력되어야 합니다. 출력 형식은 구현에 따라 다를 수 있지만 다음 정보가 포함되어야 합니다.
[생성] docs/database/table_spec.xlsx
[생성] docs/database/schema.md
[검증] 테이블 수: 스냅샷 3 / 명세서 3 / schema.md 3 → 일치
[검증] products 컬럼 수: 8 / 8 → 일치
[검증] operation_requests 컬럼 수: 10 / 10 → 일치
[검증] stock_logs 컬럼 수: 9 / 9 → 일치
[검증] 검토 필요 항목: 0건
6.3 생성된 두 문서 확인하기
docs/database/table_spec.xlsx를 열어 다음을 확인합니다.
- 테이블 목록 시트에
products,operation_requests,stock_logs세 행이 있습니다. - 테이블별 명세 시트가 세 개 있고 템플릿과 같은 서식이 적용되어 있습니다.
- 각 시트의 컬럼명, 타입,
Not Null, 기본값, PK, FK, UK, CK가 채워져 있습니다. - 인덱스 정의 영역과
CREATE TABLE스크립트 영역이 채워져 있습니다. - 논리명과 설명 열에 5.2에서 수정한 내용이 반영되어 있습니다.
- 템플릿에 있던 기존 테이블명과 컬럼명이 남아 있지 않습니다.
docs/database/schema.md를 열어 확인합니다. products 부분은 다음과 같은 형태입니다.
# inventory 데이터베이스 문맥
- 생성 기준: docs/database/schema_snapshot.json
- 이 문서는 생성 결과물이므로 직접 수정하지 않는다.
## products (상품)
판매 상품의 기본 정보와 현재 재고 수량을 관리한다.
| 컬럼 | 논리명 | 타입 | NULL | 기본값 | 키 |
|---|---|---|---|---|---|
| product_id | 상품 번호 | int unsigned | NO | AUTO_INCREMENT | PK |
| product_name | 상품명 | varchar(100) | NO | 없음 | UK |
| category | 분류 | varchar(50) | NO | 없음 | |
| unit_price | 단가 | decimal(10,2) unsigned | NO | 없음 | |
| stock_quantity | 현재 재고 수량 | int unsigned | NO | 0 | |
| reorder_level | 재주문 기준 수량 | int unsigned | NO | 0 | |
| created_at | 등록 일시 | datetime | NO | CURRENT_TIMESTAMP | |
| updated_at | 수정 일시 | datetime | NO | CURRENT_TIMESTAMP | |
operation_requests와 stock_logs도 같은 구성으로 생성되며, 외래 키 관계와 제약 조건 설명이 포함되어야 합니다.
마지막으로 Excel 명세서와 schema.md의 테이블명, 컬럼명, 컬럼 수가 서로 같은지 확인합니다. 두 문서는 같은 스냅샷에서 생성되므로 다르면 생성 도구의 오류입니다.
▶ 지금 해보세요
- 구현 계획을 검토한 후
generate_table_spec.py구현을 승인합니다. - 도구를 실행하고 검증 출력에서 모든 항목의 일치를 확인합니다.
- Excel 명세서와
schema.md를 열어 세 테이블의 내용과 서식을 확인합니다. - 도구를 한 번 더 실행하여 같은 결과가 다시 생성되는지 확인합니다.
✔ 확인 기준:
· 실행 출력에서 테이블 수와 테이블별 컬럼 수 8 / 10 / 9가 모두 일치로 표시됩니다.
· Excel 명세서와 schema.md의 테이블명과 컬럼명이 서로 같습니다.
· 템플릿의 기존 데이터가 결과물에 남아 있지 않습니다.
· 도구를 다시 실행해도 같은 내용의 문서가 생성됩니다.
7. CLAUDE.md에 데이터베이스 작업 규칙 등록
→ Claude Code가 코드 작업 전에 schema.md를 먼저 읽도록 규칙을 등록하고 적용을 확인합니다.
7.1 규칙 작성하기
CLAUDE.md는 Claude Code가 프로젝트에서 대화를 시작할 때 자동으로 읽는 프로젝트 규칙 파일입니다.
/init
프로젝트 루트에 CLAUDE.md를 만들고 다음 내용을 직접 추가하거나, 요청합니다.
CLAUDE.md에 다음 내용 추가해줘
## 데이터베이스 작업 규칙
1. 데이터베이스 관련 코드를 수정하기 전에
docs/database/schema.md와
docs/database/schema_snapshot.json을 먼저 확인한다.
2. 문서에 없는 테이블, 컬럼, 제약 조건을 임의로 만들지 않는다.
3. 문서와 실제 데이터베이스가 다르거나 최신 상태 확인이 필요하면
읽기 전용 MySQL MCP로 실제 스키마를 조회한다.
4. MySQL MCP를 사용하여 INSERT, UPDATE, DELETE, DDL을 실행하지 않는다.
5. 데이터 변경은 프로그램의 MySQL Driver 코드에서만 실행한다.
6. 스키마가 변경되면 테이블 명세서와 schema.md를 다시 생성한다.
7. 업무 설명이 불명확한 항목은 추측하지 말고 '검토 필요'로 남긴다.
이 규칙을 적용하면 Claude Code는 6강부터 다음 자료를 같은 작업 문맥에서 사용합니다.
기능 요구사항
+ 현재 프로젝트의 Python·PySide6 파일
+ schema.md와 schema_snapshot.json
+ 필요할 때만 읽기 전용 MCP로 확인한 실제 MySQL 상태
= 현재 프로젝트 구조에 맞는 구현 계획과 코드 변경
7.2 규칙 적용 확인하기
CLAUDE.md는 대화 시작 시점에 읽히므로, Claude Code를 종료한 뒤 다시 실행하여 새 대화에서 확인합니다. 클로드 코드 프롬프트에 다음과 같이 요청합니다.
stock_logs와 operation_requests의 관계와
출고 이력을 저장할 때 지켜야 하는 제약 조건을 설명해줘.
조건:
- 근거로 사용한 문서의 파일명을 함께 제시한다.
- 문서에서 확인하지 못한 내용은 추측하지 않는다.
MySQL MCP 조회가 필요하면 실행할 SQL을 먼저 보여주고,
내가 승인하기 전에는 실행하지 마.[화면 캡처: Claude Code가 schema.md를 근거로 두 테이블의 관계를 설명한 화면]
응답에서 다음 내용을 확인합니다.
docs/database/schema.md또는 스냅샷 파일을 근거로 제시하는가?stock_logs.request_id가operation_requests를 참조하는 외래 키이며 고유 제약이 있다는 점을 설명하는가?- 문서에 없는 테이블이나 컬럼을 만들어 내지 않는가?
7.3 재생성 절차 확인하기
스키마가 변경되면 문서를 수정하는 것이 아니라 다음 순서로 다시 생성합니다.
실제 스키마 변경 발생
↓
읽기 전용 MCP로 변경된 스키마 조회
↓
schema_snapshot.json 다시 생성
↓
schema_descriptions.yaml에 추가된 항목만 검토
↓
python tools/generate_table_spec.py 실행
↓
table_spec.xlsx와 schema.md 갱신 확인
5강에서는 이 절차를 순서대로 설명할 수 있으면 됩니다. 실제 스키마 변경과 영향 분석은 9강에서 실습합니다.
▶ 지금 해보세요
- 프로젝트 루트에
CLAUDE.md를 작성합니다. - Claude Code를 다시 실행하고 두 테이블의 관계를 질문합니다.
- 응답이
schema.md를 근거로 제시하는지 확인합니다. - 스키마 변경 시 재생성 절차를 소리 내어 순서대로 설명해 봅니다.
✔ 확인 기준:
· 프로젝트 루트에 CLAUDE.md가 있고 일곱 개 규칙이 등록되어 있습니다.
· 새 대화에서 Claude Code가 schema.md를 근거로 테이블 관계를 설명합니다.
· 스키마 변경 후 문서를 다시 생성하는 절차를 순서대로 설명할 수 있습니다.
8. 문서 생성 오류 해결하기
→ 문서 생성이 실패하거나 결과가 실제 스키마와 다를 때 원인을 좁히는 순서를 정리합니다.
문제가 생기면 다음 순서로 원인을 좁힙니다. 파일을 무작정 다시 만들지 않습니다.
MCP 연결과 inventory_reader의 SELECT 권한
↓
schema_snapshot.json의 테이블·컬럼 수
↓
schema_descriptions.yaml의 YAML 형식
↓
openpyxl·PyYAML 설치와 실행 위치
↓
generate_table_spec.py의 검증 출력
↓
생성된 두 문서의 내용
| 증상 | 먼저 확인할 항목 | 해결 방향 |
Access denied for user 'inventory_reader' |
MCP 환경변수의 계정 정보와 2강 권한 설정 | SHOW GRANTS로 SELECT 권한 확인 후 연결 정보 수정 |
| 스냅샷에 테이블이 3개보다 적음 | 조회 SQL의 TABLE_SCHEMA 조건 |
조회 대상 DB를 inventory로 수정하고 스냅샷 다시 생성 |
ModuleNotFoundError: No module named 'openpyxl' |
라이브러리 설치 여부와 실행 중인 Python 환경 | 실행에 사용하는 환경에서 pip install 후 재실행 |
FileNotFoundError로 템플릿이나 스냅샷을 찾지 못함 |
실행 위치가 프로젝트 루트인지 | 프로젝트 루트에서 python tools/generate_table_spec.py 실행 |
yaml.parser.ParserError |
5.2에서 수정한 항목의 들여쓰기와 콜론 뒤 공백 | 수정한 항목을 기존 항목과 같은 들여쓰기로 복원 |
| 명세서 컬럼 수가 실제 스키마와 다름 | 스냅샷 생성 이후 스키마 변경 여부 | 문서를 직접 고치지 않고 스냅샷부터 다시 생성 |
| 결과물에 템플릿의 기존 테이블명이 남아 있음 | 생성 도구가 템플릿의 데이터 영역을 복사하는지 | 양식 요소만 복사하도록 도구 수정 후 다시 생성 |
Claude Code가 schema.md를 읽지 않고 답변함 |
CLAUDE.md의 위치와 규칙 등록 여부 |
프로젝트 루트의 CLAUDE.md 확인 후 새 대화에서 재확인 |
✔ 보안 원칙: 조회가 거부된다는 이유로 inventory_reader에 권한을 추가하거나 관리자 계정을 MCP에 연결하지 않습니다. 문서 생성에 필요한 권한은 SELECT뿐이며, 오류의 원인은 권한 확대가 아니라 연결 정보와 파일 형식에서 찾습니다.
9. 이번 강의 완료 기준
→ 체크리스트로 5강 완료 상태를 점검하고, 6강으로 넘기는 상태를 확인합니다.
9.1 최종 체크리스트
다음 항목을 모두 확인합니다.
- ☐ MCP 연결과 기준 데이터
8 / 16 / 0, 상품 1번 재고 25를 확인했습니다. - ☐
docs/database,tools,templates폴더와 템플릿 파일이 준비되어 있습니다. - ☐ openpyxl과 PyYAML을 설치하고
requirements.txt에 추가했습니다. - ☐
schema_snapshot.json에 테이블 3개와 컬럼 수8 / 10 / 9, 키·인덱스·CREATE TABLE정보가 있습니다. - ☐ 스냅샷 생성 과정에서 MCP가
SELECT와SHOW CREATE TABLE만 실행했습니다. - ☐
schema_descriptions.yaml의 논리명과 업무 설명을 근거를 확인하여 직접 수정했습니다. - ☐
status와movement_type의 상태 코드 의미가 설명에 포함되어 있습니다. - ☐
generate_table_spec.py실행으로table_spec.xlsx와schema.md가 생성됩니다. - ☐ 검증 출력에서 테이블 수와 테이블별 컬럼 수가 모두 일치합니다.
- ☐ Excel 명세서와
schema.md의 테이블명과 컬럼명이 서로 같습니다. - ☐ 템플릿의 기존 데이터가 결과물에 남아 있지 않습니다.
- ☐
CLAUDE.md에 데이터베이스 작업 규칙 일곱 개가 등록되어 있습니다. - ☐ 새 대화에서 Claude Code가
schema.md를 근거로 테이블 관계를 설명합니다. - ☐ 스키마 변경 후 문서를 다시 생성하는 절차를 설명할 수 있습니다.
9.2 완성 구조
inventory-mysql-app/
├── CLAUDE.md # ✅ DB 작업 규칙 등록
├── db/
│ ├── schema.sql
│ └── roles.sql
├── templates/
│ └── table_spec_template.xlsx # ✅ 양식만 사용
├── docs/
│ └── database/
│ ├── schema_snapshot.json # ✅ MCP 조회로 생성
│ ├── schema_descriptions.yaml # ✅ 사람이 검토·승인
│ ├── table_spec.xlsx # ✅ 도구로 생성
│ └── schema.md # ✅ 도구로 생성
├── tools/
│ └── generate_table_spec.py # ✅ 문서 생성 도구
├── harness/
└── app/
inventory DB (변경 없음)
├── products 8건
├── stock_logs 16건
└── operation_requests 0건
9.3 이번 강의에서 아직 하지 않는 작업
- Python 재고 조회 기능 구현 (6강)
- PySide6 재고 목록 화면 구현 (7강)
- 트랜잭션을 사용한 출고 기능 구현 (8강)
- 실제 스키마 변경과 문서·코드 영향 분석 (9강)
- MCP 계정에 쓰기 권한 부여 (과정 전체에서 하지 않습니다)
- Excel 셀에 테이블 구조를 한 칸씩 수동 입력하는 작업 (이 과정에서 다루지 않습니다)
이번 강의에서 데이터와 스키마는 변경하지 않았습니다. 만든 것은 문서 네 개, 생성 도구 하나, 프로젝트 규칙 파일 하나입니다.
9.4 참고 문서
공식 문서: Claude Code 메모리(CLAUDE.md) 공식 문서
How Claude remembers your project - Claude Code Docs
Give Claude persistent instructions with CLAUDE.md files, and let Claude accumulate learnings automatically with auto memory.
code.claude.com
그 밖에 openpyxl 공식 문서와 MySQL INFORMATION_SCHEMA 공식 문서를 참고하세요.
→ 다음 강의 (6강): 이번 강의에서 만든 schema.md와 스냅샷을 프로젝트 문맥으로 사용하여, Claude Code가 재주문 대상 재고를 조회하는 Python 기능을 구현하도록 요청하고 생성된 SQL과 코드를 검토합니다.
10. 실습 과제
→ 항목 분류, 명세서 오류 찾기, 재생성 절차 기록으로 5강 내용을 스스로 점검합니다.
10.1 자동 수집 항목과 사람 검토 항목 분류하기
다음 항목이 자동 수집 대상인지 사람 검토 대상인지 선택하고 근거를 작성합니다.
| 항목 | 자동 / 사람 | 근거 |
unit_price의 데이터 타입과 정밀도 |
||
stock_logs 테이블의 논리명 |
||
stock_quantity의 기본값 |
||
quantity의 수량 단위가 개라는 정보 |
||
request_id의 고유 제약 존재 여부 |
||
status 값 FAILED의 업무상 의미 |
✔ 완료 기준:
· 타입, 기본값, 고유 제약을 자동 수집 대상으로 분류했습니다.
· 논리명, 단위, 상태 코드의 의미를 사람 검토 대상으로 분류했습니다.
· 각 분류의 근거를 스키마에서 확인할 수 있는지 여부로 설명했습니다.
10.2 잘못 작성된 명세서 오류 찾기
다음은 수동으로 작성하다가 오류가 생긴 명세서의 일부입니다. schema_snapshot.json 또는 db/schema.sql과 대조하여 잘못된 부분 세 곳을 찾고 올바른 값을 작성합니다.
| 컬럼 | 타입 | Not Null | 기본값 |
request_id (stock_logs) |
CHAR(36) |
Y | 없음 |
status (operation_requests) |
ENUM |
Y | APPROVED |
stock_quantity (products) |
INT (부호 있음) |
Y | 0 |
✔ 완료 기준:
· stock_logs.request_id가 NULL을 허용한다는 것을 찾았습니다.
· status의 기본값이 PLANNED라는 것을 찾았습니다.
· stock_quantity가 INT UNSIGNED라는 것을 찾았습니다.
· 세 오류 모두 기억이 아니라 스냅샷 또는 schema.sql을 근거로 확인했습니다.
10.3 문서 재생성 결과 제출하기
schema_descriptions.yaml에서 컬럼 설명 하나를 더 구체적으로 수정한 뒤, 문서를 다시 생성하고 다음 결과를 캡처하거나 텍스트로 기록합니다.
- 수정한 설명 항목과 수정 근거
generate_table_spec.py실행 결과의 검증 출력- 수정한 설명이 반영된
table_spec.xlsx의 해당 셀 - 수정한 설명이 반영된
schema.md의 해당 행 - 재생성 후에도 기준 데이터가
8 / 16 / 0으로 유지됨을 확인한 조회 결과
✔ 완료 기준:
· Excel 명세서와 schema.md 두 곳에 같은 수정 내용이 반영되었습니다.
· 생성 결과물을 직접 고치지 않고 설명 파일 수정과 재생성으로 반영했습니다.
· 재생성 과정에서 데이터베이스의 데이터가 변경되지 않았습니다.