AI 에이전트 개발, 가이드 문서가 먼저다

요즘 개발 방식이 빠르게 바뀌고 있습니다.
이제는 개발자가 모든 코드를 직접 작성하는 시대를 넘어, AI 에이전트와 함께 개발하는 시대가 되었습니다.

하지만 AI에게 그냥 이렇게 말하면 어떻게 될까요?

MES 만들어줘.
화면 예쁘게 만들어줘.
오류 안 나게 해줘.

결과는 운에 가깝습니다.
잘 될 때도 있지만, 기존 구조를 망가뜨리거나 필요 없는 코드를 만들거나, 화면과 DB 기준이 뒤섞일 수 있습니다.

그래서 필요한 것이 바로 가이드 문서입니다.

---

가이드 문서란?

가이드 문서는 AI 에이전트에게 주는 개발 기준서입니다.

사람 개발자에게도 개발 표준, 화면 기준, DB 설계서, 코딩 규칙이 필요하듯이 AI 에이전트에게도 기준이 필요합니다.

예를 들어 eMES Lite 프로젝트라면 다음과 같은 문서를 프로젝트 루트에 둡니다.

AGENTS.md
PROJECT_RULES.md
CODING_GUIDE.md
DESIGN_GUIDE.md
SCREEN_RULES.md
DB_SCHEMA.md
API_SPEC.md
BUILD_GUIDE.md
VB6_MIGRATION_GUIDE.md
MENU_AUTH_GUIDE.md
LOG_ERROR_GUIDE.md
TEST_SCENARIO.md
ROADMAP.md

이 문서들은 AI에게 이렇게 말하는 역할을 합니다.

이 프로젝트는 C# WinForm 기준이다.
DB는 MariaDB를 사용한다.
기존 VB6.0 소스를 참고한다.
디자인은 Newman 스타일로 한다.
오류가 발생해도 프로그램은 종료되면 안 된다.
향후 MAUI 앱으로 확장할 수 있게 만든다.

---

AGENTS.md가 핵심이다

특히 중요한 파일은 AGENTS.md입니다.

AGENTS.md는 AI 에이전트가 가장 먼저 읽어야 할 최상위 규칙 문서입니다.

여기에는 다음 내용이 들어갑니다.

- 어떤 문서를 먼저 읽을 것인가
- 어떤 기술을 사용할 것인가
- 어떤 파일은 수정하면 안 되는가
- 기존 구조를 어떻게 유지할 것인가
- 오류 처리는 어떻게 할 것인가
- 작업 완료 후 무엇을 보고할 것인가

즉, AGENTS.md는 AI 에이전트에게 주는 작업 헌법입니다.

---

그냥 AI에게 맡기면 위험하다

AI는 빠릅니다.
하지만 기준이 없으면 너무 자유롭게 움직입니다.

기준 없는 AI 개발은 이런 문제가 생길 수 있습니다.

기존 구조 무시
불필요한 전체 재작성
DB 정보 하드코딩
화면 디자인 불일치
권한 처리 누락
오류 로그 누락
빌드 오류 발생

개발자는 빨리 가고 싶지만, 실무 시스템은 안정성이 더 중요합니다.

그래서 AI에게 코딩을 맡기기 전에 먼저 기준을 줘야 합니다.

---

가이드 문서가 있으면 달라진다

가이드 문서가 있으면 AI의 답변과 작업 품질이 달라집니다.

예전 요청:

품목관리 화면 만들어줘.

가이드 문서 기반 요청:

AGENTS.md와 CODING_GUIDE.md, SCREEN_RULES.md, DB_SCHEMA.md 기준으로
C# WinForm 품목관리 화면을 만들어줘.
DB는 MariaDB이고, Newman 스타일 디자인을 적용해줘.
오류는 LOG_ERROR_GUIDE.md 기준으로 처리해줘.

이렇게 요청하면 AI는 단순히 코드를 만드는 것이 아니라, 프로젝트 기준에 맞춰 작업합니다.

---

AI 개발의 핵심은 질문이 아니라 기준이다

Vibe Coding, Codex, Claude Code, Cursor, Windsurf 같은 도구를 잘 쓰려면 질문만 잘해서는 부족합니다.

진짜 중요한 것은 기준을 먼저 만드는 것입니다.

가이드 문서는 AI에게 다음을 알려줍니다.

무엇을 만들지
어떻게 만들지
무엇을 지키지
무엇을 하지 말아야 할지
어떻게 테스트할지
앞으로 어디까지 확장할지

---

정리

AI 에이전트 개발은 빠릅니다.
하지만 기준 없는 빠름은 위험합니다.

개발을 AI에게 맡기고 싶다면 먼저 가이드 문서를 만들어야 합니다.

좋은 개발자에게 개발 표준이 필요하듯,
좋은 AI 에이전트에게도 가이드 문서가 필요하다.

eMES Lite 같은 실무형 MES 프로젝트라면 더더욱 그렇습니다.

AI에게 무작정 “만들어줘”라고 말하기보다,
먼저 이렇게 말하는 것이 좋습니다.

AGENTS.md를 먼저 읽고, 프로젝트 가이드 문서 기준으로 작업해줘.

이 한 문장이 AI 개발의 품질을 바꿉니다.