The Nirsa Way

SpecGuard 소개: AI 코딩 전에 스펙을 먼저 검사하는 도구

KoreaNirsa — Mon, 18 May 2026 00:52:07 +0900

SpecGuard 소개: AI 코딩 전에 스펙을 먼저 검사하는 도구

최근 Codex, Claude Code 같은 AI 코딩 도구를 사용하면서 개발 방식이 많이 바뀌고 있습니다.

간단한 기능은 설명 몇 줄만으로도 빠르게 구현되고, 익숙하지 않은 코드베이스에서도 에이전트가 생각보다 많은 작업을 처리해줍니다. 저 역시 이런 도구를 사용하면서 개발 속도가 빨라지는 경험을 했습니다.

그런데 여러 번 사용해보니 문제가 단순히 “AI가 코드를 잘 짜느냐”에만 있지 않았습니다. 오히려 더 자주 부딪힌 문제는 AI에게 넘긴 스펙 자체가 불완전하다는 점이었습니다.

문제는 코드가 아니라 입력물에 있었다

AI 코딩 도구는 주어진 입력을 바탕으로 구현을 진행합니다.

입력이 명확하면 꽤 좋은 결과를 만들 수 있지만, 스펙이 애매하거나 빠진 부분이 많으면 AI는 그 빈틈을 나름대로 추측해서 채웁니다.

처음에는 구현이 그럴듯해 보입니다. 하지만 개발이 진행될수록 문제가 커집니다.

코드의 품질과 구조가 점점 무너집니다.
스펙과 코드가 점점 맞지 않게 됩니다.
나중에는 코드가 틀린 건지, 스펙이 낡은 건지, 처음 요구사항이 애매했던 건지 구분하기 어려워집니다.

특히 권한, 소유권, 상태 전이, 재시도, 멱등성, API 계약처럼 나중에 고치기 어려운 부분이 스펙에서 빠져 있으면 문제가 더 크게 번집니다.

기존에는 이런 문제를 주로 구현 이후 코드 리뷰에서 잡으려고 했습니다. 하지만 AI 코딩에서는 구현 속도가 빠른 만큼, 잘못된 방향으로도 빠르게 진행됩니다. 그래서 저는 구현 이후 코드 리뷰만으로는 부족하다고 생각했습니다.

결함 있는 스펙이 구현 에이전트에게 넘어가기 전에, 스펙 자체의 빈틈을 먼저 드러내는 단계가 필요했습니다. 이 문제를 줄이기 위해 만든 오픈소스 도구가 SpecGuard입니다.

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

SpecGuard는 무엇인가

SpecGuard는 AI에게 구현을 맡기기 전에 스펙을 먼저 검사하는 CLI / Codex 플러그인입니다.

코드 생성기가 아닙니다. 프롬프트를 넣으면 코드를 만들어주는 도구도 아닙니다.
SpecGuard는 구현 전에 스펙 패키지를 검토하고, 이 스펙을 AI 구현 에이전트에게 넘겨도 되는지 판단하는 도구에 가깝습니다.

기본 흐름은 다음과 같습니다.

1. 사람이 제품 스펙을 작성합니다.
2. SpecGuard가 스펙을 검사합니다.
3. NOT_READY라면 스펙을 보강합니다.
4. READY 또는 READY_WITH_WARNINGS가 되면 Codex, Claude Code 같은 구현 에이전트에게 넘깁니다.
5. 구현 후에는 선택적으로 PR Review를 통해 코드가 승인된 스펙에서 벗어나지 않았는지 확인합니다.

저는 이 흐름을 Validation-First Workflow(VFW)라고 부르고 있습니다. 핵심은 “AI에게 코드를 더 잘 짜게 하자”가 아니라, “AI에게 넘기기 전에 입력물을 먼저 검증하자” 입니다.

A. 어떤 문제를 찾는가

SpecGuard는 주로 구현 전에 놓치기 쉬운 스펙의 빈틈을 찾습니다. 예를 들면 다음과 같은 것들입니다.

인증/권한 경계가 불명확한 경우
tenant/user ownership 범위가 빠진 경우
idempotency, replay, race condition 처리가 없는 경우
만료/철회/상태 전이 규칙이 애매한 경우
webhook, background job, 외부 API 재시도 정책이 없는 경우
API 계약은 있다고 했지만 실제 OpenAPI path가 비어 있는 경우
클라이언트 검증만 믿고 서버 측 검증이 빠진 요구사항

결과는 크게 세 가지로 나뉩니다.

READY: 구현 에이전트에게 넘길 수 있음
READY_WITH_WARNINGS: 넘길 수는 있지만 주의할 점이 있음
NOT_READY: Critical/Major 문제가 있어 스펙 보강 필요

NOT_READY가 나오면 SpecGuard는 구현을 시작하지 말고 스펙을 먼저 고치라고 알려줍니다. 이 점이 중요합니다.
SpecGuard의 목적은 구현을 막는 것이 아니라, 잘못된 구현이 시작되기 전에 멈출 수 있는 지점을 만드는 것입니다.

B. 기본 검사는 API 키 없이 동작한다

SpecGuard의 기본 검사는 로컬 휴리스틱 기반이며 OpenAI API Key 없이도 실행할 수 있습니다.

pip install spec-guard
specguard run specs/your-feature-name --no-llm --no-follow-up

기본 경로를 LLM 기반 리뷰가 아니라 휴리스틱 검사로 둔 이유는 단순합니다.

CI나 PR Review에서는 결과가 빠르고 재현 가능한 것이 중요하기 때문입니다. LLM 기반 리뷰는 비용, 속도, 설정, 모델 변화의 영향을 받을 수 있기 때문에 현재 기본 경로는 빠른 로컬 검사입니다.
더 깊은 리뷰가 필요할 때만 OpenAI Platform 또는 Codex 기반 상세 리뷰를 선택적으로 붙이는 방향으로 두고 있습니다.

C. SpecGuard가 만드는 결과물

SpecGuard가 스펙을 검사하면 사람이 읽을 수 있는 리뷰와 기계가 읽을 수 있는 JSON 결과를 함께 만들며 대표적으로 다음과 같은 결과물이 생성됩니다.

readiness-review.md: 사람이 읽는 스펙 준비 상태 리뷰
readiness-review.json: 플러그인이나 CI가 읽을 수 있는 구조화된 결과
implementation-output.md: 구현 에이전트에게 넘길 수 있는 핸드오프 문서

여기서 중요한 파일은 implementation-output.md입니다.
SpecGuard가 스펙을 READY 또는 READY_WITH_WARNINGS로 판단하면, 구현 에이전트에게 넘길 입력을 정리한 핸드오프 문서를 만들 수 있습니다.
즉, Codex나 Claude Code에게 바로 “알아서 구현해줘”라고 넘기는 대신, SpecGuard가 검토한 스펙과 구현 경계, 테스트/계약 정보를 바탕으로 구현을 시작하도록 만드는 흐름입니다.

D. Codex 플러그인을 추가한 이유

v0.4.0 작업에서는 Codex 앱 플러그인 MVP를 추가했습니다.
기존에는 사용자가 CLI 명령어를 직접 알고 실행해야 했지만 Codex를 쓰는 사용자는 자연스럽게 이렇게 말하고 싶을 수 있습니다.

@SpecGuard specs/your-feature-name 스펙 패키지에 대해 SpecGuard를 실행하고 READY/NOT_READY 상태와 주요 finding을 요약해줘.

SpecGuard Codex 플러그인은 이 흐름을 돕기 위한 것이며 Codex 플러그인은 SpecGuard 엔진을 새로 구현하지 않습니다. 기존 specguard CLI를 호출하고, 생성된 구조화 결과를 읽어서 현재 상태와 다음 행동을 요약합니다.

설치 흐름은 대략 다음과 같습니다.

pip install spec-guard
specguard --help
codex plugin marketplace add KoreaNirsa/spec-guard --ref main

이후 Codex 앱 플러그인에서 Bulit by OpenAI → SpecGuard Plugins 소스를 선택하고 설치하면 됩니다.

다만 중요한 제한이 존재하는데, 플러그인 설치가 specguard CLI 설치까지 자동으로 처리하는 것은 아닙니다.

현재 MVP는 CLI-backed 구조입니다. 따라서 Codex가 실행되는 환경에서 specguard 명령이 동작해야 합니다.

앞으로는 사용자가 직접 명령어를 몰라도 Codex에게 “SpecGuard CLI가 설치되어 있는지 확인하고, 없으면 설치한 뒤 실행해줘”라고 요청할 수 있는 흐름을 더 자연스럽게 만들어 가려고 합니다.

E. PR Review도 지원한다

SpecGuard에는 GitHub Actions 기반 PR Review 흐름도 있습니다.

구현 PR이 올라왔을 때, 승인된 스펙 패키지와 구현 diff를 비교해서 advisory comment를 남기는 방식입니다.

여기서 목표는 “AI가 만든 코드 리뷰”가 아니라, 목표는 구현 결과가 승인된 스펙에서 벗어났는지 확인하는 것입니다.

예를 들어 팀에서 다음 같은 규칙을 두고 싶을 때 사용할 수 있습니다.

NOT_READY 스펙은 구현으로 넘기지 않기
Critical/Major finding을 PR에서 먼저 노출하기
구현 결과물이 아니라 요구사항 입력 품질을 먼저 관리하기
구현 PR이 승인된 스펙과 어긋나는지 확인하기

설치는 CLI에서 다음 명령으로 사용할 수 있습니다.

specguard actions install-pr-review

또는 Codex에게 아래와 같이 요청할 수 있습니다.

@specguard SpecGuard PR Review 워크플로우를 설정해줘.

다만, PR Review가 실제로 OpenAI 기반 리뷰를 수행하려면 GitHub Actions Secret에 SPECGUARD_OPENAI_API_KEY를 등록해야 합니다.

선택적으로 아래 repository variable도 설정할 수 있습니다.

SPECGUARD_PR_REVIEW_MODEL=gpt-5.4-nano
SPECGUARD_REVIEW_SPEC_PATHS=specs/your-feature-name

이 부분도 앞으로 Codex 플러그인에서 더 잘 도와주고 싶은 부분입니다. 예를 들어 사용자가 "@SpecGuard PR Review를 설정해줘"라고 요청하면, Codex가 다음을 순서대로 확인해주는 흐름입니다.

1. 현재 저장소와 브랜치 상태 확인
2. specguard CLI 설치 여부 확인
3. 없으면 설치 안내 또는 설치 실행
4. PR Review workflow 생성 전 사용자 확인
5. specguard actions install-pr-review 실행
6. 필요한 GitHub Secret과 Variables 안내
7. GitHub 연결이 되어 있으면 안전한 secret 등록 경로 안내 또는 보조
8. 연결이 없으면 수동 설정 방법 안내

