AI 활용 — 나만의 개발 워크플로우

1. 요즘은 코드보다 md를 더 많이 읽는다

요즘은 업무를 하면서 직접 코드를 작성하는 시간이 눈에 띄게 줄었다. 불과 1년 전만 해도 디버거를 켜고 VO에 값이 제대로 들어왔는지, 데이터가 어디서 잘못됐는지 하나하나 추적하며 개발했었다.

그런데 지금은 조금 다르다. 하나의 AI에게 구현을 맡기고, 다른 AI에게는 그 결과를 리뷰하게 한다. 두 AI가 작업하는 동안 나는 요구사항에서 빠진 부분을 찾거나, 다음 작업을 설계한다. 작업이 끝났다는 보고가 올라오면 내용을 읽고, 실제 변경 사항을 확인하고, 다음 작업을 지시한다. 그래서 요즘은 코드보다 AI가 남긴 md를 더 많이 읽는다.

그렇다고 코드를 아예 보지 않는 건 아니다. 오히려 AI가 작성한 코드를 어디까지 신뢰할 수 있는지 판단하는 일이 중요해졌다. 실제로 AI가 이미 수정된 버그를 여전히 해결되지 않았다고 보고한 적이 있었다. 알고 보니 변경 전 코드를 기준으로 분석하고 있었다. 이미 끝난 작업을 계속 검증하다가 개발 서버 로그를 잔뜩 쌓아버린 적도 있었다. 이런 문제를 겪을 때마다 규칙을 하나씩 추가했고, 다음 작업을 시작하는 AI가 그 규칙을 먼저 읽도록 했다.

그렇게 시행착오를 반복하다 보니 두 가지가 필요하다는 생각이 들었다.

• 첫째, AI가 코드베이스의 어디를 읽어야 하는지 알려주는 지도.
• 둘째, AI의 “완료했습니다”라는 보고를 실제로 신뢰할 수 있는지 판단하는 검증 절차.

첫 번째는 Graphify로 풀었고, 두 번째는 루프 엔지니어링(Loop Engineering)이라는 이름으로 개발 프로세스를 정리했다. 이 글은 AI에게 일을 어떻게 맡기고, 맡긴 결과를 어떻게 검증하며, 그 과정을 어떻게 반복 가능한 개발 방식으로 만들었는지에 대한 이야기다.

2. Claude Code는 어떻게 일하나

Claude Code에 일을 시키면 모델이 다음에 뭘 할지 정하고 도구를 부른다. 도구가 파일을 읽거나 고치거나 명령을 실행하면, 모델이 그 결과를 보고 또 다음 행동을 정한다.

“목록에 필터 추가해 줘”라고 하면, 관련 화면을 찾고 → 기존 동작을 읽고 → 파일을 고치고 → 빌드 결과를 확인하는 식이다. 공식 문서에서는 이걸 맥락 수집, 행동, 결과 검증의 반복이라고 부른다. Claude Code 동작 원리

중요한 건 AI가 프로젝트 전체를 알고 시작하지 않는다는 점이다. 필요한 파일을 그때그때 열어 보면서 일한다. 지금까지 나눈 대화, 열어 본 파일, 실행 결과, 지침을 통틀어 컨텍스트라고 하는데, 책상 위에 펼쳐 놓은 자료라고 생각하면 편하다. 자료가 너무 쌓이면 대화를 요약하고, 세션이 바뀌면 이전 대화는 남지 않는다. 그래서 계속 필요한 규칙과 결정은 파일로 남겨야 한다. 컨텍스트와 세션

이 반복만으로도 일은 된다. 문제는 세션이 바뀔 때마다 같은 설명을 다시 해야 하고, 프로젝트가 커질수록 “어디를 읽어야 하지?”와 “진짜 끝난 건가?”에서 자꾸 막힌다는 거였다. 이어지는 세 장이 이 빈자리를 하나씩 채운다.

3. 하네스·메모리·오케스트레이션

비유하면 쉽게 기억 가능하다!

매뉴얼을 주고, 지도를 보고 빠르게 일을 찾게 하고, 사람을 나눠 배치하고, 결과를 검수한다. 작업이 끝나면 다음 사람을 위해 인수인계 노트를 남긴다. 사람한테 일 맡길 때랑 크게 다르지 않다…!

하네스 — 목줄이면서 수레

처음엔 하네스를 이렇게 이해했다. AI한테 목줄을 채우는 거.

그런데 하네스는 원래 말에 채우는 마구다. 마구는 말이 엉뚱한 데로 못 가게 잡기도 하지만, 말 힘을 수레 끄는 데 쓰게 해 주기도 한다. AI 매뉴얼도 똑같았다. “하지 마”만 적어서는 부족하고, “이렇게 해”가 같이 있어야 했다.

