Vibe Coding에서 Agentic Development까지 | 주니어 개발자의 AI 개발 적응기

영석·2026년 3월 15일
Agentic DevelopmentClaudevibe coding

Agentic Development

목록 보기
1/1
post-thumbnail

들어가면서

Agentic Development를 회사와 개인프로젝트에서 적용 후 인사이트를 정리한 글입니다.

주니어 개발자로 근무한 지 어느덧 6개월이 되었습니다.
그동안 개발자에 대한 가치관, 개발방식에 대한 여러 인사이트를 배울 수 있어서 내적으로 많은 변화가 생겼음을 체감할 수 있었습니다.

특히 개발 패러다임에 큰 변화가 생겨서 이를 정리하는 시간을 가지려고 합니다.

26년도 부터 회사에서는 KPI 평가 항목에 Vibe-Coding 즉, Agent를 이용한 (Claude, Gemini) 개발 활용이 추가되었고 덕분에 Claude, Gemini를 개인돈을 들이지 않고 강제로(?) Vibe-Coding을 할 수 있게 되었습니다!!(감사합니다 ㅠㅠ)

다가올 미래를 위해, 현재까지 느낀점을 정리해보고자 합니다.

1. Vibe-Coding과 Agentic Development란 무엇인가?

Vibe-Coding

결과물을 생성하기 위해, 말하듯이 자연어로 개발하는 과정을 뜻합니다.
당장의 결과물을 생성해 내는데 중점이 맞춰져 있습니다.

Agentic Development

기존 인간 중심의 요구사항 파악 > 설계 > 구현 > 테스트 > 유지보수의 일련의 과정을, AI-Agent가 자율적으로 판단하고 실행하는 방식으로 함께 관리 및 개발하는 과정입니다.

2. 회사가 원하는 것은 Agentic Development

회사의 니즈는 생성(Vibe-Coding)뿐만 아니라, 계획, 설계, 테스트, 향후 유지보수 비용까지이다.
즉, 개발의 패러다임은 변화해도 기존 효율적인 SDLC를 유지해야한다.

실제로 회사에 이미 Agentic Development를 적용하여 개발중인 시니어 개발자분에게 여쭤보았고
새로운 인사이트를 얻을 수 있었다.

생산성의 폭발에 양면성

대부분의 SW 기업은 SaaS, 온프레미스 형태의 구독료 및 라이선스비용을 받는다.
이때 무시될 수 없는 비용은 유지보수 비용 이다. 이러한 환경에서는, 생산성 증가와 그에 따른 유지보수성 역시 함께 고려되어야 한다.

그렇기 때문에 인간이 Agent를 통제하고 도구로서 이용해야지, Agent가 인간을 도구로 이용하게 두면 안된다고 하셨다.
단기적으로는 기능이 돌아가니, 이상은 없지만 실제 사용환경에서 유지보수는 전혀 다른 이야기가 되기 때문이다.

즉 폭발하는 생산성을 뒷받침하는 유지보수 효율성 개선도 고민되어야 한다.

실무에는 책임의 영역이 존재한다

실무는 내가 개발한 내용에 대한 향후 관리를 넘어서 비즈니스 협업적으로 주어진 책임이 존재한다.
그렇기 때문에, 개발만 하고 멈추는 게 아닌, 향후 이어 개발할 사람과 이에 대해 충분히 설명하고 비즈니스 요구사항을 함께 해결해 나갈 수 있어야 한다.

이러한 특수성 때문에 단순히 AI를 활용한 폭발적인 생산성 향상에만 초점을 두는 것은 니즈에 어긋난다고 생각했다
그렇기 때문에 회사는 단순 Vibe-Coding을 사용하는 개발자 보다는 Agentic Development 개발자에 수요가 있다.

3. 프로젝트 Spec 문서에 시간을 투자하자

개인적으로는 Agentic Development에서 코드치는 시간보다 Spec 문서를 작성하는 시간이 더 많아져야한다고 생각한다. 물론 이러한 과정을 번거롭게 생각 할 수도 있다.