API Key를 플러그인이 임의로 만들거나 저장해서는 안 됩니다. Secret은 GitHub Actions Secret으로만 다뤄야 하고, 저장소에 커밋되어서는 안 됩니다. 이 보안 경계는 앞으로도 유지할 생각입니다.

설계하면서 중요하게 본 것

SpecGuard를 만들면서 중요하게 본 기준은 아래와 같습니다.

첫째, CLI가 기준이 되어야 합니다.
Codex 플러그인, GitHub Actions, PR Review는 모두 같은 SpecGuard CLI 결과를 읽어야 합니다. 플러그인 안에 별도의 리뷰 엔진을 만들면 동작이 갈라지고 유지보수가 어려워집니다.

둘째, 기본 검사는 재현 가능해야 합니다.
그래서 기본 게이트는 API Key 없이 동작하는 휴리스틱 검사입니다. LLM 리뷰는 더 깊게 보고 싶을 때 선택적으로 붙이는 보조 경로에 가깝습니다.

셋째, 스펙 수정은 사용자가 결정해야 합니다.
SpecGuard는 finding을 보여주고 개선 방향을 제안할 수 있지만, 제품 요구사항 자체를 자동으로 바꾸는 것은 조심해야 합니다. 스펙을 바꾸는 것은 곧 제품 의도를 바꾸는 일이기 때문입니다.

넷째, 구현 에이전트에게 넘기는 입력을 명확히 해야 합니다.
AI 구현 에이전트에게 애매한 요구사항을 던지고 결과를 기다리는 대신, 검토된 스펙과 핸드오프 문서를 넘기는 방식을 지향합니다.

현재 한계와 앞으로 할 일

SpecGuard는 아직 초기 버전입니다.
모든 스펙을 완벽하게 판별하지 못합니다. 특히 휴리스틱 기반 검사는 빠르고 재현 가능하지만, 모든 도메인 문제를 다 잡아내지는 못합니다.

현재 가장 먼저 개선해야 할 방향은 아래와 같이 잡았습니다.

불필요하게 깨지는 테스트 줄이기
핵심 로직 중심의 안정적인 테스트 유지
휴리스틱 리뷰의 미탐/오탐률 개선
Codex 플러그인 사용 흐름 개선
@SpecGuard 기반 PR Review 설정 UX 개선
GitHub Secret/Variables 설정 안내 개선
한국어 스펙에서의 finding 품질 개선

특히 OSS 프로젝트로 운영하려면 테스트가 너무 많은 구현 세부사항에 묶이면 안 된다고 보고 있습니다.
핵심 동작은 지키되, 문서 문구나 내부 구조가 조금 바뀔 때마다 CI가 깨지는 형태는 줄이려고 합니다.

마무리

AI 코딩 도구는 앞으로 더 많이 쓰이게 될 것 같습니다.
하지만 AI에게 무엇을 만들지 알려주는 스펙이 약하면, 구현 속도가 빨라질수록 잘못된 방향으로 더 빠르게 갈 수 있습니다. SpecGuard는 그 전에 한 번 멈춰서 묻는 도구입니다.

이 스펙을 정말 구현 에이전트에게 넘겨도 되는가?

이 질문을 자동화된 게이트로 만들고 싶었습니다.

아직 초기 단계의 OSS 프로젝트지만, AI 코딩을 사용하면서 “스펙이 약해서 구현이 틀어지는 문제”를 겪고 있다면 한 번 사용해보셔도 좋을 것 같습니다.

GitHub 저장소: https://github.com/KoreaNirsa/spec-guard

피드백과 기여도 환영합니다.
현재 이슈와 PR은 주로 영어로 관리하고 있지만, 한국어로 작성해주셔도 괜찮습니다.

특히 아래 피드백이 있으면 많은 도움이 될 것 같습니다.
- 어떤 종류의 스펙에서 잘 맞는지
- 어떤 finding이 과하거나 부족한지
- Codex 플러그인 흐름이 실제로 쓸 만한지
- PR Review 방식이 팀 워크플로우에 맞는지
- 한국어 스펙에서 어색하거나 부족한 부분이 있는지

내가 프로젝트에서 사용하는 개발 방식 - IDAD (Issue-Driven Agent Development)

KoreaNirsa — Sun, 10 May 2026 23:36:54 +0900

내가 프로젝트에서 사용하는 개발 방식 - IDAD (Issue-Driven Agent Development)

AI 코딩 에이전트를 프로젝트에 사용하기 시작하면서 개발 방식이 조금씩 바뀌었습니다.

처음에는 단순히 “AI에게 코드를 작성하게 한다” 정도로 생각했습니다. 하지만 실제 프로젝트에 적용해보니 중요한 것은 AI에게 코드를 얼마나 잘 쓰게 하느냐가 아니었으며 가장 중요한 것은 AI가 무엇을 기준으로 코드를 작성하게 할 것인가였습니다.

이러한 방식으로 인해 스펙 주도 개발이 유행하였고, 대부분의 개발자가 이 기준을 스펙으로 진행하고 있습니다.

하지만 저는 프로젝트에서 이 기준을 이슈로 잡아 진행하고 있으며 이 방식을 개인적으로 IDAD(Issue-Driven Agent Development)라고 부릅니다.

말 그대로, 이슈를 중심으로 AI 에이전트가 개발을 수행하는 방식입니다.

진행중인 SpecGuard 프로젝트에서 IDAD, 즉 이슈 기반으로 개발을 진행하는 모습

왜 이슈가 중요해졌을까

기존 개발 방식에서는 이슈가 사람을 위한 작업 관리 도구에 가까웠습니다.

이슈 확인
  ↓
사람이 요구사항 해석
  ↓
사람이 코드 작성
  ↓
테스트
  ↓
PR 생성
  ↓
리뷰

하지만 AI 코딩 에이전트를 사용하면 이슈의 역할이 달라집니다.

이슈는 더 이상 단순한 할 일 목록이 아닙니다. AI 에이전트가 읽는 작업 지시서가 됩니다.

Issue
  ↓
Agent Context
  ↓
Branch
  ↓
Implementation
  ↓
Pull Request
  ↓
Review
  ↓
Merge

즉, 이슈는 다음 역할을 하게 됩니다.

역할	설명
문제 정의	무엇을 해결해야 하는지 알려준다
범위 제한	어디까지 수정할 수 있는지 정한다
맥락 제공	AI가 참고해야 할 코드, 문서, 로그를 제공한다
완료 기준	어떤 상태가 되면 끝난 것인지 정한다
리뷰 기준	PR이 제대로 작성되었는지 판단하는 기준이 된다

제가 IDAD에서 가장 중요하게 보는 점은 이것입니다.

이슈가 좋아야 AI가 좋은 코드를 작성할 수 있다.

AI 에이전트는 이슈에 적힌 내용을 기준으로 움직입니다.
이슈가 모호하면 AI는 빈칸을 추측으로 채웁니다.
그리고 추측으로 작성된 코드는 리뷰 비용을 크게 늘립니다.

IDAD란 무엇인가?

제가 말하는 IDAD는 간단합니다.

이슈를 AI 에이전트가 실행할 수 있는 작업 단위를 만들고,
AI가 그 이슈를 기준으로 구현을 진행하고,
사람은 PR에서 이슈 충족 여부를 검증하는 개발 방식

기존 이슈 기반 개발과 비슷해 보일 수 있지만 차이가 있습니다.

기존 이슈는 주로 사람을 위한 설명이었습니다.
하지만 IDAD에서 이슈는 AI가 바로 작업할 수 있어야 합니다.

그래서 IDAD의 이슈에는 단순히 “무엇을 한다”만 적지 않고 아래와 같은 내용이 들어가야 합니다.

## 문제
현재 어떤 문제가 있는가?

## 목표
이 이슈가 완료되면 무엇이 가능해야 하는가?

## 변경 범위
수정해도 되는 영역은 어디인가?

## 제외 범위
이번 작업에서 건드리지 말아야 할 영역은 어디인가?

## 완료 조건
어떤 조건을 만족하면 완료로 볼 수 있는가?

## 검증 방법
어떤 테스트, 명령, 화면 확인으로 검증할 것인가?

## 참고 맥락
관련 PR, 문서, 스펙, 로그, 오류 메시지는 무엇인가?

이 정도는 있어야 AI 에이전트가 안정적으로 작업할 수 있습니다.

내가 사용하는 IDAD 흐름

제가 프로젝트에서 사용하는 흐름은 대략 이렇습니다.

이슈를 작성한다
문제, 목표, 범위, 완료 조건, 검증 방법을 적는다
AI 에이전트에게 이슈 기준으로 작업을 요청한다
AI 에이전트가 관련 파일을 탐색한다
최소 변경으로 구현한다
테스트 또는 수동 검증을 수행한다
이슈 번호와 연결된 PR을 만든다
사람이 PR을 리뷰한다
이슈 충족 여부와 범위 초과 여부를 확인한다

여기서 핵심은 이슈 하나가 하나의 목적만 가져야 한다는 점입니다.

예를 들어 이런 이슈는 좋지 않습니다.

회원가입 개선

이런식으로 작성된 이슈에서 동작할 수 있는 경우의 수는 너무나 넓습니다.
AI는 이메일 검증을 고칠 수도 있고, 비밀번호 정책을 바꿀 수도 있고, UI를 수정할 수도 있고, API 응답까지 건드릴 수도 있습니다.

반면 이런 이슈는 더 좋습니다.

회원가입 시 이메일 중복 오류 메시지를 명확하게 수정한다

이슈의 목적이 분명합니다. 수정 범위도 제한하기 쉽고, 리뷰할 때도 “이 PR이 이 이슈를 해결했는가?”를 판단하기 쉽습니다.

좋은 IDAD 이슈 예시

제가 선호하는 이슈 형태는 아래와 같습니다.

## 문제
회원가입 화면에서 이미 등록된 이메일을 입력하면 일반적인 오류 메시지만 표시된다.
사용자는 왜 회원가입이 실패했는지 명확히 알기 어렵다.

## 목표
이메일 중복 오류 발생 시 사용자가 원인을 명확히 알 수 있도록 메시지를 개선한다.

## 변경 범위
- 회원가입 화면의 오류 메시지 표시 로직
- 이메일 중복 오류 응답 처리 로직

## 제외 범위
- DB 스키마 변경 없음
- 회원가입 API 응답 필드 추가 없음
- 이메일 인증 로직 변경 없음
- 관리자 기능 변경 없음

## 완료 조건
- 중복 이메일로 회원가입 시도 시 "이미 사용 중인 이메일입니다." 메시지를 표시한다.
- 신규 이메일 회원가입은 기존과 동일하게 정상 동작한다.
- 다른 회원가입 오류 메시지는 기존과 동일하게 유지한다.

## 검증 방법
- 중복 이메일로 회원가입 시도
- 신규 이메일로 회원가입 시도
- 기존 회원가입 테스트 통과 확인

이렇게 작성하면 AI가 해야 할 일과 하지 말아야 할 일이 명확해집니다.

