Claude Code로 Excel 사양서를 효율적으로 해석하고 인수인계하기 위한 명명 및 관리 기술

개발 현장에서는 여전히 대량의 사양서가 **Excel (xlsx)**로 관리되고 있습니다. 조사 결과, 기능 목록, 대응 상황, 데이터 항목 정의……. 이들을 AI 에이전트(저의 경우에는 Claude Code)에 읽히게 하여 「해석」 「요약」 「인수인계 자료화」를 하고 싶다는 니즈는 확실히 늘어나고 있습니다.

하지만 막상 해보면 벽에 부딪힙니다.

• 사양서를 전달해도 AI가 어떤 파일을 봐야 할지 망설임
• xlsx의 내용을 읽어도 셀 병합이나 여러 시트로 인해 문맥을 제대로 파악하지 못함
• 어렵게 해석시켜도 그 내용을 제3자(나 혹은 미래의 자신)에게 인수인계할 수 없음

제가 「고객 기반 시스템 추가 개발」 안건에서 과거 조사 자료 (xlsx)를 읽혀 인수인계 자료를 정비했을 때, 바로 이 점을 뼈저리게 느꼈습니다. 그리고 깨달은 것은, AI의 해석 정밀도는 입력하기 '전' 단계에서 거의 결정된다는 사실입니다.

이 기사에서는 코드를 작성하는 이야기가 아니라, 그 전 단계에 있는 「AI가 망설이지 않기 위한 메타데이터 관리」 —— 구체적으로는 파일 명명 규칙, 디렉터리 구조, 인수인계 문서 설계 —— 에 대해 실제로 실행해 보고 효과를 본 노하우를 공유합니다.

AI의 해석 정밀도는 프롬프트보다 「전달하는 자료를 정리하는 방법」으로 결정된다

• 해야 할 일은 단 4가지:
  ① 파일명에 용도를 포함한다 ② 1폴더 1컨텍스트 ③ xlsx는 한 번만 md로 변환한다 ④ 인수인계 문서 서두에 AI를 위한 지시를 둔다
• ③을 제외하면 어떤 LLM 도구에서도 사용할 수 있는 범용 테크닉

참고로 본 기사의 구체적인 예시는 실제 안건을 바탕으로 하고 있으나, 시스템명, 티켓 번호, 경로는 모두 가상의 것으로 대체하였습니다.

처음에 저는 단순하게 생각했습니다. 「xlsx를 그대로 전달하면 AI가 읽어주겠지」라고.

실제로 해보니 이런 상태였습니다.

어떤 폴더에는 이런 파일들이 나열되어 있었습니다 (흔히 볼 수 있는 광경이라고 생각합니다).

조사결과.xlsx
조사결과_최종.xlsx
조사결과_최종_v2.xlsx
...

사람도 「어느 것이 정답이지?」라고 망설이게 되는 이 상태는 AI에게는 훨씬 더 가혹합니다. 파일명에서 역할도 최신성도 판단할 수 없기 때문에, 결국 「전부 읽어줘」라고 지시하게 되어 토큰과 시간도 낭비하게 됩니다.

xlsx는 사람이 레이아웃으로서 읽기에는 훌륭하지만, 구조화 데이터로서는 까다로운 존재입니다.

• 셀 병합으로 인해 「1항목 1셀」 원칙이 깨져 있음
• 여러 시트에 걸쳐 있어 시트 간의 관계가 암묵적 지식임
• 테두리나 색상으로만 표현되어 있는 **의미 (중요도·분류)**가 있음

그대로 읽히면 AI가 표의 구조를 잘못 파악하거나, 다른 시트의 전제 조건을 놓치게 됩니다.

가장 컸던 문제는 이것입니다. AI와 대화하며 조사를 진행하면, 그 과정과 결론은 채팅 이력 속에만 쌓여갑니다. 세션을 닫으면 사라지며, 다른 사람이 처음부터 똑같은 이해에 도달하는 것은 불가능에 가깝습니다.