하지만 Trade-off 관점에서 보면, 프로젝트가 장기화 되거나, 다수와 협업을 할수록 실보다는 득이 압도적으로 크다

Vibe-Coding은 동일한 퀄리티를 보장하기 힘들다.

다수와 작업을 하게 될 경우, Agent가 작동하는 세션의 숫자가 많아질 수록 퀄리티가 천차만별일 것이다.
하지만 프로젝트 Spec 문서를 작성해 놓고 버전관리를 한다면, 세션이 달라도 Agent는 동일한 프로젝트 마크다운 파일을 읽고 작업을 시작 할 것이다.

물론 100% 동일한 퀄리티를 보장하긴 어렵다(이건 인간도 ㅎㅎ..)
하지만 Spec 마크다운 문서가 정확/명확하게 작성이 되어있는 경우라면 퀄리티를 비약적으로 향상시킬 수 있다.

결국은 설계, 개발, 테스팅 등 Agentic Development를 지향해야한다고 생각한다.

4. 프로젝트 spec .md 파일은 인간/AI 공용이다.

.md 파일을 한글로 작성하면, 영어로 작성했을때 보다 40~50% 정도 손해가 있는건 사실이다,
그럼에도 불구하고 개인적으로는 한글로, 정확히는 팀이 주로 사용하는 언어로 적는 것을 권장하고 있다.

AI뿐만 아니라 인간도 참조해야한다.

한글(팀 언어기반)을 이용해서 작성해야하는 가장 큰 이유중 하나이다.

이미 올바르게 프로젝트 spec이 작성 되었다면, 그 자체 하나로 좋은 문서가 될 수 있기 때문이다.
또한 문서가 항상 올바르게 작성이 된다는 보장이 없기 때문에 코드를 리팩토링하는 것처럼
.md 파일 또한 주기적으로 리팩토링해줘야한다, 이때 팀이 익숙한 언어로 적혔을 때 유리하다.

개발자도 개발 전 문서를 읽고 시작한다면,
Agent가 잘못된 방향으로 개발하는 것을 바로잡을 수 있다.

5. Context를 최대한 가볍게 유지해야한다.

Context : Agent가 사용자와 대화, 프롬프트, 파일, 도구 등을 참조할 수 있는 용량

작성된 Skills, 프로젝트 spec .md 파일들이 Context의 대부분을 점유 한다면, Agent의 작업 결과물의 퀄리티는 매우 떨어진다.
즉, CLAUDE.md, spec .md 파일을 적을때도 무작정 적는것이 아닌, 개발자가 예상가능한 범위에서 작성되어야 한다.

사이드 프로젝트 Spec .md 파일

 Side-Project/
  │
  ├── CLAUDE.md ( 200 줄 이하 )
  │   └── 진입점 & Context-Switcher
  │
  └── agent_docs/
      ├── architecture.md (필수)
      │   └── 프로젝트 전체적인 아키텍처, 3-Layer, MVC, Design Pattern, Plugin 정의
      │
      ├── conventions.md (필수)
      │   └── 코딩 규칙 & 패턴 (로깅, 메서드 등) & 주석 등
      │
      ├── database.md (필수)
      │   └── 도메인별 DB Table 스키마 작성
      │
      ├── Service.md (필수)
      │   └── 도메인, 서비스 구현 정보 등
      │
      └── etc...  (옵션) (확장 기능 및 새로운 rule)
          └── test.md, rule.md, decisions.md

CLAUDE.md

  • Agent는 개발시 CLAUDE.md 파일을 한번 읽는다.
  • CLAUDE.md 는 간단한 프로젝트 개요와 함께 추가 정보를 제공하고 어떤 문서를 사용할지 Agent에게 가이드를 하는 역할을 한다

