AI 코딩 에이전트, 좀 더 믿고 맡길 수 없을까? — 만들어 본 워크플로 공개합니다 (MIT, alpha)

AI한테 코딩을 시키다 보면 다들 한 번쯤 겪죠. 시켜놓으면 절차는 건너뛰고 코드부터 쓰고, 실행도 안 해보고 "다 됐어요" 하고, 정리한답시고 켜둔 프로세스를 몽땅 죽여버리기도 하고요. 그래서 "AI를 좀 더 꼼꼼한 개발자처럼 굴러가게 할 수 없을까?" 하고 만들어 본 게 이 Evidence-First Agent Workflow입니다. 오픈소스(MIT)예요.

---

[사진 1] 공개 TaskFlow 샘플 화면 — 이 워크플로로 GPT-5.4 mini가 만든 결과예요.

---

어떤 생각으로 만들었나

거창한 도구라기보다, "일하는 방식(습관)"을 AI한테 심어주는 규칙 묶음이에요. 핵심 생각은 몇 가지로 단순합니다.

• 먼저 읽고, 그다음 손대기. 아무 파일이나 건드리기 전에 프로젝트 상태부터 파악하게 합니다.
• 말이 아니라 증거로. "됐어요"가 아니라 "이 명령을 돌렸고 결과가 이렇다"를 남기게 합니다.
• 정직이 완료보다 먼저. 대충 그럴듯하게 마무리하는 것보다, 모르면 멈추고 물어보는 걸 더 쳐줍니다.
• 기억을 남긴다. 작업 기록·현재 상태를 문서로 남겨서, 세션이 끊겨도 맥락을 잃지 않게 합니다.

이 습관을 새지 않게 잡아주는 자동 장치(커밋 검사 같은 것)도 들어 있지만, 그건 어디까지나 거들어주는 역할이고 진짜 핵심은 이 "일하는 방식" 자체예요.

좋은 점

1. 장기 프로젝트에 유리해요. 세션이 바뀌고 시간이 지나도 맥락을 안 잃어서, "어제 뭐 하던 중이었지"를 매번 다시 설명 안 해도 됩니다.
2. 작고 저렴한 LLM에서도 잘 돌아가요. 프로세스가 판단을 대신 잡아줘서, 엄청 똑똑한 모델이 아니어도 쓸 만한 결과가 나옵니다. 비용도 아끼고요.
3. 자가 진화해요. 쓸수록 기록이 쌓여서 프로젝트 나름의 규칙이 스스로 또렷해집니다.
4. "완료"를 믿을 수 있어요. 안 해놓고 다 됐다고 하는 거짓 완료가 막혀서, 매번 결과를 뜯어보는 수고가 줄어요.
5. 특정 도구·스택에 안 묶여요. Codex·Claude·Cline·Roo 같은 에이전트든, 기술 스택이든 자유롭게 갈아끼울 수 있습니다.
6. 리뷰하고 넘겨받기가 쉬워요. 모든 변경에 "왜, 무엇을, 어떻게 확인했는지"가 딸려 옵니다.
7. 누가 돌려도 비슷한 품질이 나와요. 사람이든 모델이든 같은 절차를 밟으니 결과 일관성이 유지됩니다.
8. 사고가 나도 복구돼요. 순서가 꼬여도 회복 절차가 있어서 작업이 통째로 날아가지 않습니다.

단점 (솔직하게)

좋은 점만 있으면 거짓말이겠죠. 이건 확실히 느리고 손이 가는 방식입니다.

1. 느리고 무거워요. 절차를 다 밟느라 시간이 걸립니다. ChatGPT 5.4 Mini 기준으로 사용자 관리 화면 하나에 약 20분, TaskFlow 샘플은 약 18분 걸렸어요. 빠른 프로토타이핑에는 안 맞습니다.
2. 토큰을 꽤 씁니다. 기능 하나에 약 45K, 큰 화면(TaskFlow)은 258K 창 중 143K 정도 썼어요. 비용·컨텍스트 부담이 있습니다.
3. 초기 셋업이 좀 번거로워요. 훅 설치, 폴더 구조, 상태 문서 같은 걸 얹어야 해서 "깔고 끝"은 아닙니다.
4. 새 스택을 만들어 적용하는 것도 일이에요. 검증 명령 같은 걸 직접 채워야 하고 자동은 아니라, 처음엔 러닝커브가 있습니다.
5. 사람도 개념을 한 번은 익혀야 해요. 규칙과 용어를 대충이라도 이해해야 제대로 굴러갑니다.
6. 아직 alpha예요. 특히 공개 샘플 스택은 검증이 적어서 버그가 있을 수 있습니다.

