이걸 왜 못 알아듣지?
AI를 처음 사용할 때 가장 먼저 들었던 생각은 답답함이었습니다. 분명히 원하는 내용을 전달했다고 생각했는데 결과물을 확인해보면 제가 기대한 것과는 다른 방향으로 작업되어 있는 경우가 많았습니다.
그럴 때마다 결과를 보며
- 아, 이 부분은 설명하지 않았구나
- 나는 당연하다고 생각했는데 얘는 다르게 이해했네
- 이 조건도 미리 말했어야 했는데
하는 생각이 들어서
저는 다시 설명을 덧붙이고, AI는 수정된 결과를 보여주고,
저는 또 다시 부족한 부분을 발견하는 과정을 반복했습니다.
처음에는 이를 AI의 한계라고 생각했습니다. 하지만 프로젝트를 진행하면서 문제는 AI가 부족해서가 아니라 내가 생각하는 방향과 AI가 이해한 방향이 서로 달랐다는 것을 깨달았습니다. 사람과 사람의 협업과 크게 다르지 않은 것 같습니다. 같은 목표를 가지고 있더라도 기준과 맥락이 충분히 공유되지 않으면 결과는 쉽게 어긋납니다. 원하는 결과를 얻기 위해서는 단순히 명령을 내리는 것이 아니라 목표와 의도, 중요하게 생각하는 기준을 함께 전달하며 지속적으로 방향을 맞춰나가야 했습니다.
이 아티클은 이러한 경험에서 시작되었습니다. 실제 프로젝트를 진행하며 AI에게 무엇을 어떻게 전달했는지, 단순히 질문하는 사람에서 AI와 방향을 맞추며 협업하는 사람으로 어떻게 변화했는지를 기록해보고자 합니다.
AI Agent vs Agentic AI
먼저, AI Agent와 Agentic AI는 다른 개념입니다.
Agentic AI는 이론적으로 가능한 자율 AI의 모습이고 AI Agent는 지금 우리가 실제로 쓰는 현실적인 버전입니다.
(Claude Code가 바로 AI Agent에 해당)
클로드는 작업 중에 스스로 결정하지 않고 주어진 지시와 파일 안에서, 정해진 도구만 사용해서 움직입니다.
자율적으로 보이지만 사람이 그려진 테두리 안에서 움직이는 존재인 것이죠,,
이 차이를 인식하는 것은 중요합니다. 우리는 종종 AI가 알아서 의도를 파악하고 원하는 결과를 만들어주기를 기대합니다.
하지만 AI는 사용자가 전달한 정보와 맥락 안에서만 움직이기 때문에 이 기대와 현실의 차이가 AI를 사용할 때 느끼는 답답함의 원인이 되는거죠.
AI Agent는 어떻게 작업을 처리하는가
1. 매번 새로운 사람으로 시작한다
AI Agent는 이전 대화나 이전 작업을 기억하지 못합니다.
새 세션이 시작되면, 그 순간 주어지는 정보(대화 내용, 읽을 수 있는 파일들)가 다인거죠.
2. 컨텍스트 안에서만 판단한다
AI Agent는 추론은 할 수 있지만 추론의 재료는 오직 주어진 컨텍스트뿐입니다.
프로젝트에 어떤 컨벤션이 있는지, 어떤 패턴을 써야 하는지는 누군가 알려주거나 직접 코드를 읽어서 추측하는 수밖에 없습니다.
3. 계획 → 실행 → 확인을 반복한다
AI Agent는 한 번에 정답을 내놓는 게 아니라
이 작업을 하려면 어떤 파일을 봐야하지?
→ 파일 읽기
→ 코드 수정
→ 제대로 됐나..
같은 단계를 여러 번 거칩니다. 이 과정에서 가진 정보가 부족하면 부족한 부분을 나름의 방식으로 추측해서 채웁니다.
이 단계에서 사용자가 원하지 않는 결과가 나오게 되는 것이죠.
위 세 가지를 합쳐보면
AI Agent는 매번 새로 시작하고, 주어진 정보 안에서만 판단하고, 부족한 정보는 추측으로 채웁니다.
그렇다면 추측의 빈틈을 줄이기 위해서는 매번 설명하는 대신, 참고할 수 있는 고정된 정보를 파일로 만들어두면 되겠죠?
그게 바로 제가 이번 시간에 사용할 CLAUDE.md입니다.
CLAUDE.md는 단순히 규칙 문서가 아니라 AI Agent가 매번 새로운 사람으로 시작할 때마다 잃어버리는 맥락을 채워주는 장치입니다. CLAUDE.md에 다음과 같은 내용을 추가했습니다.
- 프로젝트 개요 + 기술 스택
## 프로젝트 개요
**Stumate**는 사용자의 공부 습관과 학습 흐름을 기록하고, 이를 기반으로 학습 효율 향상 및 피드백을 제공하는 모바일 웹 서비스입니다.
- **기술 스택**: React 19, TypeScript, Vite, Tailwind CSS v4
- **모바일 웹 기준**: max-width 430px
- **패키지 매니저**: pnpm
- 명령어: dev/build/lint 등 AI가 실행할 수 있는 정확한 커맨드
## 주요 명령어
```bash
pnpm dev # 개발 서버 실행
pnpm build # 프로덕션 빌드
pnpm lint # ESLint 실행
pnpm preview # 빌드 결과 미리보기
```
- 절대 금지 사항
## 🚨 절대 금지 사항
> **IMPORTANT: 다음 조작은 어떠한 경우에도 절대 실행하지 않는다**
```bash
git push --force # 강제 푸시 금지
git reset --hard # 하드 리셋 금지
git commit --no-verify # 훅 우회 금지
git push origin main # main 직접 푸시 금지 (PR 필수)
pnpm audit fix --force # 강제 패키지 업데이트 금지
rm -rf # 디렉토리 강제 삭제 금지
```
- `.env` 파일 내용을 로그·출력·코드에 포함하지 않는다
- API 키·비밀번호·토큰을 코드에 하드코딩하지 않는다
- 라이브러리 버전을 임의로 변경하지 않는다
- 이 외에도 폴더 구조, 브랜치/커밋 컨벤션, 코드 컨벤션을 추가했습니다.
즉, 이 프로젝트에서 코드를 어떻게 짜고 어디에 두고 어떻게 커밋할지에 대한 고정된 약속이 담긴 문서입니다.
CLAUDE.md 파일을 어디에 둘까?
- ./CLAUDE.md (프로젝트 루트) — Git으로 공유되는 팀 규칙
- ~/.claude/CLAUDE.md (홈 디렉토리) — 개인 설정
저는 코드 컨벤션, 폴더 구조, 브랜치 규칙처럼 팀원 모두가 따라야 하는 내용을 다루고 있어서 프로젝트 루트에 뒀습니다.
CLAUDE.md를 만들고 나니 폴더 위치가 엉뚱하거나 컨벤션을 무시하는 문제는 확실히 줄었습니다.
그런데 작업을 진행하다보니, 컨벤션과는 상관없는 문제들이 하나둘 보이기 시작했습니다
1. 전역 파일을 맘대로 건드림
뭔 짓을 해도 패딩이 안 먹더라구요..
global.css 파일을 확인해보니
* {
margin: 0;
padding: 0;
}padding:0이 Tailwind의 px-7을 덮어쓰고 있었습니다.
AI Agent는 주어진 문제를 해결하는데 집중하지 프로젝트 전체 맥락까지 항상 고려하는 것은 아니기 때문에 전역 스타일이나 공통 설정 파일을 수정하는 경우에는 더욱 주의가 필요합니다. 원하는 결과가 나왔더라도 어떤 파일이 변경되었는지 그 범위까지 함께 검토하는 과정이 필요한 것 같아요.
2. 내가 수정한 파일 덮어씀
분명 제가 수정한 내용이 있었는데 다음 작업을 요청한 뒤 확인해보니 해당 내용이 통째로 사라져 있었습니다..
AI Agent가 필요한 부분만 수정한 것이 아니라 파일 전체를 다시 작성하면서 제가 추가한 내용까지 덮어써버린 것이었죠..
그래서 CLAUDE.md 파일에 수정 규칙을 추가했습니다. 무엇을 수정할지뿐만 아니라 어떻게 수정할지도 명확히 알려주자..
3. 필요 없는 파일 생성
저는 shared/ui 하위 컴포넌트에서 index.ts를 사용하지 않고 필요한 파일을 직접 import하는 방식을 사용하고 있었습니다.
근데 컴포넌트 생성할때마다 파일이 너무 많아져서 확인해보니 index.ts 파일을 함께 만들고 있더군요..
많은 프로젝트에서 Barrel Export 패턴을 사용하기 때문에 일반적인 관례로 판단한 거겠죠..
하지만 제 프로젝트 구조와는 맞지 않았고 결과적으로는 불필요한 파일이기 때문에
md파일에 또 추가.
다 알아주길 바라면 안되는 것 같아요.
CLAUDE.md를 통해 프로젝트 규칙은 어느 정도 정리했고,,
이번 작업에서 무엇을 만들어야 하는지 AI에게 잘 전달하려면 어떻게 해야 할까요?
같은 작업을 요청하더라도 설명하는 방식에 따라 결과는 크게 달라집니다.
그래서 AI Agent를 위한 좋은 스펙 작성법에 대해 찾아봤습니다.
AI Agent를 위한 요구사항 작성 가이드
1. 처음부터 완벽하게 쓰지 않기
빈 페이지에서 완벽한 스펙을 쓰려고 하면 막막~합니다. 목표와 핵심 요구사항만 간단히 적고, AI에게 구체적인 스펙으로 확장해달라고 요청하는 게 훨씬 쉽습니다.
2. AI가 질문하게 만들기
스펙을 주고 나서 "진행하기 전에 애매한 부분 있으면 먼저 물어봐"라고 명시적으로 요청합니다.
3. 경계 명시하기
✅ 항상 해도 됨 / ⚠️ 먼저 물어보기 / 🚫 절대 금지
CLAUDE.md에 적었던 규칙들과 같은 형태입니다.
(md파일을 프로젝트 전반의 경계고 스펙은 이번 작업에 한정된 경계라는 차이가 있겠죠)
프로젝트에 적용
먼저 제가 스펙 초안을 작성하고 구체화 해줄 것을 요구하고 헷갈리는 부분을 질문하도록 요청했습니다.
그러면 아래와 같이 클로드가 부족한 부분을 질문했고
제 답변을 바탕으로 구체적이고 명확한 스펙으로 정리해주었습니다.
## **✅ 투두리스트 페이지 확정 스펙**
### **레이아웃**
- 상단 `logo-small` (좌측)
- "투두리스트" 타이틀 중앙, 좌측에 `chevron-left` 아이콘 → `navigate(-1)`
- 그래프 → 날짜 박스 목록 순으로 스크롤 구성
---
### **이번주 공부 시간 그래프 (`shared/ui/BarChart`)**
- **위치**: `shared/ui/BarChart/BarChart.tsx`
- **색상**: 값이 작을수록 `primary(#9DDE78)`, 클수록 `primary-dark(#84C95F)` (선형 보간)
- **Props**:
`interface BarChartProps { data: { label: string; value: number }[]; showValueLabel?: boolean; // 막대 위 값 텍스트 표시 여부}`
- `showValueLabel={true}` → 투두리스트 페이지 (시간 텍스트 표시)
- `showValueLabel={false}` (기본값) → 플래너 페이지
---
### **날짜 박스 (`pages/todolist/components/DateAccordion`)**
- **범위**: 이번 주 월~일 (7개)
- **기본 상태**: 모두 닫힘
- **동시 다중 열기** 가능
- **토글**: 클릭 시 열림/닫힘, chevron-down ↔ chevron-up 전환
- **활성화 시**: 배경색 `primary-light`, 텍스트 `text`, chevron-up
- **비활성화 시**: 배경색 `white`, 텍스트 `text-gray`, chevron-down
- **미래 날짜**: `disabled` (클릭 불가, 비활성 스타일 유지)
- **투두 없는 날짜**: `disabled` (클릭 불가)
---
### **투두 아이템 (`shared/ui/TodoItem`)**
- 기존 컴포넌트 재사용 (피그마와 다르면 파일 수정)
- **완료 시**: 텍스트 색 `text-gray` 변경 (취소선 없음)
- **토글**: 완료 ↔ 미완료 재클릭 가능
- **완료 상태 변경** → API 호출 (플래너 수행률 연동 목적)
- API 연결 전 로컬 state로 관리, `todoApi.ts`에 함수 stub 작성
---
### **Mock 데이터 구조**
`interface Todo { id: string; subject: string; content: string; isCompleted: boolean;}
interface DayTodos { date: string; // 'YYYY-MM-DD' todos: Todo[];}`
---
### **조회 전용**
- 새 투두 추가 입력창 없음, 완료 체크만 가능스펙을 함께 구체화하고 나니 결과물을 받은 뒤 추가 설명을 덧붙이는 일이 눈에 띄게 줄었습니다.
하지만..
AI는 종종 문제를 근본적으로 해결하기보다 현재 발생한 문제를 가장 빠르게 해결하는 방향을 선택하기도 했습니다.
작업 중 한쪽에서는 서로 다른 형식의 dayId를 사용하는 부분이 있었는데 클로드는 이 차이를 맞추기 위해 변환 매핑 로직을 추가했습니다. diff를 검토하던 중 굳이 매핑하지 않고 dayId 자체를 통일하면 되겠다는 생각이 들어 코드를 수정했습니다.
AI는 문제를 만나면 우선 지금 이 자리에서 가장 적게 수정해서 해결할 수 있는 방법을 선택하는 경향이 있다고 느꼈습니다.
다만 이 경험이 반드시 스펙을 더 세세하게 작성해야 한다는 의미는 아닙니다.
실제 개발 과정에서 이런 예외 상황을 어떻게 모두 예상하겠어요?? 오히려 중요한 것은 AI가 제안한 해결 방법을 그대로 받아들이지 않고 왜 이렇게 구현했는지 질문하고 검토하는 과정이라고 생각합니다. AI가 제공한 결과물을 보며 문제의 근본적인 원인을 찾을 수는 없는지, 불필요한 코드가 추가된 것은 없는지 확인하고 다시 질문하는 과정에서 더 나은 구조를 찾을 수 있는 것 같아요.
결국 중요한 것은 AI에게 완벽한 지시를 내리는 것이 아니라 같은 방향을 바라보며 함께 문제를 해결해 나가는 과정인 것 같습니다. AI는 생각보다 많은 일을 빠르게 처리해주지만 항상 개발자가 의도한 최선의 방법을 선택하지는 않으니까요.
그러기 위해서는 개발자인 내가 먼저 다양한 기술과 방법을 경험해 봐야겠지요. 어떤 방식이 더 적절한지 판단하려면 각 선택지의 장단점을 알고 있어야 하고, 그래야 AI가 제안한 결과도 비판적으로 검토할 수 있으니까요.
Before
간단한 조건 몇 개 + 피그마 링크 주고 만들어달라함
After
AI와 스펙 작성 + 스크린샷과 함께 만들어달라함
참고
https://news.hada.io/topic?id=25949
AI 에이전트를 위한 좋은 스펙 작성법 | GeekNews
AI 코딩 에이전트에게 방대한 스펙을 한꺼번에 던지면 제대로 작동하지 않으며, 핵심은 스마트 스펙 작성에 있음 고수준 비전을 먼저 제시하고 AI가 세부 계획을 확장하도록 한 뒤, Plan Mode에서
news.hada.io