예를 들어 디자인 목업 프로젝트 루트에 CLAUDE.md를 둔다고 해 보자. Claude Code가 작업할 때마다 읽는 지침 파일이다.

## 하지 말 것
- 요청하지 않은 화면까지 바꾸지 않는다.
- 기획에 없는 동작을 임의로 추가하지 않는다. 빈칸은 질문한다.

## 화면 만들 때
- 기존 화면의 버튼, 간격, 글자 스타일을 먼저 확인한다.
- 화면에 들어갈 조건과 예외를 확인하고 구현한다.
- 완료 보고에 바꾼 화면과 확인한 동작을 적는다.

위쪽이 목줄이고 아래쪽이 수레다. 위쪽만 있으면 AI는 뭘 하면 안 되는지는 알지만, 뭘 만들어야 하는지는 여전히 추측한다.

하나 오해하면 안 되는 게 있다. CLAUDE.md에 적은 건 어디까지나 AI가 참고하는 지시다. 권한 설정처럼 실행 자체를 막아 주지는 않는다. AI가 읽었다고 지켰다는 보장은 없다. Claude Code 메모리 문서

그래서 운영 서버 명령은 AI가 복사해서 붙일 수 있게 써 주기만 하고, 실행은 내가 직접 한다. 명령을 만드는 것과 실행까지 맡기는 건 다른 문제다. 가끔 스레드에 AI가 DB를 날렸다는 글을 보는데.. 무섭다

Claude Code 공식 문서는 CLAUDE.md를 200줄 이내로 쓰라고 권장한다! 길수록 컨텍스트를 많이 차지하고 잘 안 지켜진다. CLAUDE.md 작성법

메모리 — 인수인계 노트

앞에서 본 것처럼 세션이 바뀌면 이전 대화는 남지 않는다. 메모리는 그 빈자리를 메우려고 내가 파일에 직접 적는 인수인계 노트다. (Claude Code가 알아서 쌓는 자동 메모리와는 다르다.) 이번에 정한 것, 확인 못 한 것, 다음에 할 일을 적어 둔다. 그래야 다음 세션의 AI한테 같은 설명을 처음부터 다시 안 해도 된다.

오케스트레이션 — 팀 배치

오케스트레이션은 구현하는 AI와 검토하는 AI를 나눠 앉히는 일이다. 그런데 둘이 같은 추측을 하면 둘 다 통과시킨다. 이건 6장에서 다시 다룬다.

4. Graphify — 어디부터 읽을지 알려 주는 지도

“이 기능 고쳐 줘” 한마디에 AI가 뒤져야 할 파일은 프로젝트가 커질수록 늘어난다. 이 화면이 어떤 함수를 쓰는지, 그 함수가 다른 데서도 쓰이는지, 관련 문서는 어디 있는지. 게다가 새 세션을 열 때마다 이 탐색을 처음부터 다시 한다.

그래서 Graphify를 붙였다. Graphify는 코드와 문서를 읽어서 지식 그래프를 만든다. 함수, 파일, 개념을 점으로 찍고 호출이나 의존 관계를 선으로 이은 지도다. 코드 구조는 구문 분석으로 뽑고, 문서 사이의 의미 관계는 AI로 뽑는다. 결과가 파일로 남기 때문에 다음 세션에서도 그대로 조회할 수 있다. Graphify 프로젝트 설명

다만 지도는 지도일 뿐이다. 이걸 어디까지 믿고 쓰는지는 8장에서 사례와 함께 적는다.

5. 루프 엔지니어링

읽을 곳을 찾았으면 일을 맡긴다. 그런데 AI가 “완료했습니다”라고 하면, 그다음은?

처음엔 매번 직접 쳤다. “테스트 돌려 봐”, “다른 AI한테 리뷰 맡겨”, “그 지적 고쳐”. 몇 번 하다 보니 이 순서와 조건을 미리 정해 두면 되겠다 싶었다. 그게 루프 엔지니어링이다. 에이전트가 돌아가는 루프에 검증, 상태 기록, 반복 횟수 제한, 사람한테 넘기는 지점을 붙이는 방식이다. 루프 엔지니어링 연구

내가 실제로 쓰는 검수 루프는 이렇게 생겼다.

구현이 끝나면 검증과 독립 리뷰를 돌리고, 결함이 남으면 고치고 다시 검증한다. 결함이 없으면 기록하고 끝낸다. 이 루프를 실제로 어떤 규칙으로 돌리는지는 9장에서 적는다.

6. 맡기기 전에: 기획의 빈칸부터 메운다

AI를 몇 명 붙이고 리뷰를 몇 번 돌려도, 기획에 빈칸이 있으면 소용없다.

기획서가 곧 AI 지시서가 된다.