즉 문제는 「Excel을 읽히는 기술」이 아니라, Excel을 기점으로 한 지식을 AI가 다룰 수 있는 자산으로 변환하여 남기는 설계였습니다.

도달한 결론은 심플합니다.

AI의 해석 정밀도와 인수인계성은 입력의 구조화로 결정된다. 그러므로 인간 측에서 「AI를 위한 메타데이터」를 미리 준비한다.

구체적으로는 다음의 3종 세트입니다.

• 명명 규칙 (Naming Convention) — 파일명에 「역할」을 심는다
• 디렉터리 구조 (Directory Structure) — AI가 탐색하기 쉬운 계층으로 만든다
• 인수인계 문서 — 자기 완결적인 하나의 문서로 집약한다

xlsx 해석 스킬과 같은 도구 고유 기능도 사용하지만, 본질은 이 투박한 3가지 포인트입니다. 순서대로 설명하겠습니다.

이 안건에서 가장 효과적이었던 것이 명명 규칙이었습니다. 계기는 인수인계 자료를 만들 때 제가 스스로 내린 한 마디의 지시였습니다.

「
AI에게 읽히는 것이 파일명만 보고도 알 수 있게 해줘
」

이 발상이 핵심이었습니다. 파일명은 사람을 위한 것뿐만 아니라, AI에 대한 첫 번째 메타데이터이기도 하다는 것입니다.

실제로 채택한 명명이 이것입니다.

# Before (용도도 최신성도 불명)
조사결과_최종_v2.xlsx
# After (서두에서 「AI용 인수인계 문서」라고 선언)
...

포인트는 식별자를 맨 앞에 두는 것입니다. AI인수인계프롬프트_로 시작하고 있다면, 폴더를 ls 했을 때 AI도 사람도 「이것은 AI에게 전달할 것을 전제로 한 자기 완결적 문서다」라고 즉시 판단할 수 있습니다. 뒤에 붙이면 비슷한 이름의 파일들에 묻혀 효과가 떨어집니다.

명명 템플릿으로는 다음과 같은 형태가 정착되었습니다.

<용도 접두사>_<대상>_<내용>.md
예시: AI引き継ぎプロンプト_顧客基盤_追加開発.md
仕様メモ_認証API_エラーコード一覧.md

또 하나 은근히 효과적인 것이 **연번 접두사 (Serial Number Prefix)**입니다. 자료 폴더는 번호를 붙여 정렬해 두었습니다.

01_개발안건/
step_2026/
02_자료/
...

01_, 02_와 같은 숫자를 앞에 붙이면, 파일 시스템의 정렬 순서가 의미 있는 순서로 고정됩니다. AI에게 폴더를 탐색하게 했을 때, 01_부터 읽기 시작하므로 「전체상 → 상세」라는 인간과 동일한 읽기 순서를 유도할 수 있습니다. 「최종」, 「v2」, 「이거」와 같은 **정서적인 접미사 (Emotional Suffix)**는 최신성 판단을 인간과 AI 모두에게 떠넘기게 되므로 피해야 했습니다.

구분	Before	After
용도 판별	파일을 열기 전까지 불명	도입부 접두사로 즉시 판별
최신 버전 판별	_최종_v2_이거로 혼란	연번 + 업데이트로 유일성 확보
AI 탐색 지시	"전부 읽어줘"	"AI引き継ぎ~를 읽어줘"로 충분

명명과 짝을 이루는 것이 폴더 구조입니다. 원칙은 **「1폴더 = 1컨텍스트 (Context)」**입니다. 하나의 폴더를 열었을 때, 그곳에 있는 자료만으로 하나의 완결된 문맥이 마무리되도록 합니다.

채택한 계층 구조는 다음과 같은 이미지입니다.

01_개발안건/
└─ step_2026/ # 공정·시기
└─ 02_자료/ # 자료 종류
...

의도는 세 가지입니다.