제가 IDAD에서 특히 중요하게 보는 항목은 제외 범위입니다.
AI 에이전트는 관련 코드를 넓게 수정하려는 경향이 있기 때문에 이번 이슈에서 건드리지 말아야 할 영역을 명확히 적어야 합니다.

Issue-Driven Agent Developemnt의 장단점

IDAD의 장점

제가 IDAD를 쓰면서 느낀 장점은 크게 다섯 가지입니다.

장점	설명
도입 비용이 낮다	대부분의 프로젝트는 이미 이슈 기반으로 일하고 있다
작업 단위가 작아진다	AI가 처리하기 좋은 단위로 일을 쪼갤 수 있다
추적성이 좋아진다	이슈, 브랜치, 커밋, PR, 리뷰가 연결된다
운영 업무에 강하다	버그 수정, 문서 보완, 테스트 추가에 적합하다
병렬 처리가 쉽다	여러 이슈를 여러 에이전트가 나누어 처리할 수 있다

특히 추적성은 실제 프로젝트에서 꽤 중요합니다.

Issue #128
  ↓
feature/issue-128-fix-email-error-message
  ↓
Commit
  ↓
Pull Request
  ↓
Review
  ↓
Merge

나중에 “이 코드는 왜 들어왔지?”라고 확인해야 할 때가 있습니다.
그때 PR만 보는 것보다, 원래 이슈까지 연결되어 있으면 판단이 훨씬 쉬워집니다. 또한 여러 이슈들을 여러 에이전트가 병렬 처리가 가능하기에 개발 속도가 굉장히 빨리지는 것을 체감할 수 있었습니다.

IDAD의 단점

물론 IDAD가 모든 문제를 해결하는 것은 아닙니다.

가장 큰 단점은 이슈가 명세보다 약하다는 점입니다. 일반적인 이슈에는 다음 내용이 충분히 들어가지 않는 경우가 많습니다.

누락되기 쉬운 내용	예시
API 계약	요청 필드, 응답 필드, 상태 코드
예외 처리	실패 시 어떤 응답을 반환할 것인가
권한	누가 이 기능을 사용할 수 있는가
상태 전이	어떤 상태에서 어떤 상태로 변경 가능한가
데이터 소유권	어떤 사용자가 어떤 데이터를 소유하는가
장애 처리	재시도, 타임아웃, 롤백 기준

이런 내용이 빠진 상태에서 AI가 구현하면 겉으로는 동작하는 코드가 나올 수 있지만 시스템의 계약을 위반할 수 있습니다.

예를 들어 API 응답 필드를 마음대로 추가하거나, 권한 검증을 누락하거나, 기존 상태 전이 규칙을 깨는 코드가 만들어질 수 있습니다.

그래서 SDD와는 무엇이 다르고 언제, 어떻게 사용해야 하는가?

AI 시대의 개발 방식으로 SDD, 즉 Spec-Driven Development도 자주 언급됩니다. 제가 보는 IDAD와 SDD의 차이는 이렇습니다.

기준	SDDI	IDAD
중심	스펙	이슈
목적	구현 전 요구사항과 계약을 명확히 고정	이슈 단위로 변경을 빠르게 실행
강점	API, 권한, 예외, 상태, 검증 기준을 구조화	기존 백로그와 PR 흐름에 자연스럽게 연결
적합한 작업	신규 기능, API, 보안, 결제, 권한 변경	버그 수정, 작은 기능, 문서, 테스트, 운영성 개선
검증 위치	구현 전 스펙 검증	PR 단계에서 이슈 충족 여부 검증
속도	상대적으로 느리지만 안정적	빠르지만 이슈 품질에 민감
실패 방식	스펙이 약하면 구현 전 차단 가능	이슈가 약하면 AI가 추측으로 구현할 수 있음

간단히 말하면 이렇게 정리할 수 있습니다.

SDD
= 무엇을 만들지 명확해질 때까지 구현하지 않는다.

IDAD
= 이슈를 실행 가능한 단위로 정리하고, 그 범위 안에서 구현한다.

둘 중 하나가 항상 더 좋다고 보지는 않습니다. 작업의 성격에 따라 다르게 써야 합니다.

현재 저는 A 프로젝트는 SDD 방식으로, B 프로젝트는 IDAD 방식을 사용하며 AI 에이전트를 활용한 여러 개발 방식을 사용해보고, 테스트하고, 실험해보고 있습니다. 현재까지의 상황으로는 서로 명백히 장단점과 성격이 다르기 때문에 큰 특이사항이 없다면 다음 프로젝트에서는 SDD+IDAD 방식으로 함께 사용하 개발을 진행하려 합니다.

오히려 같이 사용했을 때 더 좋은 퍼포먼스가 나올 것으로 생각합니다.

SDD와 IDAD를 무슨 기준으로 진행하는가?

제가 프로젝트에서 기준으로 삼는 방식은 단순합니다.

작고 명확한 변경
  → IDAD로 처리

계약과 리스크가 큰 변경
  → SDD로 전환

조금 더 구체적으로 나누면 다음과 같습니다.

작업 유형	적합한 방식	이유
문구 수정	IDAD	영향 범위가 작다
UI 버그 수정	IDAD	변경 범위를 제한하기 쉽다
테스트 추가	IDAD	기대 동작이 이미 존재한다
문서 보완	IDAD	위험도가 낮다
기존 기능의 작은 확장	IDAD	맥락이 이미 있다
신규 API 설계	SDD	요청/응답 계약이 필요하다
인증/권한 변경	SDD	보안 리스크가 크다
결제/정산	SDD	실패 비용이 높다
데이터 모델 변경	SDD	장기 영향이 크다
외부 시스템 연동	SDD	장애 처리와 재시도 정책이 필요하다

즉, IDAD는 모든 변경을 가볍게 처리하기 위한 방식이 아닙니다.
오히려 가벼운 변경과 무거운 변경을 빠르게 구분하기 위한 방식에 가깝습니다.

위험도에 따른 운영 기준

제가 IDAD를 운영할 때는 이슈를 위험도에 따라 구분합니다.

위험도	예시	처리 방식
낮음	문구 수정, 문서 보완, 테스트 이름 변경, 작은 UI 버그	IDAD로 바로 처리
중간	기존 기능의 작은 확장, 내부 로직 수정, 단일 화면 변경	IDAD로 처리하되 완료 조건과 검증 방법을 명확히 작성
높음	API 계약 변경, 권한 변경, 데이터 모델 변경, 결제/보안 관련 작업	이슈에서 스펙 작성을 요구하고 SDD로 전환

이 기준을 두면 AI 에이전트에게 맡겨도 되는 작업과, 먼저 사람이 설계해야 하는 작업을 구분할 수 있습니다.

IDAD를 사용할 때 지키는 규칙

제가 IDAD를 사용할 때 중요하게 보는 규칙은 다음과 같습니다.

1. 이슈 하나는 하나의 목적만 가진다

좋지 않은 이슈입니다.

대시보드 개선

좋은 이슈입니다.

대시보드 최근 주문 목록의 빈 상태 메시지를 추가한다

AI에게 맡길수록 작업 단위는 더 작고 명확해야 합니다.

2. 완료 조건은 검증 가능해야 한다

좋지 않은 완료 조건입니다.

사용성이 좋아진다.

좋은 완료 조건입니다.

비밀번호 형식이 올바르지 않을 때 INVALID_PASSWORD_FORMAT 메시지를 표시한다.

완료 조건은 테스트하거나 화면에서 확인할 수 있어야 합니다.

3. 검증 방법을 반드시 적는다

이슈에는 최소한 하나 이상의 검증 방법이 있어야 합니다.

검증 방식	예시
테스트 명령	npm test, ./gradlew test
수동 확인 경로	회원가입 화면 → 이메일 입력 → 가입 시도
기대 응답	HTTP 400, EMAIL_ALREADY_EXISTS
화면 기준	특정 오류 메시지 표시
로그 기준	특정 에러 로그가 발생하지 않음

검증 방법이 없으면 PR 리뷰에서 완료 여부를 판단하기 어렵습니다.

4. 제외 범위를 적는다

제가 가장 중요하게 보는 규칙 중 하나입니다.

이번 이슈에서는 DB 스키마를 변경하지 않는다.
API 응답 필드는 추가하지 않는다.
인증 로직은 수정하지 않는다.
관리자 화면은 변경하지 않는다.

AI 에이전트가 코드를 잘 작성하더라도, 범위를 넘어서면 좋은 변경이 아닙니다.

5. PR은 반드시 이슈와 연결한다

PR 설명에는 최소한 아래 내용이 있어야 합니다.

## 해결한 이슈
- Close #128

## 변경 내용
- 이메일 중복 오류 메시지 처리 로직 수정

## 검증 결과
- 중복 이메일 회원가입 시 오류 메시지 확인
- 신규 이메일 회원가입 정상 동작 확인
- 기존 테스트 통과

## 제외한 범위
- API 응답 필드 변경 없음
- DB 스키마 변경 없음

PR 리뷰는 단순히 코드 스타일을 보는 과정이 아닙니다.
IDAD에서는 PR이 원래 이슈를 정확히 해결했는지 확인해야 합니다.

IDAD의 안티패턴

제가 피하려고 하는 안티패턴은 다음과 같습니다.

안티패턴	문제
제목만 있는 이슈를 AI에게 넘긴다	AI가 대부분을 추측하게 된다
여러 기능을 하나의 이슈에 섞는다	변경 범위가 커지고 리뷰가 어려워진다
완료 조건 없이 “개선”만 요청한다	완료 여부를 판단할 수 없다
API 계약 변경을 이슈만으로 처리한다	요청/응답 계약이 깨질 수 있다
권한 변경을 스펙 없이 구현한다	보안 문제가 생길 수 있다
실패 케이스를 정의하지 않는다	정상 케이스만 동작하는 코드가 나올 수 있다
PR 리뷰에서 이슈 충족 여부를 보지 않는다	AI가 범위를 벗어나도 놓치기 쉽다

이런 방식은 IDAD라기보다는 단순히 AI에게 일을 던지는 것에 가깝습니다.

IDAD의 핵심은 AI를 많이 쓰는 것이 아닙니다.
AI가 실행할 수 있을 만큼 작업 기준을 명확하게 만드는 것입니다.

IDAD의 핵심

제가 IDAD를 사용하면서 내린 결론은 단순합니다.

AI 에이전트는 좋은 도구이지만, 좋은 입력이 없으면 좋은 결과를 만들기 어렵습니다.

AI에게 바로 코드를 맡기는 것보다 중요한 것은, 먼저 기준을 세우는 것입니다.

Issue = 작업의 입구
Spec  = 위험한 변경의 기준
PR    = 구현 결과의 검증 지점

가벼운 작업은 IDAD로 빠르게 처리하고 위험한 작업은 SDD로 전환해 먼저 스펙을 세우며 PR에서는 이슈와 스펙을 기준으로 구현 결과를 검증합니다.

