개인 OSS 프로젝트 SpecGuard를 진행하며 겪은 AI 코딩 에이전트와의 작은 오해

개인 OSS 프로젝트 SpecGuard를 진행하며 겪은 AI 코딩 에이전트와의 작은 오해

개인적으로 진행 중인 OSS 프로젝트 SpecGuard를 진행하며 오늘 있었던 일에 대해 작성하려 합니다. SpecGuard는 제가 개인적으로 만들고 있는 오픈소스 프로젝트입니다.

github : https://github.com/KoreaNirsa/spec-guard

프로젝트를 진행하면서 GitHub 이슈를 정리하고, 기능 우선순위를 판단하고, 새로운 아이디어가 프로젝트 방향과 맞는지 검토하는 과정에서 에이전트 AI를 함께 사용하고 있습니다.

오늘도 평소처럼 AI에게 현재 열린 이슈를 기준으로 우선순위를 정하고, 특정 기능 아이디어가 프로젝트에 적절한지 검토해 달라고 요청했습니다.

그런데 AI의 답변이 제가 기대한 방향과 조금 달랐습니다.

처음에는 “왜 이런 식으로 답변했을까?”라고 생각했습니다.
하지만 다시 제가 작성한 프롬프트를 읽어보니, 문제는 AI가 아니라 제가 던진 질문의 범위가 충분히 명확하지 않았다는 점이었습니다.

이번 글에서는 그 사례를 바탕으로, 에이전트 AI를 사용할 때 왜 프롬프트가 중요한지 정리해보려 합니다

.

오늘 작성했던 프롬프트

제가 AI에게 작성한 요청은 다음과 같았습니다.

현재 이슈 기준으로 우선순위 결정해.

또한 현재 스펙가드에 자바 포맷팅을 검사하는 기능은 어떤지 검토해봐.
현재 프로젝트의 의도와 달라져 과한지.

 

제가 원했던 것은 단순했습니다. 현재 SpecGuard에는 Java 포맷팅을 검사하는 기능이 없었으며 저는 이미 그 사실을 알고 있었습니다.

제가 궁금했던 것은 “현재 코드에 이 기능이 있는지”가 아니었고, 제가 알고 싶었던 것은 다음과 같은 설계적 판단이었습니다.

SpecGuard에 Java 포맷팅 검사 기능을 추가하는 아이디어가 괜찮은가?

이 기능이 프로젝트 목적과 맞는가?

혹시 오버 엔지니어링이 되는가?

기능이 많아지면서 프로젝트의 목적성이 흐려질 가능성은 없는가?

만약 넣는다면 core gate로 넣는 것이 맞는가?

아니면 PR Review 단계의 보조 피드백 정도로 넣는 것이 맞는가?

 

즉, 저는 기능 구현을 요청한 것도 아니었고, 현재 코드에 해당 기능이 있는지 확인해 달라고 요청한 것도 아니었습니다.

제가 원했던 것은 기능 도입에 대한 제품적, 설계적, 구조적 의견이었습니다.

 

AI가 실제로 한 일

AI는 제 요청을 받고 현재 프로젝트에 Java 포맷팅 검사 기능이 있는지 먼저 확인했습니다.

예를 들어 google-java-format, checkstyle, spotless, pmd 같은 Java 포맷팅 검사 도구나 관련 코드가 있는지 검색했습니다. 그리고 현재 레포지토리에는 Java 포맷팅 검사 기능이 없다고 정리했습니다.

이후 SpecGuard의 목적을 기준으로 Java 포맷팅 검사를 core gate로 넣는 것은 과할 수 있다고 판단했습니다.
SpecGuard의 중심은 코드 스타일 검사가 아니라, 스펙과 구현 사이의 불일치를 줄이는 데 있기 때문이라는 식의 답변이었습니다.

실제로 AI로부터 답변받은 내용

AI의 결론 자체가 완전히 틀렸다고 보기는 어렵습니다. Java 포맷팅 검사를 core gate로 넣는 것이 과할 수 있다는 의견은 충분히 검토할 만한 의견입니다.

하지만 제가 기대했던 답변과는 달랐습니다.

제가 원한 것은 “현재 기능이 있는지 확인해줘”가 아니었습니다.
또한 “core gate로 넣는 것이 맞는지 아닌지 하나의 결론만 내려줘”도 아니었습니다.