공개본과 원본 이야기

솔직하게 밝히면, 이 워크플로의 핵심은 실제 사내 프로젝트(엔터프라이즈 웹 프론트엔드 스택)에서 써 오던 것입니다. 그런데 그 스택은 UI 프레임워크랑 통신 레이어가 상용 라이선스가 필요해서, 공개 테스트용으로는 쓸 수가 없더라고요.

그래서 공개본에는 라이선스가 필요 없는 React + ASP.NET Core 샘플을 대신 넣었습니다. "회사에서 쓰던 건데 이걸 어떻게 공개하냐"는 궁금증이 있을 텐데, 대표이사님께 허락을 받고 사내·독점 내용은 전부 걷어낸 공개본을 따로 만든 거예요. 정리하면, 핵심 방식은 실무에서 검증됐고, 공개 샘플 스택은 새로 만든 것입니다.

테스트한 모델

• 공개본(샘플 스택): Claude Haiku, GPT-5.4 mini 등
• 원본(사내 버전): Claude Opus 4.8, Sonnet 5, Haiku, GLM 5.2, Qwen3.6 35B-A3B

Claude를 뺀 나머지는 전부 제 개인 예산으로 돌린 거라, Qwen3.6 27B는 결국 예산이 부족해서 중간에 멈췄어요. 저는 그냥 가난한 아기 아빠라… 애기 기저귀 값 버는 것도 벅차거든요. 😅

---

[사진 2] 절차를 건너뛴 변경을 자동 검사가 막아주는 모습이에요.

---

써 보려면 — 뭐가 필요하고, 어떻게 하나

필요한 프로그램은 스택에 따라 조금 다릅니다.

• Git — 필수예요. (버전 관리 + 자동 검사가 여기 붙습니다.)
• Python — 킷의 검사 도구를 돌리는 데 씁니다.
• Node.js — React 쪽(프론트엔드)을 쓸 때.
• .NET SDK — ASP.NET Core 쪽(백엔드)을 쓸 때.

쓰는 순서는 이렇게 단순해요.

1. GitHub에서 저장소를 받습니다.
2. 설치 스크립트로 내 프로젝트에 킷을 얹습니다. (install-kit — Windows·macOS·Linux용 각각 있음)
3. 쓰던 코딩 에이전트(Codex·Claude 등)를 열고, 시작 프롬프트를 줍니다.
4. 나머지는 워크플로가 알아서 안내합니다 — 상태 파악 → 계획 → 작업 → 검증 → 기록 순으로요.

그리고 공개 샘플은 React와 ASP.NET Core를 꼭 같이 쓸 필요는 없어요. 프론트만(React) 쓰거나 백엔드만(ASP.NET Core) 써도 됩니다. 필요한 프로그램도 그만큼만 있으면 되고요.

부탁이 있어요

이게 아직 alpha라, 여러분 도움이 정말 큰 힘이 됩니다.

• 스택을 만들어 보셨다면 공유해 주세요. 지금 채워진 공개 예시는 React + ASP.NET Core 하나뿐이에요. FastAPI, Express, 정적 사이트 등 더 늘려갈 계획인데, 여러분이 만든 스택을 이슈나 PR로 나눠 주시면 다른 분들에게도 큰 도움이 됩니다. 같은 스택이 여러 개 겹쳐도 대환영이에요 — 겹치는 것들을 모으면 서로 대조해서 정합성을 검증할 수 있고, 지식 기반도 그만큼 더 단단해집니다.
• AI 리소스가 남는 분이 계시면 테스트 환경을 부탁드려요. 앞서 말했듯 제 주머니 사정상 여러 모델을 다 돌려보긴 어렵거든요. 다른 모델·에이전트로 돌려볼 수 있는 환경이나 컴퓨트를 나눠 주실 수 있다면 정말 감사하겠습니다. 다른 환경에서의 결과·리포트도 언제든 환영해요.

가장 반가운 건 "내 스택/에이전트에선 이게 안 됐다"는 실패 사례와 설계에 대한 쓴소리입니다.

링크

• 저장소: https://github.com/SonTaeksu/evidence-first-agent-workflow
• 시작점: Code-Agent-Kit/ko(또는 en)에 있는 한 페이지 QUICKSTART