마무리

IDAD는 AI에게 단순히 코드를 작성하게 하는 방식이 아닙니다. 이슈를 AI가 실행 가능한 작업 단위로 만들고, 그 이슈를 기준으로 구현과 리뷰를 연결하는 방식입니다.

정리하면 이렇습니다.

작고 명확한 변경
  → IDAD로 빠르게 처리한다

계약과 리스크가 큰 변경
  → SDD로 검증한 뒤 구현한다

AI 시대의 개발 생산성은 코드를 얼마나 빨리 작성하느냐만으로 결정되지 않으며 오히려 더 중요한 것은 어떤 입력을 기준으로 코드를 작성하게 하느냐입니다.

서로 완전히 다른 개발 방식이 아니라, 서로의 장단점을 보완해줄 수 있는 방식이라고 생각하고 있습니다.

IDAD는 이슈로 정리하는 방식입니다.
SDD 스펙으로 검증하는 방식입니다.

둘의 공통점은 하나입니다.

AI에게 코드를 맡기기 전에, 사람이 먼저 기준을 세운다.

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

KoreaNirsa — Sun, 10 May 2026 23:07:59 +0900

개인 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로 넣는 것이 맞는지 아닌지 하나의 결론만 내려줘”도 아니었습니다.

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

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

그리고 각 선택지가 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는 자신이 생각하는 검토를 수행합니다.

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

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

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

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

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

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

결론

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

AI 시대, 왜 소프트웨어 기본기가 더 중요해졌는가?

KoreaNirsa — Sat, 2 May 2026 23:19:29 +0900

※ 해당 포스팅은 Matt pocock의 발표 영상(https://youtu.be/v4F1gFy-hqg?si=7M0lPIfwYiBs4Yfs)을 정리하고, 저의 생각을 추가한 작성한 글입니다.

AI 시대, 왜 소프트웨어 기본기가 더 중요해졌는가?

최근 AI 코딩 도구가 빠르게 확산 되면서 개발 방식도 크게 달라지고 있습니다. 이제는 개발자가 직접 모든 코드를 작성하지 않아도 AI에게 요구사항을 전달하고 코드를 생성하게 만들 수 있습니다.

하지만 Matt Pocock은 이런 흐름 속에서도 소프트웨어 기본기, 즉 Software Fundamentals가 그 어느때보다 중요해졌다고 강조합니다.

핵심은 단순한데, "AI에게 스펙을 전달하고 코드를 생성하게 하는 방식만으로는 좋은 시스템을 만들기 어렵다" 입니다. 코드베이스 전체의 설계를 고려하지 않은 채 기능 추가와 수정만 반복하면 Software Entropy가 발생하고 시스템은 점점 이해하기 어렵고 변경하기 어려운 구조로 변해 결국 유지보수가 힘든 스파게티 코드가 만들어집니다.

※ Software Fundamentals : 소프트웨어 개발의 기본기
※ Software Entropy : 시간이 지날수록 시스템 점점 무질서해지고, 이해하기 어렵고, 변경하기 어려운 상태로 변해가는 현산

AI는 전술적 프로그래머, 개발자는 전략적 설계자

영상에서는 AI를 뛰어난 전술적 프로그래머로 바라봅니다. AI는 구체적인 코드 작성, 구현 세부 사항 처리, 반복 작업 수행에는 강한 강점을 보이지만 시스템 전체의 방향을 결정하고, 모듈간 관계를 설계하고, 유지보수가 가능한 구조를 만드는 책임은 개발자에 있다라고 합니다.

즉 AI 시대의 개발자는 코드를 더 많이 작성하는 사람이 아니라, AI가 좋은 코드를 작성할 수 있는 환경을 설계하는 사람에 더욱 가까워지고 있습니다.

이 영상에서 말하는 전체적인 워크플로우는 아래와 같은 형태를 가집니다.
요구사항 전달 → AI와 공통 이해 형성 → 용어와 설계 개념 정리 → 작은 단위로 테스트하며 구현(TDD) → 딥 모듈로 복잡성 은닉 → 인터페이스는 개발자가, 구현은 AI에게 위임 → 유지보수 가능한 코드 베이스 확보

1. AI와 먼저 공통된 설계 개념을 맞춰야 한다.

AI와 협업할 때 자주 발생하는 문제는 "AI가 내가 원한 대로 하지 않았다"라는 것 입니다. 이 문제는 단순한 프롬프트 문제가 아니라, 개발자와 AI가 서로 다른 설계 개념을 가지고 있기 때문에 발생합니다.

영상에서는 이를 해결하기 위한 방법으로 Grill Me 기법이 소개되는데, 이 방식은 AI에게 다음과 같은 역할을 부여하는 것 입니다.

"우리가 공유된 이해에 도달할 때까지 이 계획의 모든 측면에 대해 계속 질문하라"

AI가 요구사항, 의존 관계, 설계 의도를 계속 파고들게 만들면 개발자와 AI 사이의 생각 차이를 줄여나갈 수 있습니다.

2. 유비쿼터스 언어로 AI와 같은 단어를 사용한다.

해당 영상에서는 도메인 주도 설계의 유비쿼터스 언어 개념도 중요하게 다루고 있습니다.

기존에는 기획자와 개발자 간의 용어 간극을 메우기 위한 방법이였다면, 이 포스텡어슨ㄴ 현재는 AI와 개발자 간의 간극을 메우기 위한 방법으로써 활용됩니다.

AI와 개발자가 같은 단어를 다른 의미로 사용하면 결과물을 쉽게 어긋나기 때문에, 코드 베이스에서 사용하는 핵심 용어를 마크다운 파일 등으로 정리하고 AI가 계획 수립과 코딩 과정에서 이 용어를 기준으로 생각하게 만드는 것이 필요합니다.

구분	문제 상황	해결 방식
설계 개념	개발자와 AI가 서로 다른 결과를 상상함	Grill Me 기법으로 질문을 유도하여 공통 이해 형성
용어	같은 단어를 다른 의미로 해석함	유비쿼터스 언어를 마크다운 파일로 정리
구현 방향	AI가 설계 의도와 다른 코드를 작성함	용어집과 설계 개념을 계속 참조하게 함

여기서 말하는 용어집은 말 그대로 용어들을 정리하여 개발자와 AI가 용어에 의한 차이를 보이지 않도록 하는 것입니다.

# 용어집 예시
수강생(Student)
- 학원에서 강의를 신청하고 수강하는 사용자
강사(Instructor)
- 강의를 개설하고 수업을 진행하는 사용자
강의(Course)
- 특정 주제와 기간을 가진 수업 단위
수강신청(Enrollment)
- 수강생이 특정 강의에 참여 신청하는 행위
정원(Capacity)
- 하나의 강의에 등록 가능한 최대 수강생 수

3. TDD로 AI의 작업 단위를 작게 유지한다.

현재 AI를 사용하며 개발을 하시는 분들은 "한번에 여러가지의 작업을 요청하지 마라" 라는 말을 들어보셨을겁니다.

AI는 때때로 너무 많은 코드를 한 번에 작성하려 하는데, 이를 '헤드라이트보다 빨리 달리는 상황'으로 설명합니다. 코드가 빠르게 생성되더라도 검증 없이 많은 변경이 쌓이면 개발자는 오히려 결과를 따라가기 힘들어지고, 이는 오히려 개발자가 병목의 원인이 되는 이유로 이어집니다.

영상에서는 이를 제어하기 위한 핵심 방법으로 TDD를 소개하고, 이는 저의 개인적인 AI 이후 개발 방법론과 정확하게 일치합니다.

이전 사람이 TDD를 작성할때는 오히려 테스트 코드를 작성하느라 개발 속도가 느려지고, 테스트 코드가 '주'가 되면서 테스트 코드의 품질에 신경쓰다보니 실제 개발의 코드 품질이 오히려 낮아지며 대부분의 TDD는 실패한 TDD인 상황이 많았습니다.

하지만 AI 시대에서 코드의 작성을 AI에게 위임하게 되면서 코드 생산성이 수십배 빨라진 상황에서, TDD는 오히려 AI와 함께 사용함으로써 더욱 많은 장점을 제공합니다.

TDD를 사용함으로써 AI가 작은 단계로 움직이게 만듭니다. 테스트를 먼저 작성하고, 작은 단위로 구현하고, 다시 리팩터링하는 흐름은 AI의 코드 생성을 사람이 검증 가능한 단위로 제한할 수 있습니다.

영상에서는 피드백 루프의 속도가 개발 속도와 연결된다고 설명합니다. 결국 빠른 개발은 단순히 코드를 많이 생성하는 것이 아니라, 빠르게 검증하고 안정적으로 다음 단계로 넘어가는 구조를 만드는 것 입니다.

4. 딥 모듈로 복잡성을 숨긴다.

영상에서 강조하는 또 하나의 핵심은 딥 모듈(Deep Modules) 입니다.

딥 모듈은 많은 기능과 복잡성을 내부에 숨기고 외부에는 단순한 인터페이스만 노출하는 구조입니다. 이미 좋은 메이저 오픈소스들은 사용자가 내부 구현을 몰라도 사용할 수 있도록 복잡한 구현을 단순한 public interface 뒤에 숨기는 경우가 많습니다. 이는 딥 모듈의 핵심과 일치합니다.

반대로 얕은 모듈(Shallow Modules)은 기능이 너무 작은 조각 단위로 흩어져 있어 AI가 코드의 맥락을 파악하기 어렵게 하며 AI는 수많은 파일과 함수, 의존 관계를 따라가야 하고 코드 베이스의 목적과 경계를 놓칠 수 있습니다.

구분	얕은 모듈	딥 모듈
구조	작은 조각이 많이 흩어져 있음	관련 기능을 하나의 모듈로 묶음
인터페이스	외부에서 알아야 할 것이 많음	외부 인터페이스가 단순함
복잡성	외부로 노출되기 쉬움	내부로 캡슐화됨
AI 협업	맥락 추적이 어려움	모듈의 목적과 경계를 이해하기 쉬움
테스트	검증 지점이 분산됨	입출력 경계 기준으로 테스트 가능

딥 모듈을 만드릭 위한 기준은 관련 코드들을 찾아 하나로 묶고, 외부에서는 단순한 인터페이스만 호출하도록 만드는 것 입니다.

이러한 방식의 핵심은 복잡성은 내부에 숨기고 인터페이스는 단순하게 유지하는 것이며 이는 다음 내용과 이어집니다.

5. 인터페이스는 개발자가 설계하고 구현은 AI에게 위임한다.

현재 AI 시대의 개발자들은 모든 구현을 직접 작성할 필요가 없습니다. 인터페이스는 개발자가 직접 설계하고, 구현은 AI에게 위임하는 방식을 제안합니다.

이 접근은 개발자의 인지 부하를 줄여줍니다. 개발자는 모듈의 경계, 입출력, 테스트 가능성, 시스템 전체 방향에 집중하고 AI는 그 안쪽 구현을 담당합니다.

이것이 전략적 프로그래머의 역할입니다.즉, 앞으로는 더욱 더 코드를 잘 작성하는 개발자보다는 아키텍처의 관점에서 코드를 잘 설계하고 AI에게 구현을 위임할 수 있는 개발자가 되어야 합니다.

결론

AI의 압도적인 생산성으로 인해 개발자가 모든 코드를 직접 치던 시대는 점점 끝나가고 있습니다. 그러나 좋은 코드베이스와 좋은 설계가 없다면 AI는 오히려 소프트웨어 엔트로피를 빠르게 증가시킵니다.

AI 시대에 중요한 것은 코드를 얼마나 많이 생성하고 빠르게 기능을 구현하느냐가 아니라, AI가 올바른 코드를 생성할 수 있도록 시스템을 설계하는 능력입니다. 이제 개발자는 코드를 직접 구현하는 포지션이 아니라, 전략적 설계자로써 코드베이스의 품질을 지켜야 합니다.

많은 개발자들은 이러한 AI의 압도적은 생산성으로 인해 소프트웨어 기본기보다는 화려한 기술들을 향해 가고 있지만, 역설적이게도 AI의 압도적인 생산성으로 인해 소프트웨어의 기본기가 점점 더 중요해지고 있습니다.

[이런 저런 이야기] 2025 표준프레임워크 컨트리뷰션 후기 (feat. 굿즈 개봉)

KoreaNirsa — Sun, 2 Nov 2025 00:07:53 +0900

[이런 저런 이야기] 2025 표준프레임워크 컨트리뷰션 후기 (feat. 굿즈 개봉)

올해는 2025 표준프레임워크 컨트리뷰션에 참여하였고 오늘 감사장과 굿즈를 배송 받아 후기를 남깁니다.

1. 참여한 계기

올해는 유독 일을 오래 쉬었다보니 ~~시간 부자가 되어서~~ 평소에 관심있던 오픈소스에 기여를 해보자라는 생각을 가지게 되었습니다.

그중에서 spring-boot, spring-petclinic, spring-ai, 표준프레임워크 이렇게 4가지 정도로 정리가 되었는데, 결과적으로는 spring-ai와 표준 프레임워크를 선택하게 되었습니다.

spring-ai는 학습하는 과정에서 일부 중복이나 성능 개선이 가능한 코드를 ~~아주 조금~~ 수정하고 표준프레임워크에서는 레거시한 코드 구조와 스웨거를 명확히 출력 하도록 개선하기 위한 작업을 진행하였습니다. 처음부터 너무 많은 것을 바꾸려 하면 현실적으로 불가능하다 판단되어 우선은 패키지 구조와 요청/응답 데이터를 도입하여 유지보수성 및 스웨거를 출력하는 것이 1차 목표였어요.

올해 진행한 PR들

기여하다보니 커밋 기준 #1 컨트리뷰터 ?!

2. 아쉬운 것들

표준프레임워크 simple-backend 템플릿에서 bbs에 관련된 것은 컨트리뷰션이 종료되기 전 모두 진행하려 했으나, 아무래도 매일 이것만을 잡고 있을 순 없기 때문에 몇 개의 메서드를 아직 개선하지 못한채로 종료된 것이 아쉽네요.

실제로 요청 데이터나 응답 데이터를 Map 형태로 주고 받고 모든 필드를 사용하며, 하나를 수정하게 되면 다른 의존하는 코드들이 에러를 뿜어대다보니 조금의 수정도 생각보다 많은 시간을 투자해야 했습니다 ㅠㅠ

개인적으로 컨트리뷰션이 종료된 후에도 simple-backend는 구조 개선을 목표로 여유가 있을 때 지속적으로 기여를 할 생각이고 최종적으로 구조 개선 후에는 성능 개선, 불필요한 로직, 미사용 필드를 제거하는 과정을 진행해보고 싶네요.

내년에는 책을 집필하는 것이 목표이기 때문에 만약 시간이 된다면 공통 컴포넌트나 msa 템플릿에도 기여를 해볼 생각입니다.

3. 굿즈 개봉 후기

우선 감사장이 너무 귀여운 형태로 왔습니다 ㅋㅋ 상장같은 느낌일줄 알았는데 저의 깃허브 닉네임이 박힌 피규어와 함께 손바닥 크기 정도의 피규어 감사장이 도착했어요.

피규어는 구글 스터디잼 이후로 처음 받아보는데, 피규어 감사장이 너무 귀여워서 제 책상에 올려두었습니다

그리고 오픈플랫폼개발자커뮤니티라고 작성된 에코 수첩과 런치백이 있더라구요. 마스코트가 해달인지 처음 알게 되었는데 너무 귀여웠습니다.

내년에도 표준프레임워크 컨트리뷰션에 참여할 생각이고, 만약 이 포스팅을 읽으며 고민중이신 분이 계시다면 한번 해보시는 것도 좋은 경험이 될 것 같습니다~

[AWS] Route53 + CloudFront + S3 + ACM 정적 페이지 배포하기 (HTTPS 배포, 가비아 도메인 연동)

KoreaNirsa — Fri, 19 Sep 2025 00:26:19 +0900

[AWS] Route53 + CloudFront + S3 + ACM 정적 페이지 배포하기 (HTTPS 배포, 가비아 도메인 연동)

AWS의 Route53, CloudFront, S3, ACM를 사용하여 정적 페이지를 배포하는 방법입니다. 저는 미리 가비아에서 도메인을 구입해둔 상태이기 때문에 해당 도메인을 연동하고 ACM으로 인증서를 발급하여 HTTPS로 배포하도록 하겠습니다.

1. S3 버킷 생성

우선 가장 먼저 AWS에 로그인하여 콘솔에서 s3를 검색한 후 클릭하여 서비스에 들어가주세요.

우측의 버킷 만들기를 클릭합니다.

버킷 이름을 작성하고 다른 옵션들은 그대로 둔 채 우측 하단의 "버킷 만들기"를 클릭 해주세요.

이후 생성된 버킷을 클릭하고 업로드 하려는 파일을 마우스로 올려서 업로드를 진행한 뒤 우측 하단의 "업로드"

2. AWS CloudFront

이제 다시 콘솔에서 cloudfront를 검색하여 해당 서비스를 클릭한 후 "CloudFront 배포 생성"을 클릭해주세요.

배포 이름은 편하신데로 임의로 작성한후 하단의 Next를 눌러줍니다.

현재 포스팅은 S3를 기반으로 배포하기 때문에 Origin type을 Amazone S3로 지정해주고, 아래의 Browse S3를 클릭하여 버킷을 연결해주시면 됩니다.

Origin path - optional는 선택 사항이며 저는 S3 버킷에 iPortfolio라는 폴더가 기본적으로 있기 때문에 기본 경로로 설정하였습니다. 즉 도메인.com 으로 사용자가 접속할 경우 기본 경로를 "도메인.com/iPortfolio"가 됩니다.

만약 S3 버킷에 폴더 아래에 html, css, js 파일들이 있는 구조라면 폴더명을 작성해주시면 되며 S3 버킷에 따로 폴더를 한번 거쳐서 가는 형태가 아닌 html, css, js 파일들이 바로 있는 형태라면 빈값으로 두고 진행하시면 됩니다.

아래와 같이 저는 현재 iPortfolio 폴더 아래에 정적 파일들이 있는 형태이기 때문에 작성한 것 입니다.

정적 페이지이기도 하고 잠깐 사용할 것이기 때문에 비용을 최소화 하기 위해 "보안 보호 비활성화"로 진행하였습니다.

마지막으로 하단의 Create distribution을 클릭하여 CloudFront 설정을 마무리 합니다.

3. AWS Route53

다시 콘솔에서 route53을 클릭하여 서비스에 들어가고 "시작하기" 버튼을 클릭해주세요.

"호스팅 영역 생성"을 선택하고 "시작하기" 버튼을 클릭하여 다음 단계로 넘어갑니다.

도메인 이름(ex. tistory.com)을 입력하고 "호스팅 영역 생성"을 클릭하여 Route53을 생성하고 마무리합니다.

4. AWS Certificate Manager (ACM)

이제 ACM을 사용하여 인증서를 발급하는 과정입니다. 콘솔 검색에서 ACM을 입력하여 Certificate Manager를 클릭해주세요.

우측 상단에서 리전을 "버지니아 북부"로 변경해줍니다.

※ CloudFront에 인증서를 사용하기 위해서는 ACM의 리전을 버지니아 북부(us-east-1)로 하여 사용해야 합니다.

https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/cnames-and-https-requirements.html?utm_source=chatgpt.com

이제 요청 → 퍼블릭 인증서 요청 → 다음을 클릭해주세요.

구매해두었던 도메인 이름을 추가합니다. 저는 "이 인증서에 다른 이름 추가"를 클릭하여 도메인을 추가 하였습니다. 인증서를 발급받을 도메인을 입력한 후 우측 하단의 요청을 눌러주세요.

예시) tistory.com / www.tistory.com 이와 같은 형태로 총 2개를 입력하였습니다.