제가 원했던 답변은 여러 선택지를 놓고 비교하는 것이었습니다.

1. 아예 추가하지 않는 경우
2. core gate로 추가하는 경우
3. PR Review 보조 피드백으로 추가하는 경우
4. 옵션 기능으로 추가하는 경우
5. 외부 도구 연동 형태로만 제공하는 경우

 

그리고 각 선택지가 SpecGuard의 목적과 얼마나 잘 맞는지, 어떤 장단점이 있는지 듣고 싶었습니다.

 

문제는 “검토”라는 단어가 너무 넓다는 점입니다

이번 일을 통해 다시 느낀 점은 이것입니다.

“검토해줘”라는 말은 너무 넓습니다.

 

사람과 대화할 때는 “이 기능 어떤지 검토해봐”라고 말해도 어느 정도 의도가 전달될 수 있습니다. 하지만 에이전트 AI에게는 이 표현이 여러 방식으로 해석될 수 있습니다.

사용자의 의도	AI가 해석할 수 있는 작업
이 기능 아이디어가 프로젝트 방향과 맞는지 의견을 듣고 싶음	현재 코드에 해당 기능이 있는지 검색
기능을 도입하면 오버 엔지니어링인지 판단하고 싶음	현재 구현 여부와 문서 기준으로 적절성 판단
core gate와 PR Review 중 어디에 넣을지 비교하고 싶음	core gate로 넣는 것이 과한지 단일 결론 제시
여러 선택지의 장단점을 듣고 싶음	가장 안전한 하나의 방향만 제안
구현하지 말고 설계 의견만 받고 싶음	구현 여부 또는 현재 구현 상태 중심으로 검토

즉, “검토”라는 표현 안에는 여러 종류의 작업이 섞여 있습니다.

현재 상태 확인
도입 필요성 판단
설계 방향 검토
구현 위치 검토
기능 범위 검토
대안 비교
리스크 분석

 

제가 원했던 것은 이 중에서 도입 필요성 판단, 설계 방향 검토, 대안 비교, 리스크 분석에 가까웠습니다.

하지만 AI는 먼저 현재 상태 확인으로 들어갔습니다.

 

제가 원했던 검토와 AI가 수행한 검토의 차이

이번 상황을 도식화하면 다음과 같습니다.

[제가 원했던 검토]
Java 포맷팅 검사 기능을 추가하는 아이디어가
SpecGuard의 목적과 맞는지 의견을 듣고 싶었습니다.
          │
          ▼
[구체적으로 궁금했던 것]
- 프로젝트 목적과 충돌하는가?
- 오버 엔지니어링인가?
- 기능이 많아져 목적성을 잃게 되는가?
- core gate가 맞는가?
- PR Review 보조 기능이 더 맞는가?
- 옵션 기능으로 두는 것이 나은가?
          │
          ▼
[AI가 수행한 검토]
- 현재 코드에 Java 포맷팅 검사 기능이 있는지 검색
- 관련 도구 설정이 있는지 확인
- core gate로 넣는 것은 과하다고 판단
          │
          ▼
[결과]
제가 원했던 다방면의 설계 검토가 아니라,
현재 구현 여부 확인과 제한적인 방향성 판단에 가까운 답변이 나왔습니다.

 

AI가 완전히 엉뚱한 일을 한 것은 아닙니다.
제가 작성한 문장에는 “현재 스펙가드에 자바 포맷팅을 검사하는 기능은 어떤지 검토해봐”라는 표현이 있었습니다.

AI 입장에서는 이 문장을 다음처럼 이해할 수 있습니다.

현재 SpecGuard에 Java 포맷팅 검사 기능이 있는지 확인합니다.
그 기능이 프로젝트 목적과 맞는지 판단합니다.

 

하지만 제 실제 의도는 달랐습니다.

현재 기능이 없다는 것은 알고 있습니다.
그 기능을 추가하는 아이디어 자체가 프로젝트 방향과 맞는지 의견을 듣고 싶습니다.

 

이 작은 차이가 결과의 차이를 만들었습니다.

---

“존재 여부 확인”과 “도입 타당성 검토”는 다릅니다

이번 사례에서 가장 중요한 구분은 이것입니다.

존재 여부 확인과 도입 타당성 검토는 다릅니다.

 

두 작업은 비슷해 보이지만 완전히 다른 질문입니다.