• 안건 → 공정 → 자료 종류 → 개별 안건으로 계층을 나눔으로써, AI에게 「어디를 기점으로 읽을지」 지시하기 쉬움
• 각 안건 폴더에 입구가 되는 인수인계 문서를 하나 배치함으로써, 「먼저 이 폴더의 AI引き継ぎ~를 읽어줘」라는 지시만으로 탐색이 시작됨
• 가공되지 않은 xlsx / csv와 AI용 .md를 같은 폴더에 공존시켜, 인수인계 문서에서 원본 데이터를 참조할 수 있도록 함

너무 깊게 파고들지 않는 것도 요령입니다. 계층이 깊으면 AI도 경로 지정 시 길을 잃습니다. 「몇 번의 클릭만으로 목적의 컨텍스트에 도달할 수 있는」 정도가 현실적이었습니다.

이 부분은 도구(Claude Code)에 의존하는 부분입니다. Claude Code에는 xlsx를 해석하는 기술이 있어, xlsx 파일을 전달하면 시트 구성이나 셀 값을 프로그램적으로 읽어 들여 구조를 파악해 줍니다.

다만, 제가 배운 운용의 요령은 **「가공되지 않은 xlsx를 매번 AI에게 계속 전달하지 않는 것」**입니다. 흐름은 다음과 같이 구성했습니다.

[원본 xlsx] --(xlsx 해석 기술로 단 한 번 해석)--> [구조를 정리한 Markdown] --> 이후에는 이것을 읽게 함

예를 들어, 셀 병합이 가득한 기능 목록 시트는 AI에게 난관이지만, md화(Markdown화)를 통해 「1행 1레코드」로 정규화됩니다.

Before (xlsx의 모습: 기능 ID가 세로로 병합되어 행의 경계가 모호함)

┌────────┬──────────────────┬──────────┬──────────┐
│ 기능ID │ 기능명 │ 대응 상황 │ 비고 │
├────────┼──────────────────┼──────────┼──────────┤
...

After (md화: 병합을 해제하고 값을 보완. AI와 인간 모두 유일하게 읽을 수 있음)

| 기능ID | 기능명 | 대응 상황 | 비고 |
|--------|------------|----------|----------|
| F-01 | 로그인 | 완료 | -
...

이렇게 해두면, 나중에 「미대응 기능만 추출해줘」라고 요청해도 AI가 병합된 셀을 잘못 해석하여 로그인 항목까지 포함해 버리는 등의 사고가 발생하지 않습니다.

이유를 정리하면 다음 세 가지입니다.

• xlsx는 셀 병합이나 여러 시트로 인해 매번 파싱 (Parsing) 시 오차가 발생한다. 한 번 깔끔하게 .md (표 형식)로 내려받으면 이후에는 안정적으로 읽을 수 있다.
• Markdown 표는 인간과 AI 모두에게 유일하게 읽히므로, 인수인계 문서에 그대로 전기할 수 있다.
• 가공되지 않은 xlsx보다 토큰 효율 (Token Efficiency)이 좋아, 필요한 항목만 추출할 수 있다.

즉, xlsx 해석 기술은 「변환기」로서 한 번 거쳐 가는 것이 효율적이라는 활용법입니다. 해석 결과를 인수인계 문서 안에 포함해 버리면, 제삼자는 원본 xlsx를 열지 않고도 전체를 파악할 수 있습니다.

보충: 이 "한 번만 구조화한 뒤 이후에는 경량 포맷을 재사용한다"는 사고방식 자체는 툴에 의존하지 않는 범용 테크닉입니다(후술).

3종 세트의 마무리는 바로 인수인계 문서 자체의 설계입니다. 채팅 이력에 쌓인 조사 흐름을, **그 문서 한 장만 읽으면 재현할 수 있는 자기 완결적 문서 (Self-contained document)**로 녹여내는 것입니다.

실제로 만든 것은 총 10장 구성이었지만, 골자는 이 템플릿으로 일반화할 수 있습니다.

