요약 — 지금까지 다룬 AI 에이전트, 프롬프트·컨텍스트 엔지니어링, 하네스 엔지니어링, 에이전틱 엔지니어링은 개념만 읽어서는 감이 잘 안 옵니다. 이 글은 간단한 “가계부 요약 앱”을 함께 만들면서, 네 개념을 한 단계씩 그대로 따라 하며 실습합니다. 실제 화면 대신, 각 단계마다 “무엇을 입력하고 AI가 어떻게 반응하는지” 예시 대화를 그대로 실어뒀습니다. Claude Code, Codex, Cursor 등 코드를 다룰 수 있는 AI 에이전트라면 어디서든 따라할 수 있습니다.
지금까지 이 시리즈에서 네 편을 다뤘습니다.
- AI 에이전트란 무엇인가 — Context Window, Subagent, Skill, MCP
- 프롬프트 엔지니어링과 컨텍스트 엔지니어링
- 하네스 엔지니어링
- 에이전틱 엔지니어링과 PH-AH 루프
개념은 이해했어도, 직접 손으로 해보지 않으면 잘 안 남습니다. 이번 글에서는 아주 단순한 예제 하나로 네 개념을 순서대로, 한 걸음씩 실습합니다.
아직 AI 코딩 에이전트를 설치하지 않으셨다면: 환경 설정 가이드를 먼저 따라 하시면, 이 글의 모든 예시를 그대로 같은 환경에서 실습하실 수 있습니다. 이미 쓰고 있는 도구가 있다면 그대로 진행하셔도 됩니다 — 아래 내용은 특정 도구에 종속되지 않습니다.
이미지에 대해: 이 실습은 어떤 AI 에이전트 도구를 쓰느냐에 따라 화면이 전부 다르게 생겼습니다. 그래서 특정 도구의 스크린샷을 넣는 대신, 각 단계에서 실제로 입력할 문장과 AI가 돌려줄 만한 응답 예시를 그대로 코드블록으로 넣었습니다. 직접 실습하실 때 각 단계에서 화면을 캡처해두시면, 나중에 이 글에 실제 스크린샷을 추가하기 좋습니다 (아래 각 Step 끝에
[스크린샷 위치]표시를 남겨뒀습니다).
실습 준비
- 필요한 것: 코드를 다룰 수 있는 AI 에이전트 도구 (Claude Code, Codex, Cursor, AI Pro 등 무엇이든 가능)
- 실습 주제: 하루 지출 내역을 입력하면, 항목별 합계와 가장 많이 쓴 항목을 알려주는 아주 단순한 웹 화면
- 소요 시간: 40~50분
- 사전 준비: 컴퓨터에 빈 폴더 하나 생성 (예:
budget-practice)
프로그래밍을 몰라도 괜찮습니다. 이 실습의 목적은 코드를 배우는 게 아니라, AI 에이전트와 협업하는 절차를 몸에 익히는 것입니다.
Step 1. 컨텍스트 엔지니어링 — 규칙 파일 먼저 만들기
1-1. 폴더를 열고 에이전트를 실행한다
만들어둔 budget-practice 폴더에서 AI 에이전트를 실행합니다. (Claude Code라면 터미널에서 claude, Codex라면 codex, Cursor라면 폴더를 열고 채팅창을 사용합니다.)
[스크린샷 위치: 빈 폴더에서 에이전트를 처음 실행한 화면]
1-2. AGENTS.md 파일을 만들도록 요청한다
바로 이렇게 입력합니다.
AGENTS.md 파일을 만들어줘. 내용은 이렇게 적어줘.
- 프로젝트 설명: 하루 지출 내역을 입력하면 항목별 합계와
가장 많이 쓴 항목을 보여주는 단순한 웹 화면을 만드는 프로젝트다.
- Backend는 Python 파일 하나로, Frontend는 HTML 파일 하나로 만든다.
- 내가 명시적으로 요청한 것 외에는 아무것도 하지 않는다.
- 서버는 내가 직접 실행하니 자동으로 실행하지 않는다.AI가 이렇게 반응할 가능성이 높습니다 (에이전트마다 표현은 다를 수 있습니다):
AGENTS.md 파일을 생성하겠습니다.
[파일 생성 권한 요청]
- Allow once: 한 번만 허용
- Always allow: 이번 세션에서 Write는 항상 허용
- Reject: 거절이런 권한 확인 창이 뜨면 Allow once 또는 Always allow를 선택하면 됩니다. 처음이라 낯설 수 있는데, “이 에이전트가 파일을 만들어도 되는지” 사람에게 확인받는 절차이니 당황하지 않아도 됩니다.
1-3. 결과 확인
파일 탐색기(또는 에이전트 화면)에서 AGENTS.md 파일이 실제로 생겼는지, 내용이 요청한 대로 들어갔는지 열어서 확인합니다.
[스크린샷 위치: 생성된 AGENTS.md 파일 내용]
이 파일이 바로 2편에서 다룬 컨텍스트 엔지니어링의 실제 적용입니다. 앞으로 이 프로젝트에서 나오는 모든 지시를 AI가 이 파일을 기준으로 이해하게 됩니다.
왜 이 순서가 중요한가: 이 파일 없이 바로 “가계부 앱 만들어줘”라고 하면, 매번 세부 규칙을 새로 설명해야 하고 결과도 그때그때 달라집니다. 규칙을 먼저 정해두면 이후 모든 지시가 짧아지고 일관됩니다.
Step 2. PH-AH 루프 — 계획부터 확인받기
2-1. 계획만 요청하고, 코드는 아직 시키지 않는다
4편에서 다룬 PH-AH 루프의 Plan 단계입니다. 곧바로 “만들어줘”라고 하지 않는 것이 핵심입니다.
지출 항목(식비, 교통비, 문화생활비 등)을 입력하면 합계와
최다 지출 항목을 보여주는 화면을 만들 계획을 세워줘.
코드는 아직 작성하지 마. 어떤 순서로 만들 것인지만 알려줘.AI의 계획 응답 예시:
다음 순서로 진행하겠습니다.
1. Backend(main.py): 지출 항목을 저장하고 합계를 계산하는
간단한 API 서버를 FastAPI로 만든다.
2. Frontend(index.html): 지출 항목(이름, 금액)을 입력하는 폼과
결과(합계, 최다 지출 항목)를 보여주는 화면을 만든다.
3. Backend 서버를 실행해서 Frontend와 연결이 되는지 확인한다.
4. 지출 항목 3~4개를 직접 입력해서 계산이 맞는지 테스트한다.
이 순서로 진행해도 될까요?2-2. 계획을 검토하고, 이상하면 이 시점에서 고친다
계획을 읽어보고 질문해봅니다. 예를 들어:
2번에서 항목 이름은 미리 정해진 목록(식비/교통비/문화생활비)
중에서 고르게 해줘. 자유 입력이 아니라 드롭다운으로.AI가 계획을 수정해서 다시 보여주면, 그때 확정합니다.
좋아, 그 계획대로 진행해줘.[스크린샷 위치: AI가 제시한 계획 전체 화면]
이 단계를 건너뛰면 안 되는 이유: 계획 확인 없이 바로 코드를 만들게 하면, 방향이 잘못됐을 때 이미 많은 코드가 만들어진 뒤에야 알아차리게 됩니다. 계획 단계에서 몇 분 확인하는 것이, 나중에 전부 다시 만드는 것보다 훨씬 쌉니다.
Step 3. Action 확인 — 결과를 검토하고 확정하기
3-1. 실행을 요청한다
계획이 확정됐으니 이제 실제로 만들게 합니다.
계획대로 Backend(main.py)부터 만들어줘.AI가 코드를 작성하고 나면, 다음과 같이 서버 실행을 요청합니다.
서버를 실행해줘. 코드 수정 시 자동으로 반영되게 해줘.3-2. 직접 눈으로 확인한다
브라우저에서 안내받은 주소(보통 http://localhost:8000 같은 형태)를 열어, 지출 항목을 2~3개 입력해서 합계가 맞게 나오는지 직접 확인합니다.
예시로 넣어볼 데이터
| 항목 | 금액 |
|---|---|
| 식비 | 15,000원 |
| 교통비 | 3,000원 |
| 식비 | 8,000원 |
이렇게 입력했을 때 “식비 합계 23,000원, 최다 지출 항목: 식비”가 정확히 나오는지가 확인 포인트입니다.
[스크린샷 위치: 실제 브라우저에 뜬 화면, 지출 입력 후 결과]
3-3. 확인 결과를 AI에게 알려준다
잘 동작하면:
확인했어, 잘 동작해. 이제 다음 기능을 추가하자.문제가 있으면 그 자리에서 구체적으로 알려줍니다:
식비 합계가 잘못 나와. 15,000 + 8,000 = 23,000이어야 하는데
21,000으로 나오고 있어. 계산 로직을 확인해줘.이렇게 계획 확정 → 실행 확정을 매 기능마다 반복하는 것이 PH-AH 루프입니다. 지금까지 한 사이클(계획 단계와 실행 단계)을 실제로 한 번 돌아본 셈입니다.
Step 4. Subagent로 나눠보기
4-1. Subagent 두 개를 만들도록 요청한다
1편에서 다룬 Subagent 개념을 적용합니다. “화면을 만드는 일”과 “합계 계산이 맞는지 검증하는 일”을 나눕니다.
이 프로젝트에 Subagent 두 개를 만들고 싶어.
하나는 "화면 담당"으로 HTML 화면 작업만 맡고,
다른 하나는 "검증 담당"으로 합계 계산 로직에 오류가
없는지만 확인해. 각각의 역할을 정의한 파일을 만들어줘.AI 응답 예시: 에이전트에 따라 .agents/ 폴더 안에 screen-agent.md, verify-agent.md 같은 파일이 만들어지고, 각 파일 안에 역할 설명이 담깁니다.
[스크린샷 위치: 생성된 Subagent 파일 목록과 내용]
4-2. 새 기능을 Subagent에게 순서대로 시켜본다
이제 새 기능(지출 항목별 비율 %표시)을 추가하면서, Subagent를 명시적으로 호출해봅니다.
지출 항목별 비율을 %로 보여주는 기능을 추가하려고 해.
반드시 아래 순서로 진행해줘.
1. 화면 담당 Subagent가 화면에 % 표시를 추가한다.
2. 검증 담당 Subagent가 % 계산이 정확한지 확인한다.왜 나눠서 시켰을 때 결과가 더 안정적인지 직접 비교해보면 체감이 됩니다. 하나의 에이전트에게 “화면도 만들고 계산도 검증해줘”라고 한 번에 시켰을 때와, 역할을 나눠 시켰을 때 결과의 꼼꼼함이 다르게 느껴지는 경우가 많습니다. 특히 검증 담당이 실제로 숫자를 검산해서 “3개 항목 비율 합이 100%가 맞는지 확인했습니다”처럼 구체적으로 보고하는지 지켜보세요.
Step 5. Skill로 반복 작업 저장해두기
5-1. 반복될 것 같은 요청을 하나의 명령으로 만든다
지출 요약을 볼 때마다 같은 형식의 요청을 반복할 것 같다면, 1편에서 다룬 Skill로 저장해둘 수 있습니다.
방금 요청한 "이번 달 지출 요약 + 상위 3개 항목 정리"를
매번 다시 설명하지 않도록, 하나의 명령(Skill)으로 만들어줘.AI 응답 예시:
Skill을 만들었습니다. 앞으로는 아래처럼 짧게 요청하시면 됩니다.
/monthly-summary5-2. 실제로 짧아졌는지 확인한다
새로 만든 명령어로 다시 요청해봅니다.
/monthly-summary전에 길게 설명해야 했던 요청이 한 줄로 줄어든 것을 확인합니다.
[스크린샷 위치: Skill 명령어 실행 전/후 비교]
Step 6. 하네스 규칙 추가해서 안정성 높이기
6-1. 검산 규칙을 AGENTS.md에 추가한다
마지막으로 3편에서 다룬 하네스 엔지니어링을 적용합니다. 지금까지는 매번 사람이 직접 결과를 확인했지만, 실수를 미리 막는 규칙도 추가해봅니다.
AGENTS.md에 규칙을 추가해줘. 합계나 비율 계산 코드를
수정할 때는, 수정 후 반드시 예시 데이터로 계산 결과를
직접 검산해보고 그 결과를 함께 보고해.
검산 없이는 완료로 보고하지 마.6-2. 규칙이 실제로 적용되는지 테스트한다
계산 로직을 한 번 더 수정해달라고 요청해봅니다.
교통비도 카테고리를 대중교통/택시로 나눠서 따로 집계해줘.규칙 추가 전이라면 이렇게 끝났을 것입니다.
완료했습니다. 대중교통과 택시로 나눠서 집계하도록 수정했습니다.규칙 추가 후에는 이런 식으로 검산 결과까지 함께 나오는 것을 확인할 수 있습니다.
완료했습니다. 대중교통과 택시로 나눠서 집계하도록 수정했습니다.
[검산 결과]
- 예시 데이터: 대중교통 3,000원 x 2건, 택시 8,000원 x 1건
- 대중교통 합계: 6,000원 (직접 계산: 3,000 + 3,000 = 6,000 ✓)
- 택시 합계: 8,000원 (직접 계산: 8,000 = 8,000 ✓)
검산 결과 정상입니다.[스크린샷 위치: 규칙 추가 전후 응답 비교]
이게 바로 하네스가 실제로 결과물의 신뢰도를 끌어올리는 방식입니다.
실습 정리 — 무엇을 했는지 다시 보기
| 단계 | 실습 내용 | 해당 개념 |
|---|---|---|
| Step 1 | AGENTS.md로 프로젝트 규칙 미리 정의 | 컨텍스트 엔지니어링 |
| Step 2 | 코드 작성 전 계획부터 확인 | 에이전틱 엔지니어링 (PH-AH 루프 · Plan) |
| Step 3 | 실행 결과를 직접 확인 후 확정 | 에이전틱 엔지니어링 (PH-AH 루프 · Action) |
| Step 4 | 화면 작업과 검증 작업을 역할별로 분리 | AI 에이전트 기본 개념 (Subagent) |
| Step 5 | 반복 요청을 하나의 명령으로 저장 | AI 에이전트 기본 개념 (Skill) |
| Step 6 | 검산 없이는 완료 보고 금지 규칙 추가 | 하네스 엔지니어링 |
프롬프트 엔지니어링은 이 실습 전체에서 매 순간 함께 쓰였습니다 — AI에게 건넨 모든 지시 문장 하나하나가 프롬프트 엔지니어링의 실전 적용입니다.
더 도전해볼 과제 5가지
가계부 앱 하나로 감이 잡혔다면, 아래 과제로 난이도를 조금씩 올려가며 같은 절차(컨텍스트→계획 확인→실행 확인→Subagent→Skill→하네스)를 반복해보세요. 난이도 순으로 정리했습니다.
1. 할일 관리 앱 (난이도: 하)
할일을 추가·완료 처리하는 단순한 화면. 가계부 실습과 구조가 비슷해서 몸풀기로 좋습니다. Subagent를 “화면 담당”과 “마감일 임박 항목 알림 담당”으로 나눠보세요.
2. 여러 도시 날씨 요약기 (난이도: 하~중)
미리 정해둔 도시 3~4곳의 날씨 정보를 정리해서 보여주는 도구. “매번 같은 형식으로 정리해줘”가 반복되는 상황이라 Skill 연습에 특히 적합합니다.
3. 독서 기록 앱 (난이도: 중)
읽은 책 제목·평점·한줄평을 기록하고, 월별 통계(가장 많이 읽은 장르 등)를 보여주는 앱. Subagent를 “기록 담당”, “통계 담당”, “추천 담당” 세 개로 나눠보면 1편에서 다룬 “역할을 나눌수록 결과가 안정적인 이유”를 더 분명하게 체감할 수 있습니다.
4. 팀 회의록 요약 도구 (난이도: 중~상)
회의록 텍스트를 붙여넣으면 결정사항과 액션 아이템을 구분해서 정리해주는 도구. 하네스 규칙을 강하게 걸어보는 연습에 좋습니다 — 예를 들어 “결정사항과 액션 아이템을 구분하지 못했다면 요약을 완료로 보고하지 마” 같은 규칙을 추가하고, 실제로 애매한 회의록을 넣었을 때 AI가 스스로 판단을 보류하는지 확인해보세요.
5. 웹사이트 방문자 로그 분석기 (난이도: 상)
하네스 엔지니어링 원본 강의교안에서도 다룬 주제와 비슷한, 조금 더 도전적인 과제입니다. 가상의 로그 파일(요청 시각, 응답 시각)을 만들어 API 응답 속도를 계산하고 그래프로 시각화하는 도구를 만들어보세요. 1편에서 다룬 MCP를 실제로 연결해서(예: 브라우저 자동화 MCP로 완성된 그래프 화면을 스크린샷까지 찍게 하는 것) 지금까지 배운 네 개념 — 에이전트 기본 구조, 컨텍스트, 하네스, PH-AH 루프 — 을 전부 한 프로젝트에 담아보는 것이 목표입니다.
다음으로 해볼 것
이 실습들은 실제 업무보다 축소된 형태입니다. 업무에 적용할 때는:
- AGENTS.md에 회사·팀의 실제 규칙을 담아보세요
- 반복되는 업무 패턴을 Skill로 하나씩 저장해보세요
- 중요한 작업일수록 PH-AH 루프의 확인 단계를 건너뛰지 마세요
다섯 편의 개념·실습 글을 한 번씩 따라 해봤다면, 다음에 AI 에이전트로 실제 업무를 진행할 때 “왜 결과가 이렇게 나왔지” 대신 “이 부분에 컨텍스트를 더 줘야겠다”, “이건 Subagent로 나눠야겠다” 같은 판단이 조금은 더 쉬워질 것입니다.