인증서 생성이 완료되었다면 "Route 53에서 레코드 생성" 버튼을 클릭 후 레코드 생성을 진행해주세요.

처음엔 "검증 대기 중"으로 되어있으며 이후 가비아 도메인 연동 등 추가적인 설정 이후 완료될 것 이기 때문에 우선은 무시한 채 아래의 가비아 도메인 연동 설정을 진행해주세요.

5. 가비아 도메인 연동

가비아 홈페이지로 이동하셔서 로그인 후 우측 상단의 My가비아 → 도메인을 클릭해주세요.

미리 구매해둔 도메인을 확인하고 우측 "관리" 버튼을 클릭합니다.

네임서버 설정을 클릭해주세요.

AWS Route53을 보면 NS 유형에 총 4개의 값이 보일겁니다. 이 값들을 각각 가비아에서 1~4차의 호스트명에 입력하여 적용해주세요. 순서 상관 없이 값들을 채워 넣어주면 됩니다.

※ 가비아에 네임서버 입력 시 마지막에 . 을 빼주셔야 합니다.

7. 마무리 (CloudFront 대체 도메인 이름, Path 설정 및 Route53 A 레코드 등록)

다시 CloudFront 서비스로 들어가서 대체 도메인 이름 아래에 있는 "Add domain"을 클릭해주세요.

"Add another domain"을 클릭하여 도메인 입력란을 추가하고 구매한 2개의 도메인 주소를 입력해주세요.

예시) tistory.com / www.tistory.com

ACM 설정이 잘 되어 있으면 아래와 같이 기본적으로 연결되어 있으니 Next → Add domains를 눌러 마무리 해줍니다.

다시 CloudFront 서비스 화면에서 우측의 편집을 눌러주세요.