장0. AI를 위한 첫 번째 지시 ← 가장 중요. 진행 방식·엄수 사항·전제
장1. 목적·배경 ← 왜 이 작업을 하고 있는가
장2. 대상 시스템·사양 ← 무엇을 다루는가 (xlsx 해석 결과는 여기에 포함)
...

이 중에서 효과가 차원이 달랐던 것이 바로 **장0 「AI를 위한 첫 번째 지시」**입니다.

인수인계 문서를 다른 AI 세션(또는 다른 사람 + AI)에 전달할 때, 문서의 서두에 갑자기 "당신을 위한 지시"를 써 두면, AI가 즉시 올바른 모드로 동작하기 시작합니다. 실제로 넣었던 것은 다음과 같은 취지의 서문입니다.

## 장0. 이 문서를 읽는 당신(AI)을 위한 지시
- 이 파일은 과거의 조사를 인수인계하기 위한 자기 완결적 문서입니다.
- 먼저 모든 장을 통독하고, 불명확한 점은 추측으로 채우지 말고 저(사용자)에게 확인해 주세요.
...

포인트는 "데이터"보다 먼저 "행동 지침(Behavioral instructions)"을 배치하는 것입니다. 사양서 본문을 갑자기 읽게 하면 AI는 멋대로 해석해서 달려나가기 쉽지만, 장0에서 "통독한 뒤에·확인하면서·근거를 제시하며"라고 틀을 잡아두면, 폭주나 성급한 판단이 눈에 띄게 줄었습니다. 이는 인간의 인수인계에서 "먼저 작업 방식을 합의하는 것"과 같습니다.

여기까지에서 Claude Code 고유한 것은 ③의 xlsx 해석 기술 정도이며, 나머지는 툴을 불문하고 효과가 있습니다. 정리하면 다음과 같습니다.

테크닉	툴 의존도	범용화 포인트
① 명명 규칙 (용도를 서두에·연번)	없음	어떤 LLM이든 명시적인 파일명은 탐색 비용을 낮춤
...

요컨대, 본질은 **"AI에게 전달하기 전에, 인간이 문맥을 구조화해 두는 것"**이라는 한 점입니다. 이는 모델이 똑똑해져도 변하지 않습니다. 오히려 똑똑한 모델일수록 좋은 입력에 솔직하게 반응합니다.

새로운 프로젝트 폴더를 만들 때, 저는 이 리스트를 확인합니다. 복사해서 사용하세요.

□ 폴더명·파일명에 연번 프리픽스(01_ 02_…)를 붙였는가
□ AI에게 전달할 파일은 용도를 서두에 적었는가 (예: AI_인수인계_프롬프트_◯◯.md)
□ "_최종", "_v2", "_이거"와 같은 모호한 접미사를 사용하지 않았는가
...

Excel 사양서를 AI에 활용하는 열쇠는 화려한 프롬프트 테크닉이 아니라, 수수한 메타데이터 관리였습니다. 되돌아봤을 때 효과적이었던 것은 다음 4가지입니다.

명명 규칙: 파일명 서두에 "용도"를 삽입 (AI_인수인계_프롬프트_...). 연번으로 순서를 고정
디렉토리 구조: 1폴더 1컨텍스트. 입구가 되는 인수인계 문서를 반드시 배치
xlsx 해석 기술: 원본 xlsx는 한 번만 구조화하고, 이후에는 경량화된 Markdown을 재사용
자기 완결적 인수인계 문서: 장0에서 "AI를 위한 지시"를 먼저 확립하여, 문서 한 장으로 재현 가능한 형태로 구성

"AI 시대의 메타데이터 관리"라고 하면 거창해 보이지만, 하고 있는 일은 미래의 자신(과 AI)이 헤매지 않도록 이름과 위치와 서문을 정리하는 것뿐입니다. AI 에이전트를 진지하게 업무에 활용하고 싶다면, 프롬프트를 다듬기 전에 먼저 전달할 자료의 기초를 다져보세요. 해석 정밀도와 인수인계성이 놀라울 정도로 달라질 것입니다.