CLAUDE.md 파일을 200줄 이하로 작성하는 것이 좋다는 후기들이 많다.
무엇보다도 CLAUDE.md 파일에 모든 .md 파일을 다 작성한다면, 필요 없는 Context까지 읽게 되어 효율이 떨어진다.

그렇기 때문에 CLAUDE.md는 최대한 가볍게 작성을 하되, Context Switcher 역할을 수행하도록 명확히 작성해야한다.

agent_docs/

  • CLAUDE.md에서 Context Switcher가 지정해주는 명세 파일을 모아두는 폴더
  • 자유 양식, 팀에서 필요한 섹션별로 정리하는게 좋아 보임

실제 작성된 CLAUDE.md, agent_docs/*.md 리뷰 결과

  • Claude Sonnet 4.5 (200K Context) 사용
  • 명세 파일 토큰 효율성 검사 요청했습니다.
파일줄 수예상 토큰
CLAUDE.md70줄~1,000-1,500
Architecture.md247줄~4,000-5,000
Database.md357줄~5,000-6,000
Service.md361줄~5,000-6,000
Conventions.md243줄~4,000-4,500
Decisions.md155줄~2,000-2,500
전체1,433줄~21,000-25,000
효율성 분석

200,000 토큰 중 ~25,000 토큰 = 12.5% (최악인 경우)

이 정도면 매우 효율적입니다:

✅ 한 번 읽으면 세션 내 캐싱 - Service.md를 다시 참조 시 캐싱된 데이터는 비용이 적음
✅ 선택적 읽기 가능 - 필요한 1-2개 파일만 읽으면 5,000-10,000 토큰
✅ 175,000 토큰 여유 - 코드 읽기/작성에 충분한 공간


결론

현재 문서 세트는 **전체 컨텍스트의 12.5%**로 매우 적절합니다.
실제 개발 시 코드 읽기/작성에 87.5%를 사용할 수 있어 이상적입니다.

CLAUDE.md에 모든것을 다 넣지 말자.

Agent는 작업시 필요한 .md 파일을 읽게된다, 이때 필요 없는 파일은 읽지 않는다 이렇게되면
Context를 절약 할 수 있게 되며, 그만큼 Agent는 일을 할 수 있는 공간이 확보되어 효율적이다.

물론 최악인 경우 (모든 명세가 필요할때)를 대비하여 미리 중복되거나, .md파일내 코드 블럭 등
불필요한 요소를 리팩터링하는 활동도 필요하다

개발자의 역할은 점점 코드 작성자에서
'명세를 설계하는 사람'으로 변화하고 있는 것 같습니다.

6. Agent는 마법사가 아니다

소위 말하는 딸깍(?)으로 개발되지 않는다. 내가 원하는 방향으로 개발을 진행하기 위해서는 많은 정보를 입력해야 한다. 코드 컨벤션, 개발 순서 및 아키텍처 구조, 참조 코드 등 여러가지 정보를 세밀하게 조절하여 프롬프트를 작성해야 더 나은 결과물이 생성된다.

심지어 명세를 잘 작성해놔도, Agent가 이전 context를 잊어버리던가, 할루시네이션으로 인한 문제도 존재한다. 이 때문에 인간이 결과물을 검증하는 단계가 꼭 필요하다.

Agent를 사용하는 개발자 본인도 프로젝트와 WorkFlow에 대한 높은 수준의 이해가 필요하다.

마무리하면서

AI를 이용한 개발은 이제 피한다고 해서 피해지는 게 아니라, 어떻게 잘 다룰 수 있는지를 고민하는 게
이 시대의 과제인 것 같습니다 ㅎㅎ..

특히 기존 개발자의 역할에서 새로운 역할로 변경하는 과도기에 있는 것 같아서 흥미롭네요
좋은 환경에서 배울 수 있음에 감사하면서 대체당하지 않도록 노력해보겠습니다!

profile
영석
느리게 갱신되는 개발실력 - >_0

1개의 댓글

comment-user-thumbnail
chanhoan
2026년 3월 19일

인간이 병목이다. - 이영석

답글 달기