구분	질문의 의미	기대하는 답변
존재 여부 확인	현재 프로젝트에 이 기능이 있는가?	관련 코드, 설정, 도구 존재 여부
도입 타당성 검토	이 기능을 프로젝트에 넣는 것이 적절한가?	목적 적합성, 장단점, 리스크, 대안
설계 위치 검토	넣는다면 어디에 넣는 것이 맞는가?	core gate, PR Review, 옵션 기능 등 비교
제품 방향성 검토	이 기능이 프로젝트 정체성을 흐리는가?	프로젝트 범위와 목적성 관점의 판단
구현 검토	실제로 어떻게 만들 수 있는가?	구현 방식, 테스트, 구조 변경

제가 원했던 것은 존재 여부 확인이 아니었으며 제가 원했던 것은 도입 타당성 검토와 설계 위치 검토였습니다.

하지만 프롬프트에는 이 차이가 충분히 드러나지 않았습니다.

개인 OSS 프로젝트를 만들다 보면 기능 아이디어가 계속 생깁니다.

이것도 넣으면 좋지 않을까?
저것도 지원하면 좋지 않을까?
이 기능까지 있으면 더 완성도 있어 보이지 않을까?

 

하지만 모든 좋은 기능이 현재 프로젝트에 좋은 기능은 아닙니다.

• 어떤 기능은 유용하지만 프로젝트의 핵심 목적과는 맞지 않을 수 있습니다.
• 어떤 기능은 사용자에게 도움이 되지만 유지보수 비용을 크게 늘릴 수 있습니다.
• 어떤 기능은 당장 보기에는 좋아 보여도 프로젝트의 정체성을 흐릴 수 있습니다.

Java 포맷팅 검사 기능도 그런 유형의 아이디어였습니다.

기능 자체는 나쁘지 않습니다. 하지만 SpecGuard에 넣었을 때 좋은지는 별개의 문제입니다.

이때 필요한 것은 단순한 코드 검색이 아니라, 프로젝트 방향성에 대한 검토입니다.

이 기능이 정말 SpecGuard다운 기능인가?
이 기능이 핵심 문제 해결에 기여하는가?
이 기능이 들어가면 프로젝트 범위가 과도하게 넓어지는가?
이 기능을 넣는다면 어느 레벨에 두어야 하는가?

 

저는 AI에게 이런 질문에 대한 의견을 듣고 싶었습니다.

---

 

프롬프트에서 질문의 레이어를 명확히 해야 합니다

이번 일을 통해 배운 것은 단순히 “프롬프트를 자세히 써야 한다”가 아닙니다.

더 정확히는 다음과 같습니다.

AI에게는 질문의 레이어를 명확히 알려줘야 합니다.

 

개발 작업에서 질문은 여러 레이어로 나뉩니다.

[현재 상태 확인]
현재 코드에 이 기능이 있는가?

[아이디어 검토]
이 기능을 넣는 것이 좋은가?

[설계 검토]
넣는다면 어디에 넣는 것이 맞는가?

[구현 검토]
어떻게 구현하는 것이 좋은가?

[실행 요청]
실제로 구현해달라.

 

이번에 제가 원했던 것은 두 번째와 세 번째였습니다.

[아이디어 검토]
이 기능을 넣는 것이 좋은가?

[설계 검토]
넣는다면 어디에 넣는 것이 맞는가?

 

하지만 프롬프트에는 그 구분이 명확하지 않았습니다.
그 결과 AI는 첫 번째인 현재 상태 확인부터 수행했습니다.

---

더 나은 프롬프트는 어떻게 작성할 수 있었을까요?

이번 상황에서 제가 더 정확히 작성했다면 다음과 같았을 것입니다.

현재 열린 이슈 기준으로 우선순위를 정해주십시오.

그리고 SpecGuard에 Java 포맷팅 검사 기능을 추가하는 아이디어에 대해
프로젝트 방향성 관점에서 의견을 듣고 싶습니다.

중요한 점은, 현재 코드에 해당 기능이 있는지 확인하는 것이 아닙니다.
현재 이 기능이 없다는 것은 알고 있습니다.

제가 알고 싶은 것은 다음입니다.