비용 절감을 위해 "Use North America, Europe, Asia, Middle East, and Africa"로 선택합니다.

스크롤을 조금 내리면 Default root object - optional가 있을텐데, 이는 사용자가 Root URL(/)을 요청할 경우 반환할 파일을 선택해주어야 합니다. 즉 예를들어 htts://도메인.com/을 입력할 경우 어떤 정적 페이지를 보여줄 것인가에 대한 옵션입니다.

저는 기본적으로 index.html 파일을 보여줄 것이기 때문에 index.html을 작성하였습니다. 설정 완료 후 "변경 사항 저장"을 클릭하여 CloudFront 설정을 마무리해주세요.

이제 마지막으로 Route 53으로 돌아와서 "레코드 생성"을 클릭해주세요.

A 레코드를 추가하고 별칭 토클을 한번 클릭하여 "CloudFront 배포에 대한 별칭"을 클릭하고 배포 선택을 클릭해줍니다.

이후 "다른 레코드 추가"를 눌러 www에 대한 설정도 똑같이 진행한 뒤 "레코드 생성"을 클릭하여 마무리해주시면 됩니다.

배포 확인하기

이제 배포한 도메인으로 접속하면 아래와 같이 정적 페이지가 배포된 것을 확인할 수 있습니다.

[LLM] 컨텍스트 엔지니어링이란? (Context Engineering, RAG, Chunking, Embedding, Vector Search, Context Injection)

KoreaNirsa — Mon, 15 Sep 2025 18:19:45 +0900

[LLM] 컨텍스트 엔지니어링이란? (Context Engineering)

LLM은 기본적으로 프롬프트를 기반으로 답변을 생성하게 되는데, 실제 서비스 환경에서는 특정 작업에 따른 정보를 제공하여 더 정확한 답변을 줄 수 있습니다. 즉, LLM이 응답을할 때 특정 도메인이나 상황에 맞춰 필요한 문맥(Context)을 공급하여 더 정확한 답변을 유도하는 기법을 의미합니다.

예를들어 사내에서 사용할 QA 챗봇을 만드는 상황에서 "우리 회사의 연차 규정을 알려줘" 라고 하면 일반적으로 다른 회사들이 사용하는 정보들을 기반으로 답변이 제공됩니다.

// 간단한 예시
사용자 : 우리 회사의 연차 규정을 알려줘
답변 : 대한민국 근로기준법에 따르면 근로자는 1년에 15일 이상의 연차를 보장받습니다.

하지만 컨텍스트 엔지니어링을 적용하여 답변할 때 참고해야할 추가 문맥(Context)를 제공, 즉 회사 연차 규정이 적혀있는 문서를 제공한다면 회사에 맞춘 답변을 제공할 수 있게 됩니다.

// 간단한 예시 (컨텍스트 엔지니어링 적용)
사용자 : 우리 회사의 연차 규정을 알려줘
  - 사내 인사 규정 문서 검색
답변 : 우리 회사는 입사 1년 후 15일, 3년 이상 근속 시 20일, 최대 25일의 연차를 제공합니다

위의 예시와 같이 컨텍스트 엔지니어링이 적용된 사내 QA 챗 봇을 사용한다면 문서를 검색하여 "우리 회사"에 대한 연차 규정을 정확하게 확인하고 답변이 가능한 형태가 됩니다. 위의 예시를 조금만 더 자세히 한다면 다음과 같습니다.

사용자 입력 : "우리 회사의 연차 규정을 알려줘"
컨텍스트 검색 : 사내 DB 또는 문서에서 관련 컨텍스트(연차 규정) 검색
실제 LLM 입력 : 검색된 컨텍스트, 사용자가 입력한 프롬프트 등을 LLM에게 실제로 입력
답변 생성 : "우리 회사는 입사 1년 후 15일, 3년 이상 근속 시 20일, 최대 25일의 연차를 제공합니다"

컨텍스트 엔지니어링의 대표적인 기술 RAG

컨텍스트 엔지니어링에서 가장 대표적인 기술로써는 RAG(Retrieval-Augmented Generation)이 있습니다. 이는 위에서 살펴봣던 예시와 같이 DB나 문서를 검색하여 그 결과를 LLM 입력에 함께 넣어 답변을 생성하는 방식입니다.

RAG를 사용하게 되면 DB나 문서를 검색함으로써 모델 파라미터에 직접 학습시키지 않더라도 최신 정보 또는 도메인 지식을 활용할 수 있는 가장 큰 장점이 있습니다. 이로써 고객 지원 챗봇이나 제품 매뉴얼, 최신 뉴스 요약 등의 분야에서 활용될 수 있습니다.

동작 구조는 크게 5가지로 나뉘어 집니다.

1. 사용자 질문

가장 처음으로는 "우리 회사의 연차 규정을 알려줘"와 같이 사용자에게 질문을 받습니다.

2. Chunking

토큰 한계와 비용에 대한 문제로 긴 원문 자체를 넣기가 어렵기 때문에 효율을 위해 원문을 적절한 크기로 쪼개서 부분적으로 검색을 합니다. 즉 문서를 작은 단위로 나누는 작업단, 원문을 잘못 쪼갤 경우 문맥이 끊겨 정확도가 떨어지거나 불필요한 토큰이 낭비되는 단점이 있습니다.

※ 토큰이란?
LLM이 텍스트를 처리할 때 잘게 쪼개는 단위로써 보통 자주 쓰이는 단어나 문자열 패턴을 1토큰으로 지정합니다.
ex) ChatGPT is powerful! → ["Chat", "G", "PT", " is", " powerful", "!"]으로 나뉘어질 수 있으므로 6토큰

아래와 같은 원문이 있다고 가정하겠습니다.

우리 회사는 입사 1년 후 15일의 연차를 지급합니다.
3년 이상 근속한 직원에게는 20일 10년 이상 근속한 직원에게는 25일의 연차를 지급합니다.
연차는 근로기준법을 준수하며 개인 사정에 따라 분할 사용이 가능합니다.

이에 대한 원문을 Chunking할 때 토큰 길이, 문장/문단 기준, 재귀 분할 등 여러가지가 있지만 단순히 문자열을 기준으로 한다는 가정하에 chunk, overlap을 사용하는데 간단히는 chunk과 overlap을 문자열 기준으로 적용한다면 chunk는 자를 문자열의 수, overlap은 앞 청크의 뒷부분을 겹칠 문자열의 수가 됩니다.

chunk 단위로 쪼개게 되면 문장이 중간에 잘려서 의미가 끊길 수 있기 때문에 겹치는 부분으로 문장을 자연스럽게 연결시켜주는 징검다리 역할을 수행해주는 것이 overlap 입니다. 만약 chunk=40, overlap=10으로 설정한다면 아래와 같은 결과를 얻을 수 있습니다.

40자를 기준으로 문서를 쪼게고, 앞 청크의 뒷부분을 overlap 만큼(10자) 다음 청크에서 반복시켜서 문장을 자연스럽게 연결시켜주게 됩니다. 아래의 예시에서는 ( ) 으로 표현된 것이 overlap으로 인해 다시 등장한 문자열입니다.

[Chunk 1] 우리 회사는 입사 1년 후 15일의 연차를 지급합니다. 3년 이상 근속한
[Chunk 2] ( 3년 이상 근속한) 직원에게는 20일 10년 이상 근속한 직원에게는 25
[Chunk 3] (한 직원에게는 25)일의 연차를 지급합니다. 연차는 근로기준법을 준수하며
[Chunk 4] (기준법을 준수하며 )개인 사정에 따라 분할 사용이 가능합니다.

3. Embedding (텍스트 → 숫자 좌표화)

임베딩에서는 텍스트를 벡터로 바꾸게 됩니다. 즉 텍스트를 숫자 좌표(벡터)로 바꾸는 기술로써 같은 문장 끼리는 벡터 공간에서 가깝게, 다른 뜻이라면 멀게 배치가 됩니다.

간단히는 지도를 생각해보시면 되는데, 서울(37.5, 127)과 인천(37.4, 126.7)의 좌표는 가깝고 부산(35.1, 129.0)과는 먼것을 생각하시면 됩니다. 이에 따라 벡터도 숫자 좌표를 기준으로 같은 문장끼리는 가까운 곳에, 다른 문장끼리는 먼 곳에 배치하는 기술입니다.

예를들어 아래와 같이 텍스트를 벡터로 변환하게 됩니다. (숫자는 임의로 작성했습니다)

텍스트: "우리 회사의 연차 규정을 알려줘"
질문 벡터: [0.011, -0.030, 0.543, ...]

텍스트: "우리 회사는 입사 1년 후 15일의 연차를 지급합니다. 3년 이상 근속한"
Chunk 1 벡터: [0.012, -0.028, 0.551, ...]

텍스트: "( 3년 이상 근속한) 직원에게는 20일 10년 이상 근속한 직원에게는 25"
Chunk 2 벡터: [0.010, -0.033, 0.561, ...]

텍스트: "(한 직원에게는 25)일의 연차를 지급합니다. 연차는 근로기준법을 준수하며"
Chunk 3 벡터: [0.015, -0.035, 0.575, ...]

텍스트: "(기준법을 준수하며 )개인 사정에 따라 분할 사용이 가능합니다."
Chunk 4 벡터: [0.025, -0.061, 0.864, ...]

텍스트: "퇴직금 정산 방법"
벡터: [0.234, 0.481, -0.112, ...]

이러한 결과를 봣을 때 "우리 회사의 연차 규정을 알려줘"과 "우리 회사는 입사 1년 후 15일의 연차를 지급합니다. 3년 이상 근속한"는 아주 가깝게 배치되어 있어 의미가 비슷하다고 판단할 수 있으며, "퇴직금 정산 방법"의 경우 멀게 배치되어 있어 다른 의미를 가지고 있다고 판단할 수 있는 근거로 활용될 수 있습니다.

이는 아래의 벡터 검색(Vector Search)에서 활용됩니다.

4. Vector Search (질문과 가장 가까운 청크 찾기)

벡터 검색에서는 질문과 가장 가까운 청크를 찾습니다. 질문 벡터와 각각의 청크 벡터들을 비교하여 코사인 유사도를 확인하여 이에 대한 정렬 결과를 가지고 답변에 활용할 문맥(Context)으로 활용되게 됩니다.

이와 같이 코사인 유사도에 따라 Top 4로 정렬을 한다면 Chunk 1 > Chunk 2 > Chunk 3 > Chunk 4로 정렬되게 됩니다. "퇴직금 정산 방법"에 대한 벡터는 코사인 유사도가 매우 떨어지므로 제외되는 방식 입니다.

그렇다면 최종적으로 벡터 검색에 의해 정렬된 내용은 아래와 같습니다.