사람한테 모호한 기획은 AI한테도 모호하다. 차이는 속도다. 사람은 멈춰서 물어보는데, AI는 그럴듯한 동작을 금방 만들어 놓는다.

예를 들어 이런 요청이 있다고 하자.

룰 바뀌면 기존 케이스도 반영해 주세요.

어떤 상태까지 바꾸는지, 진행 중인 것도 덮어쓰는지, 안 바꾸는 건 사용을 막는지가 다 빠져 있다. AI는 전부 덮어쓰는 화면을 만들 수도 있고, 확인 창을 띄울 수도 있다. 둘 다 문장만 보면 맞는 구현이다. 화면도 잘 돌아가니 검수에서도 안 걸린다.

같은 요구를 이렇게 쓰면 달라진다.

Draft는 새 룰로 덮어쓰고, 나머지 상태는 그대로 둔다. 막지는 않는다.

(Draft는 초안 상태다.) 바꿀 대상, 그대로 둘 대상, 막을지 말지가 다 정해졌다. 검수할 때도 이 세 개만 확인하면 된다.

AI가 추측한 기획을 AI가 구현하고, AI가 그 추측대로 잘 돌아가는지 검토하면, 셋 다 같은 답을 낸다. 그 보고만 읽으면 실제 요구와 어긋난 걸 모른다. 그래서 결과를 보기 전에 지시서에 빈칸이 없는지부터 본다. 검토 기준도 일을 맡기는 내가 먼저 적어 둔다.

7. 작게 맡기고, 확인할 조건을 같이 적는다

한 번에 여러 변경을 섞어 맡기면, 문제가 생겼을 때 어느 요구 때문인지 알기 어렵다. 그래서 범위를 작게 자르고 검수 조건을 같이 적는다.

화면 작업이라면 이런 식이다. (글을 위해 만든 예시)

기존 목록 화면에 상태 필터를 추가해 줘.

- 초안과 완료 상태를 선택할 수 있다.
- 처음에는 전체 항목을 보여 준다.
- 필터를 바꾸면 첫 페이지로 돌아간다.
- 결과가 없으면 “해당 상태의 항목이 없습니다”를 보여 준다.
- 기존 목록의 수정·삭제 동작은 유지한다.

상태 이름이나 기존 동작을 확인할 수 없으면 구현 전에 물어봐.
완료하면 바꾼 화면과 확인한 동작을 알려 줘.

이렇게 써 두면 완료 여부는 화면을 열어 하나씩 눌러 보면 안다. 처음에 전체가 보이나, 필터를 바꾸면 첫 페이지로 가나, 결과가 없을 때 문구가 나오나. 원하지 않은 동작이 나오면 그 작업 안에서 고치고, 또 나올 것 같은 실수면 매뉴얼에 한 줄 추가한다.

8. 탐색: Graphify 결과로는 어디부터 읽을지만 정한다

맡길 일이 정해지면 읽을 곳부터 찾는다. AI한테 탐색을 맡길 때는 질문을 좁게 던진다.

이 버튼 동작을 바꾸려면 어디부터 읽어야 해? 같은 동작을 쓰는 다른 화면은 어디야?

472개 중 39개만 나왔다

현재 구현을 기획 문서와 대조하던 작업이 있었다. 목록 조회와 비교 판정이 각각 어떤 값을 쓰는지 확인해야 했다. 기존 그래프를 열고, 동기화·비교·스냅샷 같은 단어로 조회했다.

결과는 472개 중 39개만 출력됐다. 출력량 제한에 걸린 거였다. 이걸 “호출하는 곳은 이게 전부”로 읽었으면 그대로 틀렸을 거다. 그래서 이 결과는 어디부터 읽을지 정하는 데만 쓰고, 나머지는 원본 코드를 직접 열어 대조했다.

열어 보니 상태값이 목록 응답에는 있는데 비교 판정 입력에는 없었다. 같은 기능 근처에 있는 값이라고 같은 경로로 흘러가는 건 아니었다. 문서에도 “목록 표시에는 있고, 비교 판정 입력에는 없다”라고 나눠 적었고, 끝까지 확인하지 못한 경로는 다음 작업으로 넘겼다.

이 일 이후로 Graphify는 이렇게 쓴다.

• 그래프는 지도일 뿐이다. 길이 진짜 이어져 있는지는 원본 코드로 확인한다.
• 그래프에 없다고 코드에도 없는 건 아니다.
• 그래프를 만든 뒤에 코드가 바뀌었을 수 있다. 가리킨 파일의 지금 내용을 다시 본다.
• 직접 추출한 관계와 추론한 관계를 구분해서 읽는다. 관계의 근거 표시

9. 검수: 루프를 이렇게 돌린다

구현을 맡겼으면 5장의 검수 루프를 돌린다. 돌리면서 몇 가지 정해 둔 게 있다.