1. Java 포맷팅 검사가 SpecGuard의 핵심 목적과 맞는지
2. 이 기능을 추가하면 프로젝트 범위가 과도하게 넓어지는지
3. 오버 엔지니어링이 될 가능성이 있는지
4. 기능이 많아지면서 프로젝트의 목적성이 흐려질 위험이 있는지
5. 만약 추가한다면 core gate로 넣는 것이 맞는지
6. 아니면 PR Review 단계의 보조 피드백으로 넣는 것이 맞는지
7. 옵션 기능으로 제공하는 방식은 어떤지
8. 아예 외부 포맷팅 도구 사용을 권장하는 편이 나은지

코드는 수정하지 말고, 설계적 의견과 장단점 비교를 중심으로 답변해주십시오.

답변은 다음 형식으로 정리해주십시오.

1. 결론
2. 프로젝트 목적과의 적합성
3. core gate로 넣는 경우의 장단점
4. PR Review에 넣는 경우의 장단점
5. 옵션 기능으로 제공하는 경우의 장단점
6. 추가하지 않는 경우의 장단점
7. 최종 추천 방향

 

이렇게 작성했다면 AI가 현재 코드에 기능이 있는지 검색하는 데 시간을 쓰기보다, 제가 원했던 방향성 검토에 더 집중했을 가능성이 높습니다.

짧게 작성한다면 이렇게 작성할 수 있을 것 같습니다. 짧게 작성해야 한다면 다음 정도로도 충분히 의도를 줄일 수 있습니다.

현재 열린 이슈 기준으로 우선순위를 정해주십시오.

그리고 SpecGuard에 Java 포맷팅 검사 기능을 추가하는 아이디어가
프로젝트 목적에 맞는지 설계 관점에서 검토해주십시오.

현재 코드에 해당 기능이 있는지 확인하려는 것은 아닙니다.
해당 기능이 없다는 것은 알고 있습니다.

제가 궁금한 것은 이 기능이 오버 엔지니어링인지,
프로젝트의 목적성을 흐릴 위험이 있는지,
넣는다면 core gate가 맞는지 PR Review 보조 기능이 맞는지입니다.

코드는 수정하지 말고 의견만 정리해주십시오.

 

여기서 핵심 문장은 다음입니다.

현재 코드에 해당 기능이 있는지 확인하려는 것은 아닙니다.
해당 기능이 없다는 것은 알고 있습니다.

 

이 문장 하나만 있었어도 AI의 작업 방향은 달라졌을 수 있습니다.

 

“하지 않아도 되는 일”을 알려주는 것도 중요합니다

에이전트 AI에게는 해야 할 일뿐만 아니라, 하지 않아도 되는 일도 알려주는 것이 좋습니다.

이번 사례에서는 다음과 같은 문장이 필요했습니다.

현재 코드에 해당 기능이 있는지 검색하지 않아도 됩니다.

 

구현하지 않아도 됩니다.

 

코드 변경은 하지 말고, 설계적 의견만 주세요.

 

core gate로 넣을지 여부를 단정하지 말고,
PR Review, 옵션 기능, 외부 도구 연동 등 여러 선택지를 비교해주세요.

 

사람에게는 이런 말을 굳이 하지 않아도 될 수 있습니다.
하지만 AI에게는 이런 제약이 작업 범위를 명확히 하는 데 큰 도움이 됩니다.

좋은 프롬프트는 “할 일”만 적는 것이 아닙니다.

할 일
하지 않아도 되는 일
하지 말아야 할 일
비교해야 할 선택지
답변 형식

 

이 다섯 가지를 함께 정리하면 결과가 훨씬 안정적입니다.

---

 

에이전트 AI와 협업할 때 필요한 프롬프트 구조

이번 사례를 바탕으로, 설계 의견을 듣고 싶을 때 사용할 수 있는 프롬프트 구조를 정리하면 다음과 같습니다.

목표
- [기능 아이디어]가 프로젝트에 적절한지 의견을 듣고 싶습니다.

전제
- 현재 해당 기능이 없다는 것은 알고 있습니다.
- 구현을 요청하는 것이 아닙니다.
- 코드 검색보다 설계적 판단이 필요합니다.

검토 관점
1. 프로젝트 목적과 맞는지
2. 오버 엔지니어링 가능성이 있는지
3. 기능 범위가 과도하게 넓어지는지
4. 유지보수 비용이 커지는지
5. 사용자에게 실제 가치가 있는지