[Chunk 1] 우리 회사는 입사 1년 후 15일의 연차를 지급합니다. 3년 이상 근속한
[Chunk 2] ( 3년 이상 근속한) 직원에게는 20일 10년 이상 근속한 직원에게는 25
[Chunk 3] (한 직원에게는 25)일의 연차를 지급합니다. 연차는 근로기준법을 준수하며
[Chunk 4] (기준법을 준수하며 )개인 사정에 따라 분할 사용이 가능합니다.

5. Context Injection (컨텍스트 주입 및 프롬프트 구성)

이제 컨텍스트를 주입합니다. 최종적으로 아래와 같은 프롬프트가 구성될 수 있으며 토큰 절약을 위해 중복되는 표현(overlap 등)은 정리하여 주입해도 좋습니다.

// 내부 시스템 프롬프트
[System]
너는 우리 회사 HR 정책을 안내하는 어시스턴트야.
아래 '컨텍스트'에 근거해 답하고 근거가 없으면 "문서에 근거가 없습니다"라고 말해야 하며
가능하면 출처(청크 번호/문장)를 괄호로 표시하도록 해

[Instruction]
사용자의 질문에 맞게 핵심만 간결히 요약해서 답변해

// 벡터 검색으로 찾은 청크 4개를 컨텍스트 주입
[Context]
[Chunk 1] 우리 회사는 입사 1년 후 15일의 연차를 지급합니다. 3년 이상 근속한
[Chunk 2] ( 3년 이상 근속한) 직원에게는 20일 10년 이상 근속한 직원에게는 25
[Chunk 3] (한 직원에게는 25)일의 연차를 지급합니다. 연차는 근로기준법을 준수하며
[Chunk 4] (기준법을 준수하며 )개인 사정에 따라 분할 사용이 가능합니다.

// 사용자 질문
[User]
우리 회사의 연차 규정을 알려줘

6. 답변 생성

이제 LLM이 컨텍스트를 참고하여 답변을 제공 합니다.

우리 회사는 입사 1년 후 15일의 연차를 부여하며
3년 이상 근속 시 20일, 10년 이상 근속 시 25일을 부여합니다.
연차는 근로기준법을 준수하여 분할 사용을 할 수 있습니다.

마무리

마지막으로 컨텍스트 엔지니어링에 대해 요약하며 포스팅을 마치도록 하겠습니다.

A. 컨텍스트 엔지니어링 이란?

LLM이 응답을할 때 특정 도메인이나 상황에 맞춰 필요한 문맥(Context)을 공급하여 더 정확한 답변을 유도하는 기법을 의미합니다

B. 왜 필요한가?

정확성 향상 : 회사/제품/내부 규정과 같은 도메인 지식 반영
최신성 유지 : 모델을 학습시키지 않아도 최신 문서 반영 가능
일관성 확보 : DB/문서를 근거로 답변하므로 일관성 확보

C. 자주 사용되는 대표 상황 3가지

사내 QA : 인사/보안/IT 규정 챗봇
고객 지원 : 매뉴얼/FAQ/회사 정책에 근거하여 답변
지식 검색 : 위키/노션/사내 문서를 바탕으로 요약 또는 답변

D. 아주 간단히 보는 컨텍스트 엔지니어링의 흐름

질문 수신
관련 DB/문서 검색 (RAG 등)
검색하여 찾은 조각을 프롬프트에 주입(컨텍스트 주입)
근거 기반 답변 생성

E. 프롬프트 엔지니어링 vs 컨텍스트 엔지니어링 간단 비교

F. 자주 하는 오해

Q. 프롬프트만 잘 짜면 충분하지 않나? 컨텍스트 엔지니어링이 필요한 이유?
A. 내부 규정 또는 최신 정보, 특정 도메인에 대한 지식은 AI 모델에 의존해야 하므로 한계가 존재함

Q. 컨텍스트와 파인튜닝은 같은 것인가?
A. 파인튜닝은 AI 모델을 다시 학습하는 개념이며
   컨텍스트는 검색한 문서의 조각을 프롬프트에 붙여주는 행위에 가깝습니다.
   
Q. 그렇다면 컨텍스트 엔지니어링은 무조건 좋은것인가?
A. 문서 자체가 부정확하는 등 품질이 떨어지면 답변의 퀄리티 또한 같이 떨어집니다.
   컨텍스트 엔지니어링의 핵심은 좋은 문서가 기반이 되어야 합니다.

[LLM] 입문자를 위한 프롬프트 엔지니어링 개념과 3대 원칙 (Role, Instruction, Few-shot)

KoreaNirsa — Fri, 12 Sep 2025 21:54:58 +0900

[LLM] 입문자를 위한 프롬프트 엔지니어링 개념과 3대 원칙 (Role, Instruction, Few-shot)

프롬프트 엔지니어링은 AI 모델이 원하는 방식으로 응답할 수 있도록 프롬프트를 설계, 최적화 하는 과정입니다. LLM은 기본적으로 입력된 프롬프트를 기반으로 다음 토큰을 예측하기 때문에 프롬프트를 잘 작성하면 LLM 모델의 답변 품질을 크게 올릴 수 있습니다.

만약 모호한 프롬프트를 주면 예상과 다른 답변이 나올 확률이 그만큼 높으며 AI 활용을 하기 위해서는 명확하고 구조화된 프롬프트를 작성하는 능력이 필요합니다. 이러한 프롬프트 설계 능력을 통해 각 분야에 AI를 활용했을 때 증가하는 생산성은 크게 차이가 나게 됩니다.

보통 GPT와 같은 AI 플랫폼을 사용할 때 "잘 질문해야 좋은 답변을 얻는다"가 프롬프트 엔지니어링에 해당하는 개념인데, 잘 질문하기 위해서는 아래의 3가지 원칙을 따라 작성하는 습관이 필요하며 가장 기본적인 틀이기도 합니다.

역할 부여(Role) : 모델에게 특정 역할을 주어 답변을 유도하여 답변의 톤과 관점 제어
명확한 지시(Instruction) : 원하는 출력 형태와 조건을 구체적으로 전달
예시 제공(Few-shot) : 몇 가지 샘플을 포함하여 전달하여 원하는 답변 스타일을 학습하도록 유도

이제 Role - Instruction - Few-shot(이하 RIF)을 지키지 않고 단순하게 질문한 했을 경우와 RIF를 지켰을 경우 어떠한 답변의 차이가 있는지 살펴보도록 하겠습니다. 아래의 실험은 GPT에서 로그아웃 후 진행하였습니다.

RIF를 지키지 않고 단순하게 질문만 했을 경우 (GPT)

간단하게 질문만 한 경우입니다.

자바 ArrayList와 LinkedList를 비교해.

RIF를 지키지 않고 단순하게 질문만 했을 경우 (답변 1-1)

RIF를 지키지 않고 단순하게 질문만 했을 경우 (답변 1-2)

RIF를 지키지 않고 단순하게 질문만 했을 경우 (답변 1-3)

RIF를 지켜서 질문한 경우 (GPT)

만약 강사가 학생들에게 ArrayList와 LinkedList의 차이를 설명하기 위해 AI를 활용하여 내용을 정리하고자 한다면 아래와 같은 프롬프트를 작성할 수 있습니다.

[Role]
너는 자바를 처음 입문하는 학생들에게 강의를 하는 전문 강사야.  
개발 경력이 10년 이상인 시니어 풀스택 개발자이면서 강의 경력이 10년 이상인 강사로
초보자가 이해하기 쉽게 설명하는 데 능숙해.

[Instruction]
"ArrayList"와 "LinkedList"의 차이를 표 형식으로 설명하고
마지막에 어떤 상황에서 어떤 것을 선택하여 사용해야 하는지 간단히 정리해줘.  
- 설명은 초보 학생이 이해할 수 있는 간단한 언어로 작성하고
  필요한 경우 간단한 코드 예제나 비유를 포함해.  
- 표에는 최소 다음 항목을 포함하되 필요하다면 
  추가 항목(예: 삽입/삭제 성능, 메모리 사용량)을 포함해 
  - 메모리 구조  
  - 접근 속도  
  - 삽입/삭제 속도  
- 잘못된 내용을 전달하지 않도록 답변 작성 전 공식 문서(예: Oracle Java 문서) 또는 
  신뢰할 수 있는 자료를 참조하여 3번 검증해.  
- 답변은 한국어로 작성하고, 500~700단어 내로 유지해.  
- 실제 개발 경험에서 나온 사례나 비유를 활용하여 학생들이 개념을 쉽게 이해하도록 도와줘.

[Free-shot]
예시 출력은 아래와 같아.

| 비교항목       | ArrayList         | LinkedList        |
|----------------|-------------------|------------------|
| 메모리 구조    |        ...        |        ...        |
| 접근 속도      |        ...        |        ...        |
| 삽입/삭제 속도 |        ...        |        ...        |

위 예시를 참고하여 ArrayList와 LinkedList 비교를 진행해.

RIF를 지켜서 질문한 경우 (답변 2-1)

RIF를 지켜서 질문한 경우 (답변 2-2)

RIF를 지켜서 질문한 경우 (답변 2-3)

마무리

단순 질문을 했을 경우 기본적인 개념 설명은 간략하게 답변을 받았으나 깊이와 구조가 부족한 느낌이 강하며 RIF를 지켜서 질문했을 경우 조금 더 자세한 설명을 받았습니다.

ArrayList와 LinkedList의 경우 인터넷에 정보가 워낙 많다보니 큰 차이로 안보일 수 있지만, 이러한 프롬프트를 작성하는 능력을 키우다 보면 원하는 정보를 좀 더 자세히 얻고 특정 상황에 주어진 작업을 할 때 똑같은 AI를 활용하더라도 더 좋은 품질의 답변을 얻을 수 있습니다.

이번 포스팅에서 LLM을 활용할 때 가장 기본적이면서도 중요한 프롬프트 엔지니어링에 대해 간단히 알아보았는데, 프롬프트를 설계하는 방식에 따라 답변의 질과 활용도가 크게 달라질 수 있음을 알아야 합니다.

"AI에게 질문을 잘 하자 = 프롬프트 엔지니어링"은 크게 다르지 않지만 급격히 성장하는 AI의 흐름을 따라 활용 능력을 키우는 것은 중요하다고 생각합니다. AI를 활용할 때 어떠한 역할을 맡기고, 어떠한 형식의 답변을 원하며, 어떠한 예시 샘플을 주어 답변을 얻을것인지에 대해 고민하며 AI에게 질문한다면 같은 것을 사용하더라도 더 가치있는 답변을 얻을 수 있습니다.

이후 포스팅에서는 프롬프트 엔지니어링을 위한 세부 기법을 더 알아보도록 하겠습니다.

[LLM] 간단하게 보는 대규모 언어 모델(Large Language Model) 이란 무엇인가?

KoreaNirsa — Fri, 12 Sep 2025 18:19:05 +0900

[LLM] 간단하게 보는 대규모 언어 모델(Large Language Model) 이란 무엇인가?