• 리뷰어는 읽기만 한다. 코드는 건드리지 않고, 근거와 실패하는 상황만 적는다. 고치는 건 구현자가, 지적이 맞는지 직접 확인한 다음에 한다.
• 리뷰 대상은 고정한다. 리뷰 중에 구현자가 계속 고치면 리뷰어가 본 코드와 최종 코드가 달라진다. 수정했으면 이전 승인은 버리고 최종본을 다시 보게 한다.
• 보는 관점을 나눈다. 정확성과 구조를 따로 본다. 첫 라운드는 둘 다, 뒤 라운드는 수정 때문에 동작이 깨지지 않았는지만. 당장 고칠 것과 나중에 정리할 구조 개선도 따로 적는다.

언제 멈추고 나를 부를지

끝내는 기준도 적어 둔다. 필요한 검증이 통과했는지, 정한 범위의 결함이 다 처리됐는지. 남은 한계가 있으면 완료 기록에 같이 남긴다.

그리고 세 라운드를 돌고도 결함이나 이견이 남으면 자동 반복을 멈추고 나한테 넘기게 했다. 같은 쟁점이 되풀이되면 그보다 일찍 넘긴다. 그러면 나는 남은 지적과 근거를 보고 범위를 줄일지, 한 라운드 더 돌릴지 정한다.

AI가 쉬지 않고 일하는 것 자체는 별로 중요하지 않았다. 무슨 근거로 계속하고, 언제 끝내고, 어디서 사람을 부를지가 정해져 있어야 했다.

10. 마무리

정리하면 내가 하는 일은 이렇다. 맡기기 전에 기획의 빈칸을 메우고 작게 자른다. Graphify로 읽을 곳을 좁히고, 원본에서 확인한다. 구현과 리뷰를 나눠 맡기고, 뭘 확인해서 통과했는지 본다. 못 끝낸 건 인수인계 노트에 남긴다. 그리고 다음 작업을 시작하기 전에, 지난번에 데인 게 매뉴얼에 들어갔는지 확인한다.

규칙이 쌓이면 AI가 전보다 일을 잘하는 것처럼 보인다. 그런데 정확히는 이렇다. AI가 똑똑해지는 게 아니라, 매뉴얼이 쌓이는 것. 내 머릿속에만 있는 교훈은 다음 AI한테 전달되지 않는다. 적어 둬야 다음 세션이 읽는다. 이걸 돌리다 보니 어느 순간 이런 생각이 들었다.

나는 요즘 코드를 짜기보다 AI 여러 명한테 일 시키고 검수하는 팀장처럼 일한다. 그래서 요즘은 코드보다 md를, 그중에서도 그 보고가 뭘 확인했는지를 더 오래 읽는다.

부록

설치와 로그인이 끝났다면 터미널(명령을 글자로 입력하는 창)에서 프로젝트 폴더로 이동해 시작한다.

cd ~/my-project
claude

~/my-project는 실제 프로젝트 폴더로 바꾼다. 최근 대화를 이어가려면 같은 폴더에서 claude -c. 터미널 명령어

아래 명령은 터미널이 아니라 열린 Claude Code 입력창에 친다.

작업 중에 Esc로 멈추고 방향을 바꿀 수 있다. 대화가 길어지면 /context로 사용량을 보고 /compact로 요약한다. 새 일을 시작할 땐 /clear. 명령은 버전마다 조금씩 다르니 /help를 기준으로 본다. 명령어, 단축키

Graphify 시작과 조회

Graphify를 설치하고 스킬을 등록했다면, Claude Code 입력창에 /graphify .을 쳐서 프로젝트 그래프를 만든다. 만든 그래프는 프로젝트 폴더의 터미널에서 조회한다.

graphify query "관련 기능의 실제 이름" --budget 1500

검색어는 그래프에 있는 이름으로 바꾼다. --budget은 출력 토큰 예산이라 결과가 잘릴 수 있다. (8장의 472개 중 39개가 이거였다.) 두 대상 사이 경로는 graphify path, 대상 설명은 graphify explain으로 본다. Graphify 사용법

스킬과 플러그인

스킬은 반복 업무의 지침과 순서를 묶은 것이다. MCP는 외부 서비스의 자료와 기능을 연결하고, 훅은 정해진 시점에 동작을 실행한다. 플러그인은 스킬·훅·서브에이전트·MCP 서버 등을 한 번에 설치해 쓰도록 묶은 것이다. 확장 기능

이 구성에서 Graphify는 탐색 도구고, 루프 엔지니어링은 도구와 작업자·검토자를 어떤 순서와 조건으로 쓸지 정한 절차다. Superpowers처럼 개발 절차를 스킬로 묶어 둔 플러그인도 있다. /plugin에서 추가되는 기능과 설치 범위를 확인할 수 있다. 플러그인 관리