비교할 선택지
1. 추가하지 않음
2. core gate로 추가
3. PR Review 보조 피드백으로 추가
4. 옵션 기능으로 추가
5. 외부 도구 연동 또는 문서 안내로 처리

답변 형식
1. 결론
2. 선택지별 장단점
3. 추천 방향
4. 추천하지 않는 방향과 이유
5. 나중에 다시 검토할 조건

 

이런 식으로 작성하면 AI가 “현재 코드에 있는지 확인해야 하나?” 또는 “바로 구현해야 하나?” 같은 방향으로 빠질 가능성이 줄어듭니다.

---

이번 사례에서 얻은 교훈

이번 일을 통해 느낀 점은 다음과 같습니다.

AI에게 “검토해줘”라고 말하면 AI는 자신이 생각하는 검토를 수행합니다.

 

그 검토가 제가 원하는 검토와 같을 수도 있지만, 다를 수도 있습니다.

제가 원했던 것은 다음이었습니다.

1. 기능 아이디어의 도입 타당성 검토
2. 프로젝트 목적과의 적합성 판단
3. core gate와 PR Review의 비교
4. 오버 엔지니어링 가능성 검토
5. 기능 범위 확장에 따른 리스크 분석

 

하지만 AI가 수행한 것은 다음에 가까웠습니다.

1. 현재 코드에 해당 기능이 있는지 확인
2. 관련 포맷팅 도구 존재 여부 검색
3. core gate로 넣는 것은 과할 수 있다는 단일 방향 제안

 

둘 다 “검토”라는 단어 안에 들어갈 수 있기 때문에 더더욱 프롬프트가 중요합니다.

---

결론

오늘 SpecGuard를 진행하면서 겪은 일은 큰 문제는 아니었습니다.
하지만 에이전트 AI와 협업할 때 프롬프트를 어떻게 작성해야 하는지 다시 생각하게 만든 사례였습니다.

저는 Java 포맷팅 검사 기능을 구현해 달라고 한 것이 아니었습니다.
또한 현재 프로젝트에 해당 기능이 있는지 확인해 달라고 한 것도 아니었습니다.

제가 원했던 것은 이 기능 아이디어가 SpecGuard의 목적과 맞는지, 추가한다면 core gate가 맞는지 PR Review 보조 기능이 맞는지, 혹은 아예 넣지 않는 편이 나은지에 대한 다방면의 의견이었습니다.

하지만 제가 작성한 프롬프트에는 매우 짧았으며, 대충 적었고, 그 의도가 충분히 명확하지 않았습니다.

그 결과 AI는 현재 코드에 해당 기능이 있는지 먼저 확인했고, core gate로 넣는 것은 과하다는 방향으로 답변했습니다.

AI가 이상한 일을 한 것은 아닙니다.
제가 원하는 검토의 종류를 충분히 구체적으로 설명하지 않은 것이 문제였습니다.

에이전트 AI는 강력합니다.
코드를 읽고, 이슈를 확인하고, 문서를 분석하고, 설계 의견도 줄 수 있습니다.

하지만 강력한 도구일수록 지시가 중요합니다.

특히 “검토해줘”라는 표현을 사용할 때는 더 조심해야 합니다.

현재 상태를 확인해 달라는 것인지
아이디어의 타당성을 검토해 달라는 것인지
구현 방식을 비교해 달라는 것인지
실제로 구현해 달라는 것인지
코드는 수정하지 말라는 것인지
여러 선택지를 비교해 달라는 것인지

 

이 차이를 명확히 해야 합니다.

좋은 프롬프트는 단순히 긴 문장이 아닙니다.
좋은 프롬프트는 AI가 엉뚱한 방향으로 성실하게 움직이지 않도록 작업 범위를 정리한 문장입니다.

결국 에이전트 AI 시대의 개발자에게 필요한 역량은 코드 작성 능력만이 아닙니다.

질문을 정확히 정의하는 능력
검토 범위를 명확히 하는 능력
비교할 선택지를 제시하는 능력
하지 않아도 되는 일을 제외하는 능력
원하는 답변 형식을 지정하는 능력

 

이런 능력들이 점점 더 중요해지고 있다고 생각합니다.

AI는 의도를 알아서 읽지 않으며, AI는 프롬프트를 기준으로 작업합니다.

따라서 원하는 답을 얻고 싶다면, 원하는 검토의 범위부터 정확히 써야 합니다.