대규모 언어 모델(Large Language Model, 이하 LLM)은 대량의 텍스트 데이터를 학습하여 사람처럼 언어를 이해하고 생성할 수 있는 AI 모델입니다. LLM은 간단하게 본다면 크게 사전 학습(pre-training), 미세 조정(fine-tuning), 추론(inference)으로 나뉘어 집니다.

LLM의 3단계 동작 원리

1. 사전 학습(pre-training)

방대한 양의 텍스트와 문서등 데이터를 학습하며 언어의 패턴과 구조를 이해하는 과정입니다. 데이터를 학습하며 다음에 올 단어를 예측하는 것을 반복하며, 대규모의 데이터를 확보 및 많은 자원과 시간이 필요한 단계로써 미세 조정을 하기 위한 필수 단계입니다.

2. 미세 조정(fine-tuning)

특정 작업(번역, 요약, 코드 작성 등)에 맞춘 모델을 최적화하는 과정으로써 특정 작업의 도메인에 대한 데이터셋으로 추가적인 학습을 하고 더 잘 맞게끔 조정하는 단계입니다.

이 단계에서 강화 학습(RLHF)을 진행되며 이 과정에서 사람이 좋아하는 스타일의 답변을 평가하고 안좋은 답변은 부정적인 보상, 좋은 답변은 긍정적인 보상을 주어 모델을 학습시켜 진행합니다.

Q: “강아지를 기르는 방법을 알려줘.”

A. 나쁜 스타일 (부정적인 보상)
 - 강아지는 Canis lupus familiaris로 분류되며, 수천 년간 인간과 공생해 왔다. 사료 급여, 훈련, 예방 접종 등 복잡한 요소가 포함된다...

B. 좋은 스타일 (긍정적인 보상)
 - 매일 밥 주기
 - 산책하기
 - 예방접종 챙기기

3. 추론(Inference)

사용자가 입력한 프롬프트를 기반으로 가장 적절한 단어를 순차적으로 생성하는 과정입니다. 사용자가 프롬프트를 입력하면 학습된 지식을 바탕으로 가장 적절한 단어를 하나씩 만들어내며 답변을 생성합니다.

추론 과정에서의 특징은 확률적 생성으로 인해 같은 질문을 여러 번 하더라도 매번 조금씩 다른 답변이 나올 수 있으며, temperature, top_p와 같은 하이퍼파라미터를 통해 답변이 더 창의적이거나 일관적인 답변을 만들어 다양성을 조절할 수 있습니다.

※ 하이퍼파라미터(Hyperparameter)란?
LLM이 답변을 생성할 때 출력되는 답변의 성격을 조절할 수 있는 설정 값을 말합니다. 즉. 사용자가 API를 요청할 때 직접 하이퍼파라미터를 지정하여 답변의 성격을 바꿔 원하는 결과를 얻어낼 수 있습니다.

자주 사용되는 대표적인 하이퍼파라미터로 temperature, top_p가 있으며 temperature는 높을수록 창의적인(다양한) 답변, 낮을수록 일관된 답변을 결정합니다. 또한 top_p는 LLM이 예측한 확률을 정렬하고 누적 확률이 P 이하인 토큰만 선택하는 방식으로써 temperature과 동일하게 높을수록 창의적인(다양한) 답변, 낮을수록 일관된 답변을 결정합니다.

요약

마지막으로 요약하자면 데이터를 학습하고(사전 학습), 특정 작업에 맞는 데이터셋을 추가로 학습하여 특정 작업에 더 잘 맞게끔 하며(미세 조정), 확률적으로 가장 적절한 단어를 순차적으로 생성(추론) 합니다. 일반적으로 많이 사용하는 GPT, Gemini, Claude 등이 LLM의 대표적인 모델 입니다.

LLM의 활용 분야와 한계

LLM을 기반으로 다양한 기술들을 활용하여 여러 가지의 분야에 활용하여 사용할 수 있습니다.

RAG : 사내 문서 검색 후 답변 생성 등
업무 자동화 : 이메일 작성, 보고서 요약, 회의록 작성 등
코드 생성/보조 : GitHub Copilot, Cursor 등
교육 : 맞춤형 튜터 등
챗봇 & 어시스턴트 : 고객센터, AI 비서 등

또한 현재 아래와 같이 LLM의 본질적인 한계가 존재합니다.

잘못된 정보(Hallucination): 존재하지 않는 사실을 그럴듯하게 생성하여 답변
비용 문제 : 대형 모델일수록 학습 과정에서 생기는 비용이 증가하며 이로 인해 API 비용도 자연스럽게 증가함
데이터 최신성 부족 : 학습 시점 이후의 정보는 알지 못함
투명성 부족 : 모델의 내부 추론 과정이 블랙박스

마지막 투명성 부족의 경우 수천억 개의 파라미터로 구성되어 사람이 직접 해석이 불가능하며, 동일한 입력에서 매번 결과가 조금 씩 달라집니다. 이로 인해 사용자는 최종적인 답변(결과)를 확인할 수 있지만 해당 답변이 어떠한 근거로 만들어졌는지 알 수 없기 때문에 투명성이 부족할 수 있으며 잘못된 정보(Hallucination)가 발생하더라도 원인을 추적하기가 어렵습니다.

[Kotlin] 람다(Lambda)와 고차 함수(Higher-Order Function) 예시

KoreaNirsa — Fri, 22 Aug 2025 13:09:47 +0900

※ 해당 코틀린 포스트들은 기본적으로 자바를 알고 있다는 가정하에 간단히 예제만 제공하여 설명됩니다.

람다(Lambda)와 고차 함수(Higher-Order Function) 예시

이번 포스팅에서는 코틀린 기준의 람다와 고차함수에 대해 정리합니다. 기본적인 개념은 람다는 이름없는 함수, 고차 함수는 매개변수 또는 반환 값이 함수인 것을 뜻합니다. 아래의 예시를 보며 람다와 고차 함수를 하나씩 확인하도록 하겠습니다.

1. 람다 예시

람다의 경우 이름 없는 함수로써 아래와 같이 표현될 수 있습니다. 아래의 코드를 확인해보면 square(5)를 호출하고 있는데, (Int) 부분이 매개변수의 타입을 뜻하며 -> Int는 반환 타입을 뜻합니다.

fun main() {
    // val 변수명: 매개변수타입 -> 반환타입 = { 매개변수명 -> 코드 }           
    val square: (Int) -> Int = { x -> x * x }
    println(square(5)) // 25
}

만약 매개변수가 여러개인 상황과 없는 상황을 보면 아래와 같이 활용이 가능합니다.

// 매개변수 2개, Int 두 개 받아 Int 반환
val sum: (Int, Int) -> Int = { a, b -> a + b }
println(sum(2, 3)) // 5

// 매개변수 없음, Unit 반환(출력만)
val greet: () -> Unit = { println("hi") }

또한 블록 안에 여러 줄의 코드가 들어갈 경우 반환할 변수(또는 값)를 마지막 줄에 작성하면 return을 명시하지 않고 반환됩니다.

// 블록 본문: 마지막 표현식이 반환값
val squareVerbose: (Int) -> Int = { x ->
    val r = x * x
    r   // 이 줄이 반환됨
}

2. 람다 + 고차함수 예시

첫번째로 아까 사용했던 sum을 활용하여 고차 함수를 작성하도록 하겠습니다. 람다는 이름 없는 함수였으며, 고차 함수는 매개변수로 함수를 받거나 반환을 함수로 하는 것이였습니다.

// 매개변수 2개, Int 두 개 받아 Int 반환
val sum: (Int, Int) -> Int = { a, b -> a + b }
println(sum(2, 3)) // 5

아래의 코드를 확인해 보면 람다로 작성된 sum을 인자로 넘겼으며, OperateTwoNumbers 메서드가 함수를 매개변수로 받으므로 이는 고차함수라고 볼 수 있습니다.

// 고차 함수: (Int, Int) -> Int 타입의 함수를 받아서 실행
//                              고차함수명: 매개변수타입 -> 반환값
fun operateTwoNumbers(a: Int, b: Int, op: (Int, Int) -> Int): Int {
    return op(a, b) // 전달받은 함수 호출
}

fun main() {
    val sum: (Int, Int) -> Int = { a, b -> a + b }
    println(operateTwoNumbers(2, 3, sum)) // 5
}

두번째로 위에서 사용했던 greet을 활용하여 고차 함수를 작성하도록 하겠습니다. 기존 작성했던 람다(greet)는 아래와 같습니다.

// 매개변수 없음, Unit 반환(출력만)
val greet: () -> Unit = { println("hi") }

고차함수는 마찬가지로 함수로 전달받아 구현부 { } 블록 내에서 호출하여 사용합니다.

// 고차 함수: () -> Unit 타입의 함수를 받아서 호출
//       고차함수명: 매개변수타입 -> 반환타입
fun runAction(action: () -> Unit) {
    println("Before action")
    action() // 전달받은 함수 호출
    println("After action")
}

fun main() {
    val greet: () -> Unit = { println("hi") }
    runAction(greet)
}

중간에 전달받은 함수가 실행되므로 action()이 호출되며 "hi"가 출력될 것 입니다. 전체적인 출력은 아래와 같습니다.

Before action
hi
After action

마지막으로 squareVerbose를 고차 함수로 작성하도록 하겠습니다. 기존 작성했던 람다(squareVerbose)는 아래와 같습니다.

// 블록 본문: 마지막 표현식이 반환값
val squareVerbose: (Int) -> Int = { x ->
    val r = x * x
    r   // 이 줄이 반환됨
}

고차 함수를 작성하면 아래와 같이 되는데 리스트(1, 2, 3, 4)를 첫번째 인자로 전달하고, 람다로 작성한 squareVerbose를 두번째 매개변수로 전달합니다.

고차 함수 applyAndPrintAll 내에서 전달받은 리스트를 하나씩 for문으로 꺼내고, 전달받은 함수에 꺼낸 값을 인자로 보내 실행합니다.

그렇다면 처음 for문이 돌 때는 1을 squareVerbose에 전달하여 val r = 1*1이 되어 반환 값은 1이며, 그 다음 for문이 돌 때는 2를 squareVerbose에 전달하여 var r = 2*2가 되어 반환 값은 4가 될 것입니다.

// 고차 함수: (Int) -> Int 타입을 받아서 여러 값에 적용
fun applyAndPrintAll(values: List<Int>, op: (Int) -> Int) {
    for (v in values) {
        println("Input: $v, Output: ${op(v)}")
    }
}

fun main() {
    val squareVerbose: (Int) -> Int = { x ->
        val r = x * x
        r   // 마지막 표현식이 반환값
    }
    applyAndPrintAll(listOf(1, 2, 3, 4), squareVerbose)
}

이렇게 1~4까지 for문이 모두 실행되었다면 출력 값은 아래와 같습니다.

Input: 1, Output: 1
Input: 2, Output: 4
Input: 3, Output: 9
Input: 4, Output: 16