주현 - AX | Backend/Frontend Developer

백엔드 개발자를 위한 RAG 설계: 청킹, 임베딩, 벡터 검색 쉽게 이해하기

RichLegend — Fri, 17 Jul 2026 12:34:51 +0900

백엔드 개발자를 위한 RAG 설계: 청킹, 임베딩, 벡터 검색 쉽게 이해하기RAG가 문서를 찾는 순서부터 청킹 크기, 임베딩 모델, HNSW 설정, 검색 품질 평가까지 실무에 필요한 내용만 쉽게 정리했습니다.

RAG는 LLM이 답변하기 전에 관련 문서를 찾아 주는 구조입니다. 사용자가 질문하면 사내 문서나 기술 문서에서 근거를 찾고, 그 내용을 LLM에 전달합니다. LLM은 전달받은 근거를 바탕으로 답변합니다.

처음에는 문서를 잘라 벡터 DB에 넣고 가까운 내용을 검색하면 됩니다. 하지만 실제 서비스에서는 다른 문제가 생깁니다. 표현만 조금 바꿔도 검색 결과가 달라지고, 제품 코드나 오류 번호를 놓치기도 합니다. 수정 전 문서가 계속 검색되거나 권한이 없는 문서가 결과에 포함될 수도 있습니다.

벡터 DB부터 고르기보다 검색 결과를 어떻게 평가할지 먼저 정해야 합니다.

청킹 크기나 임베딩 모델, HNSW 설정은 문서와 질문에 따라 결과가 달라집니다. 다른 서비스에서 잘 동작한 설정도 우리 데이터에서는 같은 결과가 나오지 않을 수 있습니다. 이 글에서는 실제 질문으로 검색 품질을 확인하고, 그 결과에 맞춰 설정을 조정하는 순서를 설명합니다.

먼저 알아둘 용어

청크: 검색하기 좋게 나눈 문서 조각
청킹: 문서를 청크로 나누는 작업
임베딩: 문장이나 문서를 숫자 배열로 바꾸는 작업
벡터 검색: 숫자로 바꾼 문장 사이의 거리를 계산해 의미가 가까운 내용을 찾는 검색
BM25: 제품 코드나 오류 번호처럼 정확한 단어를 잘 찾는 검색
재정렬: 검색된 후보를 질문과 다시 비교해 순서를 바꾸는 작업
Recall@k: 관련 문서가 상위 k개 검색 결과에 포함된 비율
색인: 문서를 빠르게 검색할 수 있도록 정리해 저장한 구조
근사 검색: 모든 벡터를 비교하지 않고 가까울 가능성이 높은 벡터만 빠르게 찾는 검색

RAG는 두 단계로 나누면 이해하기 쉽습니다

RAG는 문서를 미리 저장하는 단계와 사용자의 질문을 처리하는 단계로 나눌 수 있습니다.

문서를 저장할 때

PDF, 웹 문서, 코드 같은 원문을 가져옵니다.
제목과 문단 구조를 살려 문서를 나눕니다.
각 청크를 임베딩합니다.
벡터와 문서 정보를 검색 시스템에 저장합니다.

질문을 받을 때

사용자 질문과 접근 권한을 확인합니다.
벡터 검색과 BM25로 관련 문서를 찾습니다.
필요하면 검색 결과를 재정렬합니다.
상위 청크를 LLM에 전달합니다.
답변과 출처를 사용자에게 보여 줍니다.

문서 저장 단계와 질문 처리 단계를 분리하면 변경 작업이 쉬워집니다. 임베딩 모델을 바꿀 때 원문을 다시 수집할 필요가 없습니다. 문서가 수정됐을 때는 바뀐 문서만 다시 청킹하고 색인할 수 있습니다.

청크에는 아래 정보를 함께 저장하는 편이 좋습니다.

원문 ID와 청크 ID
문서 버전 또는 수정 시각
제목과 소제목 위치
출처 URL
임베딩 모델과 버전
사용자나 부서의 접근 권한

권한은 답변을 만든 뒤 확인하면 늦습니다. 검색 단계에서 권한이 없는 문서를 제외해야 로그와 재정렬 요청에도 민감한 내용이 들어가지 않습니다.

청킹은 문서의 의미를 지키는 작업입니다

청크가 너무 짧으면 질문에 답할 정보가 부족합니다. 너무 길면 서로 다른 주제가 한 청크에 섞여 검색 정확도가 떨어지고 LLM 비용도 늘어납니다.

예를 들어 이 기간에는 환불이 불가능합니다라는 문장만 저장하면 어떤 상품과 기간을 말하는지 알 수 없습니다. 표의 한 행만 저장하면 열 제목이 사라집니다. 코드도 메서드 본문만 잘라 놓으면 클래스 정보를 놓칠 수 있습니다.

문서 종류에 맞춰 나누는 것이 먼저입니다.

일반 문서: 제목, 문단, 목록을 가능한 한 유지합니다.
API 문서: 엔드포인트별 요청과 응답 예제를 함께 둡니다.
코드: 함수나 클래스 단위로 나눕니다.
정책 문서: 조항 번호와 적용 대상을 함께 저장합니다.
표: 제목과 열 이름이 데이터와 함께 검색되도록 만듭니다.

Azure AI Search는 512토큰과 25% 겹침을 초기 설정값으로 제안합니다. 모든 문서에 그대로 적용할 값은 아니므로 문서 종류별로 비교해야 합니다.

첫 실험은 아래 범위에서 시작할 수 있습니다.

짧은 FAQ와 오류 메시지: 150에서 350토큰
일반 기술 문서와 업무 문서: 400에서 800토큰
정책과 매뉴얼: 조항이나 절 단위로 나눈 뒤 최대 길이 제한
코드: 함수나 클래스 단위로 나누고 상위 클래스 이름을 함께 저장

청크를 겹치면 문장이 경계에서 잘리는 문제를 줄일 수 있습니다. 하지만 겹침이 많으면 같은 문장이 여러 번 검색됩니다. 저장 공간과 검색 비용도 늘어납니다. 먼저 문단 경계를 지키고 제목 정보를 붙인 뒤, 정보가 계속 잘릴 때만 겹침을 늘리는 편이 낫습니다.

Anthropic의 Contextual Retrieval은 각 청크에 문서 제목과 섹션 정보를 짧게 붙이는 방식입니다. Anthropic이 공개한 내부 실험에서는 검색 실패가 49% 줄었고 재정렬을 함께 사용했을 때 67% 줄었습니다. 공급사 내부 데이터로 측정한 결과이므로 같은 수치가 나온다고 볼 수는 없습니다. 다만 제목과 상위 문맥을 청크에 추가하는 방법은 직접 시험해 볼 만합니다.

임베딩 모델은 실제 질문으로 비교합니다

임베딩 모델은 문장을 숫자 좌표로 바꿉니다. 의미가 비슷한 문장은 가까운 위치에 놓이도록 학습됩니다. 그래서 표현이 달라도 의미가 비슷한 문서를 찾을 수 있습니다.

리더보드 점수만으로 모델을 고르기는 어렵습니다. MTEB 연구에서도 모든 작업에 가장 좋은 단일 모델은 없었습니다. 한국어 문장, 영문 API 이름, 상품 코드가 섞인 데이터는 일반 영어 문서와 검색 조건이 다릅니다.

관리형 API를 사용하면 모델 서버를 직접 운영하지 않아도 됩니다.

OpenAI text-embedding-3-small: 기본 1536차원
OpenAI text-embedding-3-large: 기본 3072차원, 차원 축소 지원
Gemini Embedding: 기본 3072차원, 768과 1536차원도 권장
Cohere embed-v4.0: 텍스트와 이미지가 섞인 문서 지원
Voyage 4: 문서와 질문의 입력 유형을 구분하고 여러 차원 지원

외부 전송이 어려운 문서라면 직접 운영하는 모델도 검토할 수 있습니다. BGE-M3는 벡터 검색과 키워드 검색을 함께 지원하며 100개가 넘는 언어를 다룬다고 공개되어 있습니다. 다만 GPU와 CPU 비용, 모델 서버 운영, 장애 대응까지 직접 맡아야 합니다.

모델은 아래 질문으로 비교합니다.

띄어쓰기나 맞춤법이 틀린 한국어 질문
한국어와 영문 API 경로가 섞인 질문
상품 코드, 버전, 오류 번호를 찾는 질문
사내 약어와 정식 명칭을 섞은 질문
답이 없거나 접근 권한이 없는 질문

같은 문서와 질문으로 Recall@k, 검색 시간, 색인 크기, 비용을 비교하면 됩니다. 모델마다 문장을 숫자로 바꾸는 방식이 다르므로 임베딩 모델을 바꾸면 대부분 전체 문서를 다시 임베딩해야 합니다.

벡터 검색과 BM25를 함께 사용합니다

벡터 검색은 로그인이 안 돼요와 인증 실패 해결 방법처럼 표현이 달라도 의미가 비슷한 문장을 찾는 데 강합니다. 반면 ERR-1024, 상품 코드, API 경로처럼 글자가 정확히 일치해야 하는 검색에는 약할 수 있습니다.

BM25는 정확한 단어를 찾는 데 강합니다. 두 검색을 함께 사용하면 의미 검색과 키워드 검색의 장점을 모두 활용할 수 있습니다.

같은 질문을 벡터 검색과 BM25에 보냅니다.
두 검색에서 후보 문서를 가져옵니다.
각 검색 결과의 순위를 기준으로 합치는 RRF를 적용합니다.
재정렬 모델이 질문과 후보를 다시 읽고 순서를 바꿉니다.
상위 문서만 LLM에 전달합니다.

처음에는 30개에서 100개 정도를 찾은 뒤 5개에서 10개로 줄이는 구성을 시험할 수 있습니다. 후보가 많을수록 재정렬 비용과 응답 시간이 늘어나므로 실제 질문으로 조정해야 합니다.

검색 필터는 보안과 품질에 모두 필요합니다

문서에는 부서, 사용자, 문서 종류, 언어, 공개 범위 같은 정보가 있습니다. 이 값을 검색 조건으로 사용해야 합니다.

필터가 없으면 권한이 없는 문서까지 검색될 수 있습니다. 반대로 필터가 너무 강하거나 문서 정보가 빠져 있으면 필요한 문서를 놓칩니다. 검색에 사용한 필터와 제외된 문서 수를 로그에 남기면 원인을 찾기 쉽습니다.

Qdrant는 문서 속성을 빠르게 거르는 payload index를 데이터 적재 전에 만들도록 권장합니다. pgvector는 필터 때문에 검색 결과가 부족할 때 검색 범위를 단계적으로 넓히는 iterative scan 옵션을 제공합니다.

HNSW와 IVFFlat의 차이

벡터가 많아지면 모든 벡터를 하나씩 비교하기 어렵습니다. HNSW와 IVFFlat은 가까울 가능성이 높은 벡터만 빠르게 확인하는 근사 검색 인덱스입니다.

근사 검색을 적용하기 전에는 데이터가 적을 때 정확 검색으로 기준을 만듭니다. 정확 검색 결과와 비교해야 HNSW나 IVFFlat이 관련 문서를 얼마나 놓치는지 알 수 있습니다.

HNSW

HNSW는 벡터 사이의 연결 그래프를 만듭니다. 검색 속도가 빠르고 관련 문서를 놓치는 비율도 낮은 편입니다. 데이터가 계속 추가되는 서비스에서 많이 사용하지만 인덱스를 만드는 시간이 길고 메모리를 더 사용합니다.

m: 각 벡터가 연결되는 수
ef_construction: 인덱스를 만들 때 확인할 후보 수
ef_search: 검색할 때 확인할 후보 수

ef_search를 높이면 관련 문서를 찾을 가능성이 커지지만 검색 시간도 늘어납니다. Qdrant의 hnsw_ef도 같은 방식으로 조정합니다.

IVFFlat

IVFFlat은 벡터를 여러 묶음으로 나눈 뒤 질문과 가까운 묶음부터 검색합니다. HNSW보다 인덱스를 빠르게 만들 수 있고 메모리 부담도 낮을 수 있습니다. 다만 데이터 분포를 먼저 학습해야 하므로 데이터가 쌓인 뒤 만드는 편이 좋습니다.

lists: 벡터를 나눌 묶음 수
probes: 검색할 때 확인할 묶음 수

probes를 높이면 더 많은 묶음을 확인하므로 재현율과 검색 시간이 함께 늘어납니다.

인덱스를 비교할 때는 벡터 수, 검색량, 삽입량, 메모리, 필터 비율, 허용 응답 시간을 함께 확인합니다. 데이터가 자주 추가된다면 HNSW가 편할 수 있습니다. 메모리가 부족하고 데이터를 한 번에 적재한다면 IVFFlat도 좋은 선택입니다. 최종 선택은 같은 평가 질문으로 비교하여 정합니다.

검색과 답변을 따로 평가합니다

답변이 틀렸을 때 LLM만 바꾸면 원인을 찾기 어렵습니다. 먼저 관련 문서가 검색됐는지 확인해야 합니다.

검색 단계에서는 아래 값을 봅니다.

Recall@k: 관련 문서가 상위 k개 안에 들어왔는지
Precision@k: 검색된 문서 중 실제 관련 문서의 비율
MRR: 첫 번째 관련 문서가 얼마나 앞에 있는지
검색과 재정렬에 걸린 시간
필터 때문에 결과가 0개가 된 비율

답변 단계에서는 아래 항목을 확인합니다.

답변이 검색된 문서에 근거했는지
질문에 필요한 내용을 직접 답했는지
표시한 출처가 실제 근거와 일치하는지
근거가 없을 때 답변을 거절하는지
토큰 사용량과 비용

Ragas는 검색 문맥의 정확성(Context Precision), 누락 여부(Context Recall), 답변 관련성(Response Relevancy), 근거 충실도(Faithfulness)를 평가할 수 있습니다. 자동 평가는 반복 테스트에 유용하지만 중요한 질문과 실패 사례는 사람이 함께 확인해야 합니다.

운영 로그에는 원본 질문, 적용한 권한 필터, 검색 후보 ID, 재정렬 순위, LLM에 전달한 청크 ID, 문서 버전, 단계별 처리 시간을 남깁니다. 원문 전체나 개인정보를 무조건 저장하지는 않습니다. 문제를 추적하는 데 필요한 ID와 마스킹된 정보만 보존합니다.

처음 구현할 때는 이 순서로 진행합니다

실제 질문과 관련 문서를 묶어 평가용 질문을 만듭니다.
문서의 제목과 문단을 살려 청킹합니다.
데이터가 적을 때 정확 벡터 검색으로 첫 결과를 확인합니다.
임베딩 모델 두세 개를 같은 질문으로 비교합니다.
코드나 고유명사가 많다면 BM25를 추가합니다.
관련 문서는 찾았지만 순위가 낮을 때 재정렬을 추가합니다.
검색 시간이 길어지면 HNSW와 IVFFlat을 비교합니다.
권한 필터가 있는 상태에서 검색 결과가 줄어드는지 확인합니다.
운영에서 실패한 질문을 평가 목록에 계속 추가합니다.

새 기능은 문제가 생긴 단계에 추가해야 합니다. 관련 문서가 청크로 만들어지지 않았다면 재정렬 모델을 바꿔도 해결되지 않습니다. 관련 문서는 검색됐지만 순위가 낮다면 청킹 전체를 바꾸기보다 재정렬부터 시험할 수 있습니다.

자주 묻는 질문

청크는 몇 토큰이 좋은가요?

문서마다 다릅니다. 일반 문서는 400에서 800토큰을 먼저 비교할 수 있습니다. FAQ는 더 짧게 나누고 정책 문서는 조항 단위를 우선합니다. 최소 두세 가지 크기를 같은 질문으로 비교하세요.

처음부터 Semantic Chunking을 써야 하나요?

필수는 아닙니다. 먼저 제목과 문단을 살린 청킹으로 시작합니다. 관련 정보가 청크 경계에서 계속 잘릴 때 Semantic Chunking과 비교해도 늦지 않습니다.

PostgreSQL과 pgvector로 시작해도 되나요?

이미 PostgreSQL을 운영하고 있고 벡터 수와 검색량을 감당할 수 있다면 pgvector로 시작해도 됩니다. 벡터 규모가 매우 크거나 복잡한 혼합 검색이 필요해질 때 전용 검색 시스템을 비교할 수 있습니다.

임베딩 모델만 바꾸고 기존 벡터를 유지할 수 있나요?

대부분 어렵습니다. 모델마다 벡터 공간이 다르기 때문에 문서와 질문을 새 모델로 다시 임베딩해야 합니다.

답변이 틀리면 LLM부터 바꿔야 하나요?

관련 문서가 검색됐는지 먼저 확인합니다. 관련 문서가 없다면 청킹이나 검색 문제입니다. 관련 문서가 있는데 답변이 틀렸다면 LLM에 전달한 문맥과 프롬프트를 확인합니다.

정리

RAG는 문서를 검색하고 그 근거로 답변하는 백엔드 시스템입니다. 청킹은 문서의 의미가 끊기지 않도록 나눕니다. 임베딩 모델은 실제 질문으로 비교합니다. 벡터 검색과 BM25를 함께 사용하면 의미가 비슷한 문장과 정확한 코드 검색을 모두 처리하기 좋습니다.

처음부터 복잡한 기능을 모두 넣을 필요는 없습니다. 평가용 질문을 먼저 만들고 청킹, 검색, 재정렬, 인덱스를 순서대로 추가하면 어떤 변경이 도움이 됐는지 확인하기 쉽습니다.

태그: RAG 아키텍처, 백엔드 개발자, Chunking 전략, 임베딩 모델 비교, Vector DB, HNSW, IVFFlat, pgvector, 하이브리드 검색, Reranking, LLM, 생성형 AI, AI Agent

GPT-5.6이 나왔다. GPT-5.6 Sol·Terra·Luna, 어떤 작업에 써야 할까

RichLegend — Fri, 10 Jul 2026 13:48:47 +0900

GPT-5.6이 나왔다. 벤치마크 성능표보다 중요한 건 따로 있다

새 모델이 얼마나 똑똑한지보다, 실제 작업에서 몇 번이나 다시 설명해야 하는지가 더 궁금하다.

GPT-5.6가 정식으로 공개됐다. 플래그십 모델인 Sol, 성능과 비용을 절충한 Terra, 저렴하게 쓸 수 있는 Luna까지 세 종류다. 코딩과 과학, 보안 분야의 점수도 올랐고, 여러 에이전트를 동시에 움직이는 ultra 모드도 추가됐다.

발표 자료만 보면 확인할 것이 많다. 그런데 AI 코딩 도구를 실제 업무에 붙여 쓰는 입장에서 궁금한 건 조금 다르다. 요구사항을 한 번에 얼마나 잘 알아듣는지, 수정하다가 멀쩡한 코드를 건드리지는 않는지, 끝났다고 했을 때 테스트까지 제대로 통과했는지. 이런 부분이 좋아졌다면 점수 몇 점이 오른 것보다 훨씬 반갑다.

이번 발표에서 눈에 들어온 건 토큰 효율이었다

GPT-5.6의 메시지는 같은 수준의 결과를 더 적은 토큰으로 만들고, 작업에 따라 모델을 나눠 비용을 낮추겠다는 쪽에 가깝다.

Sol은 설계나 복잡한 디버깅처럼 판단이 많이 필요한 작업에 어울린다.
Terra는 일반적인 기능 개발이나 문서 작업처럼 자주 하는 일에 맞춰져 있다.
Luna는 분류, 형식 변환, 전처리처럼 결과를 바로 확인하기 쉬운 작업에 부담이 적다.

API 가격은 100만 토큰 기준으로 Sol이 입력 5달러, 출력 30달러다. Terra는 2.5달러와 15달러, Luna는 1달러와 6달러다.

가격만 보면 Luna부터 쓰는 게 당연해 보인다. 하지만 모델이 놓친 내용을 사람이 계속 고쳐야 한다면 계산이 달라진다. 토큰 비용은 줄어도 작업 시간은 늘 수 있다. 반대로 중요한 작업에 Sol을 쓰고 수정 횟수를 줄일 수 있다면 비싼 모델이 오히려 나은 선택일 수 있다.

개발자가 체감하는 성능은 다른 곳에서 드러난다

온라인 반응 중에 재미있는 표현이 하나 있었다. 모델 성능을 “Codex에게 욕한 횟수”로 평가했다는 이야기다. GPT-5.5를 쓸 때보다 GPT-5.6 Sol을 쓸 때 그 횟수가 줄었다고 했다.

농담이지만 무슨 뜻인지는 바로 이해된다. AI 코딩을 하다 보면 틀린 답보다 애매하게 맞는 답이 더 피곤할 때가 있다. 요구사항 다섯 개 중 네 개만 처리하거나, 한 곳을 고치면서 다른 곳을 깨뜨리거나, 테스트하지 않은 코드를 완성됐다고 내놓는 경우다.

모델이 좋아졌는지는 결국 다시 설명한 횟수, 되돌린 코드, 직접 고친 시간에서 드러난다.

벤치마크가 필요 없다는 이야기는 아니다. 어떤 작업에서 강한지 빠르게 파악하려면 점수가 필요하다. 다만 내 코드베이스에서 잘하는지는 직접 확인해야 한다. 프로젝트 구조와 사용 언어, 프롬프트 작성 방식이 사람마다 다르기 때문이다.

프롬프트를 짧게 쓰라는 말은 조금 조심해서 들어야 한다

GPT-5.6은 사용자의 의도와 기대 수준을 이전보다 잘 파악한다고 한다. 긴 시스템 프롬프트를 줄였더니 내부 평가 점수는 10~~15% 좋아지고, 전체 토큰은 41~~66%, 비용은 33~67% 줄었다는 내용도 공개됐다.

그렇다고 모든 설명을 지우면 안 된다. 프롬프트가 짧아져도 수정 범위, 성공 조건, 승인 없이 하면 안 되는 일은 남겨야 한다. 모델이 알아서 채워도 되는 설명과 사람이 직접 정해야 하는 기준은 다르다.

예를 들어 “짧게 답해줘”라고 쓰는 것보다 “수정한 파일, 변경 이유, 테스트 결과만 알려줘”라고 쓰는 편이 낫다. 답변 길이만 줄이는 게 아니라 무엇을 받아야 하는지 정해 주기 때문이다.

Codex와 Claude Code, 하나만 고를 필요는 없다

새 모델이 나올 때마다 Codex와 Claude Code 중 무엇이 더 좋은지 묻게 된다. 여기에 하나의 정답은 없다. 모델의 코딩 실력만 비교해서 끝나는 문제가 아니기 때문이다.

도구가 안정적으로 동작하는지, 사용량을 얼마나 주는지, 원격으로 작업을 확인할 수 있는지, 긴 세션에서 앞의 맥락을 얼마나 잘 이어가는지도 중요하다. 같은 모델을 써도 프로젝트에 따라 체감이 달라진다.

예산이 허용한다면 둘을 경쟁시키는 방법도 괜찮다. 같은 요구사항으로 설계를 각각 받아 보거나, 한쪽이 작성한 코드를 다른 쪽에 검토하게 하면 각 모델의 장단점이 빨리 드러난다.

새 모델은 같은 작업으로 비교해 보면 된다

GPT-5.6를 써 볼 생각이라면 평소 자주 하는 작업 하나를 정해 두는 게 좋다. 새 기능 하나, 실제 버그 하나, 오래된 코드의 작은 리팩터링 정도면 충분하다.

첫 결과에서 요구사항을 몇 개나 놓쳤는지
수정 지시 뒤에 기존 동작을 깨뜨렸는지
테스트를 직접 실행하고 결과를 확인했는지
사람이 다시 설명하고 고치는 데 몇 분이 들었는지
한 작업을 끝내는 데 실제로 얼마를 썼는지

며칠만 기록해도 Sol을 써야 할 작업과 Terra로 충분한 작업, Luna에 맡겨도 되는 작업이 나뉜다. 모델 이름보다 내 작업에서 나온 기록이 훨씬 믿을 만하다.

GPT-5.6에서 기대하는 건 화려한 답이 아니다

AI 코딩 도구에 바라는 것은 점점 단순해지고 있다. 말을 길게 잘하는 것보다 앞에서 정한 조건을 잊지 않았으면 한다. 수정한 뒤에는 테스트를 돌리고, 문제가 생기면 원인을 찾아 끝까지 고쳤으면 한다.

GPT-5.6가 이런 기본적인 답답함을 줄여 준다면 충분히 좋은 업그레이드다. 성능표는 그다음에 봐도 늦지 않다.

태그: GPT-5.6, Codex, Claude Code, AI 코딩, OpenAI, LLM, 프롬프트, 개발 생산성, AI 에이전트

참고 자료
https://news.hada.io/topic?id=31275
https://openai.com/index/gpt-5-6/

Codex GPT-5.6 Sol [collaboration.spawn_agent] 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

RichLegend — Fri, 10 Jul 2026 10:58:20 +0900

Codex GPT-5.6 Sol `collaboration.spawn_agent` 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

GPT-5.6 Sol에서 일반 질문까지 실패하는 원인과 LazyCodex 업데이트, config.toml 우회 설정, CLI 검증 순서를 정리했습니다.

Codex에서 GPT-5.6 Sol을 선택한 뒤 평범한 인사나 질문을 입력했는데 아래 오류만 나오고 대화가 시작되지 않는 경우가 있습니다.

Invalid Value: 'tools'. Function 'collaboration.spawn_agent' is reserved for use by this model and must match the configured schema.

오류 문구에 spawn_agent가 들어가 있으니 멀티 에이전트 기능부터 꺼야 할 것처럼 보입니다. 하지만 영향을 받는 환경에서는 멀티 에이전트를 포기하지 않고도 문제를 해결할 수 있습니다.

2026년 7월 10일 현재 가장 먼저 확인할 것은 LazyCodex 또는 OMO의 버전입니다. LazyCodex v4.16.2에는 GPT-5.6 계열에서 문제가 될 수 있는 관리 설정을 자동으로 정리하는 수정이 포함됐습니다. 업데이트한 뒤에도 같은 오류가 정확히 반복될 때만 tool_namespace 우회 설정을 적용하는 순서가 안전합니다.

바쁜 분을 위한 해결 순서

오류 문구가 위 내용과 정확히 같은지 봅니다.
LazyCodex 또는 OMO를 사용한다면 v4.16.2 이상으로 업데이트합니다.
기존 대화가 아닌 새 작업에서 GPT-5.6 Sol을 다시 실행합니다.
오류가 남으면 config.toml을 백업하고 tool_namespace = "agents"를 추가합니다.
multi_agent = false나 multi_agent_v2.enabled = true부터 적용하지 않습니다.
Codex Desktop과 터미널의 Codex CLI는 따로 확인합니다.

일반 질문까지 막히는 이유

OpenAI Codex 이슈 #31864에 올라온 코드 분석과 A/B 테스트는 도구 이름과 스키마의 충돌을 원인으로 지목합니다.

GPT-5.6 Sol에는 collaboration.spawn_agent라는 예약 도구가 있습니다. 그런데 영향을 받는 Codex 런타임도 MultiAgentV2의 spawn_agent를 같은 collaboration 네임스페이스에 등록합니다. 이름은 같지만 스키마가 일치하지 않으면 서버가 요청을 거부합니다.

Codex는 질문만 보내지 않습니다. 모델이 필요할 때 쓸 수 있도록 도구 정의도 요청에 함께 넣습니다. 서버는 모델이 답변을 만들기 전에 이 정의부터 검사합니다. 서브 에이전트를 요청하지 않은 평범한 질문까지 실패하는 이유가 여기에 있습니다.

tool_namespace = "agents"를 설정하면 도구 이름이 collaboration.spawn_agent에서 agents.spawn_agent로 바뀝니다. 예약된 이름과 겹치지 않도록 이름표만 바꾸는 셈입니다. 멀티 에이전트를 삭제하거나 끄는 설정은 아닙니다.

다만 2026년 7월 10일 확인 시점에도 OpenAI Codex 이슈 #31864는 열려 있습니다. 이 글에서 설명하는 원인은 공개 이슈의 재현 결과를 토대로 한 유력한 분석이며, OpenAI 유지관리자가 확정한 영구 수정 공지는 아닙니다.

가장 먼저 LazyCodex를 업데이트합니다

LazyCodex 이슈 #118에는 v4.16.0이 세션 시작 때 넣던 [features.multi_agent_v2] enabled = false 관리 설정이 GPT-5.6 Sol과 충돌할 수 있다는 내용이 올라왔습니다.

이 문제는 LazyCodex v4.16.2에서 수정됐습니다. 업데이트된 가드는 GPT-5.6 계열에서 문제가 될 수 있는 관리 블록의 enabled = false, hide_spawn_agent_metadata = false, agents.max_threads를 정리합니다. 이후 Codex가 모델 정보에 맞춰 멀티 에이전트 버전을 선택하도록 둡니다.

설치 방식에 맞는 명령 하나를 사용합니다.

codex plugin marketplace upgrade sisyphuslabs

또는 최신 설치 프로그램을 실행합니다.

npx lazycodex-ai@latest install

LazyCodex 자동 업데이트에는 최대 24시간 간격이 있을 수 있습니다. 오류가 이미 발생했다면 수동 업데이트가 빠릅니다. 업데이트가 끝나면 새 작업을 만들고 GPT-5.6 Sol로 짧은 메시지를 보내 봅니다.

업데이트 후에도 같은 오류가 남는다면

새 작업에서도 정확히 같은 오류가 반복될 때만 설정 파일을 손봅니다. 수정 전 백업은 꼭 남겨 두세요.

사용자 전역 설정 파일의 기본 위치는 다음과 같습니다.

Windows: %USERPROFILE%\.codex\config.toml
macOS/Linux: ~/.codex/config.toml

CODEX_HOME을 별도로 지정했다면 실제 파일은 다른 경로에 있을 수 있습니다.

Windows PowerShell에서 백업

$codexHome = if ($env:CODEX_HOME) { $env:CODEX_HOME } else { "$env:USERPROFILE\.codex" }
$path = Join-Path $codexHome "config.toml"
Copy-Item -LiteralPath $path -Destination "$path.bak.$(Get-Date -Format 'yyyyMMddHHmmss')"
notepad $path

macOS/Linux에서 백업

cp ~/.codex/config.toml ~/.codex/config.toml.bak
nano ~/.codex/config.toml

`tool_namespace` 한 줄 추가하기

설정 파일에 [features.multi_agent_v2] 블록이 없다면 다음 내용을 한 번만 추가합니다.

[features.multi_agent_v2]
tool_namespace = "agents"

같은 블록이 이미 있다면 새 블록을 만들지 말고 기존 블록 안에 아래 한 줄만 넣습니다.

tool_namespace = "agents"

OpenAI 공식 Configuration Reference가 연결하는 최신 config-schema.json에도 features.multi_agent_v2.tool_namespace 항목이 정의돼 있습니다. 다만 Codex 버전이나 모델 제공 경로가 다르면 결과도 달라질 수 있으므로 백업 후 적용하는 편이 안전합니다.

TOML 중복 선언은 피해야 합니다

다음처럼 [features] 아래에 multi_agent_v2가 불리언 값으로 들어 있는 상태에서 [features.multi_agent_v2] 테이블을 덧붙이면 잘못된 TOML이 됩니다.

[features]
multi_agent_v2 = false

multi_agent_v2를 값과 테이블로 동시에 선언할 수 없기 때문입니다. 오래된 LazyCodex가 만든 관리 설정이라면 먼저 v4.16.2 이상으로 업데이트하여 자동 정리를 실행하는 편이 낫습니다. 직접 넣은 설정이라면 백업한 뒤 기존 불리언 선언을 제거하고 테이블 형식 하나만 남깁니다.

[features.multi_agent_v2]
tool_namespace = "agents"

[features.multi_agent_v2] 블록 자체가 두 번 들어가 있어도 파싱 오류가 날 수 있습니다. 파일 맨 아래에 같은 블록을 통째로 붙이지 않았는지 확인하세요.

설정 저장 후에는 새 작업에서 확인하세요

기존 대화는 시작할 때 정해진 런타임이나 도구 구성을 유지할 수 있습니다. 설정이 반영됐는지는 새 작업을 기준으로 판단하는 편이 낫습니다.

새 Codex 작업을 만듭니다.
GPT-5.6 Sol을 선택합니다.
간단한 메시지를 보냅니다.
오류가 계속되면 Codex Desktop 창을 모두 닫고 다시 실행합니다.
새 작업에서 한 번 더 확인합니다.

앱을 닫았는데도 달라지지 않을 때만 백그라운드 프로세스가 남아 있는지 봅니다. 처음부터 모든 프로세스를 강제 종료할 필요는 없습니다.

CLI에서는 설정을 바꾸기 전에 시험할 수 있습니다

Codex CLI를 사용한다면 네임스페이스 변경을 일회성 옵션으로 먼저 확인해 볼 수 있습니다.

codex exec -m gpt-5.6-sol -c 'features.multi_agent_v2.tool_namespace="agents"' 'Reply exactly OK.'

정상 처리되면 결과에 OK가 나옵니다.

여기서 Unknown model gpt-5.6-sol이 표시된다면 이번 스키마 충돌과는 다른 문제입니다. CLI 버전, 계정별 모델 접근 권한, 모델 캐시, 모델 제공 경로를 따로 살펴봐야 합니다.

codex --version

Windows에서는 실제 실행되는 CLI 위치도 확인합니다.

where.exe codex

Codex Desktop에 포함된 런타임과 npm으로 설치한 Codex CLI의 버전은 다를 수 있습니다. CLI에서 성공했다고 Desktop까지 해결됐다고 단정하지 말고 두 환경을 나눠서 확인하세요.

그래도 안 될 때 보는 항목

[features.multi_agent_v2] 블록이 두 번 이상 있는지
[features]의 multi_agent_v2 = false와 [features.multi_agent_v2] 테이블이 함께 있는지
CODEX_HOME이 기본 경로와 다른 설정 파일을 가리키는지
선택한 프로필의 설정이 전역 설정을 덮어쓰는지
신뢰된 프로젝트의 .codex/config.toml에 다른 값이 있는지
LazyCodex 또는 OMO 업데이트 뒤 설정 파일이 다시 바뀌었는지
Desktop과 CLI 가운데 어느 쪽에서만 문제가 생기는지
프록시나 비공식 모델 제공자의 인증 오류, 모델 목록 누락, Unknown model이 섞여 있지 않은지

문자열 검색으로 tool_namespace = "agents"가 보인다고 해서 현재 작업에 그 설정이 적용됐다고 단정할 수는 없습니다. Codex가 설정 파싱 오류 없이 실행되고, 새 작업에서 해당 오류가 사라졌는지가 최종 기준입니다.

재부팅과 재설치부터 할 필요는 없습니다

컴퓨터를 재부팅해도 디스크에 저장된 설정은 그대로입니다. Codex를 삭제하고 다시 설치해도 ~/.codex/config.toml이 남으면 같은 문제가 이어질 수 있습니다.

multi_agent = false로 바꾸면 사용하려던 멀티 에이전트 기능까지 포기하게 됩니다. 영향을 받는 런타임에서 이 설정 하나로 충돌이 사라진다는 보장도 없습니다.

features.multi_agent_v2.enabled = true를 무조건 강제하는 것도 피하세요. 설정 조합에 따라 agents.max_threads와 충돌할 수 있습니다. OMO 훅 전체를 끄는 방법 역시 정확한 원인을 확인하기 전에는 범위가 너무 큽니다.

같은 오류가 반복된다면 LazyCodex 업데이트 → 새 작업 확인 → 설정 백업 → 네임스페이스 변경 순서로 접근하는 것이 낫습니다.

아래 오류가 GPT-5.6 Sol에서 모든 질문마다 반복된다면 프롬프트부터 고칠 문제는 아닐 가능성이 큽니다.

Invalid Value: 'tools'. Function 'collaboration.spawn_agent' is reserved for use by this model and must match the configured schema.

LazyCodex 또는 OMO 사용자라면 v4.16.2 이상으로 업데이트하고 새 작업에서 다시 확인하세요. 오류가 그대로 남을 때만 config.toml을 백업하고 다음 설정을 적용합니다.

[features.multi_agent_v2]
tool_namespace = "agents"

이 한 줄은 멀티 에이전트를 끄지 않습니다. 예약된 collaboration 이름과 겹치지 않도록 도구 네임스페이스만 바꿉니다. 업데이트부터 확인하면 불필요한 재설치나 기능 비활성화를 피할 수 있습니다.

참고 자료

원문 정리 참고: https://mekain80.tistory.com/325
OpenAI Codex 이슈 #31864: https://github.com/openai/codex/issues/31864
OpenAI Codex Configuration Reference: https://developers.openai.com/codex/config-reference
OpenAI Codex config schema: https://developers.openai.com/codex/config-schema.json
LazyCodex 이슈 #118: https://github.com/code-yeongyu/lazycodex/issues/118

부제목/미리보기: GPT-5.6 Sol에서 일반 질문까지 실패하는 collaboration.spawn_agent 오류의 원인과 LazyCodex v4.16.2 업데이트, config.toml 우회 설정, CLI 검증 순서를 정리했습니다.

태그: Codex, GPT-5.6 Sol, OpenAI Codex, collaboration.spawn_agent, MultiAgentV2, LazyCodex, OMO, config.toml, Codex 오류 해결, 멀티 에이전트

AI를 비서처럼 사용하려면 업무 흐름부터 정리해야 합니다

RichLegend — Mon, 29 Jun 2026 11:45:15 +0900

요즘 AI 활용법을 보면 대부분 “프롬프트를 어떻게 잘 쓰느냐”에 집중합니다.

물론 중요합니다.

같은 질문을 해도 어떻게 묻느냐에 따라 답의 질이 달라지니까요.

그런데 실제 업무에서 더 큰 차이를 만드는 건 프롬프트 실력이 아니라, 일을 맡길 수 있는 구조입니다.

AI를 검색창처럼 쓰는 사람은 매번 직접 물어봐야 합니다.

반대로 AI를 업무 흐름 안에 넣는 사람은 자리를 비워도 일이 조금씩 진행되게 만듭니다.

AI 활용의 기준을 바꿔야 합니다

AI를 “잘 쓰는 도구”로만 보면 계속 내가 중심이 됩니다.

내가 질문하고, 내가 복사하고, 내가 정리하고, 내가 다시 옮깁니다.

이 방식은 빠르긴 하지만 결국 손이 계속 갑니다.

이제는 질문을 잘하는 단계에서 한 걸음 더 가야 합니다.

반복되는 업무를 정리하고, AI가 처리할 수 있는 단위로 쪼개고, 결과물을 다시 내가 확인하는 구조를 만드는 겁니다.

쉽게 말하면 AI에게 모든 판단을 넘기는 게 아닙니다.

내가 판단하고, AI는 실행하게 만드는 방식입니다.

처음부터 큰 자동화를 만들 필요는 없습니다

많은 분들이 자동화를 어렵게 생각합니다.

하지만 시작은 작아도 됩니다.

예를 들어 이런 업무부터 넘겨볼 수 있습니다.

회의 메모를 요약하기
긴 글에서 핵심만 뽑기
반복되는 이메일 초안 만들기
매일 확인하는 자료를 정리하기
일정이나 할 일을 다시 분류하기
블로그 글의 초안 구조 잡기

이런 일들은 창의적인 판단보다 반복과 정리가 많이 들어갑니다.

그래서 AI에게 맡기기 좋습니다.

핵심은 “AI가 할 수 있는 일”을 찾는 게 아니라, “내가 계속 반복하고 있는 일”을 먼저 찾는 겁니다.

좋은 자동화는 질문이 아니라 흐름에서 시작됩니다

프롬프트 하나를 잘 쓰는 것도 도움이 됩니다.

하지만 업무 흐름 안에 들어간 AI는 더 강력합니다.

예를 들어 블로그 글을 쓴다고 해보겠습니다.

예전 방식은 이렇습니다.

자료를 찾고, 핵심을 읽고, 제목을 고민하고, 목차를 만들고, 초안을 쓰고, 다시 다듬습니다.

AI를 도구처럼만 쓰면 이 중간중간에 계속 질문을 던져야 합니다.

하지만 구조를 만들면 달라집니다.

자료를 넣으면 핵심을 뽑고, 핵심을 바탕으로 목차를 만들고, 목차를 기준으로 초안을 만들고, 마지막에 사람이 톤과 사실을 검토합니다.

이때 사람의 역할은 줄어드는 게 아닙니다.

오히려 더 중요해집니다.

사람은 방향, 기준, 맥락, 최종 판단을 맡습니다.

AI는 반복, 정리, 초안, 변환을 맡습니다.

하루 10분짜리 일부터 넘겨보세요

처음부터 거창한 자동화 시스템을 만들려고 하면 금방 막힙니다.

대신 하루에 10분씩 잡아먹는 일을 하나만 골라보세요.

매일 같은 형식으로 정리하는 보고서.

반복해서 쓰는 안내 메시지.

읽고 요약해야 하는 긴 자료.

회의 후 매번 다시 정리하는 액션 아이템.

이런 작은 일을 AI에게 넘기는 것만으로도 체감이 생깁니다.

하루 10분이면 별것 아닌 것 같지만, 매일 반복되면 한 달에 몇 시간이 됩니다.

더 중요한 건 시간이 아니라 집중력입니다.

작은 반복 업무가 줄어들면, 진짜 판단이 필요한 일에 에너지를 남길 수 있습니다.

AI 시대의 생산성은 “질문력”보다 “위임력”에 가깝습니다

앞으로 AI를 잘 쓰는 사람은 단순히 프롬프트를 많이 아는 사람이 아닐 가능성이 큽니다.

자기 업무를 잘게 나누고, 어디까지 AI에게 맡길지 정하고, 결과를 검수할 기준을 가진 사람입니다.

AI에게 전부 맡기는 것이 아니라, 맡겨도 되는 일을 구분하는 능력.

결과가 틀렸을 때 바로 알아차릴 수 있는 기준.

그리고 반복되는 일을 다시 구조화하는 습관.

이 세 가지가 쌓이면 AI는 단순한 도구가 아니라, 내 업무 흐름 안에서 계속 일하는 보조 인력이 됩니다.

처음부터 완벽할 필요는 없습니다.

오늘 반복한 일 하나를 적어보세요.

그리고 이렇게 질문해보면 됩니다.

“이 일에서 내가 꼭 해야 하는 판단은 무엇이고, AI에게 넘겨도 되는 실행은 무엇일까?”

AI 활용은 여기서부터 달라집니다.

AX 시대, AI를 슬랙에 팀원처럼 초대하는 법

RichLegend — Fri, 26 Jun 2026 11:02:27 +0900

AX 시대, AI를 슬랙에 팀원처럼 초대하는 법

AI를 업무에 쓰는 방식이 바뀌고 있습니다.

예전에는 한 사람이 챗봇 하나를 열고 질문하는 방식이 대부분이었습니다. 자료를 요약하고, 글을 고치고, 코드를 작성하는 식이었죠. 이때 AI는 개인 생산성 도구에 가까웠습니다.

그런데 AX, 즉 AI Transformation 관점에서 보면 다음 단계는 조금 다릅니다. 이제는 AI를 개인 대화창 안에 두는 것이 아니라, 슬랙 같은 협업 공간에 초대해 팀의 일부처럼 함께 일하게 만드는 방향으로 가고 있습니다.

여기서 중요한 질문이 생깁니다.

AI를 팀 채널에 초대한다는 건, 단순히 편한 도구를 하나 더 붙이는 일이 아닙니다. 같이 일할 팀원을 한 명 더 들이는 일에 가깝습니다. 그래서 어떤 일을 맡길지, 어떤 자료를 보게 할지, 결과를 어떻게 확인할지 정도는 미리 정해두는 편이 좋습니다.

1. AX의 출발점은 ‘AI 사용’이 아니라 ‘팀 운영 방식’입니다

많은 조직이 AI 도입을 개인 생산성 관점에서 시작합니다. 직원들이 AI로 문서를 빨리 쓰고, 개발자가 코드를 빨리 만들고, 기획자가 자료를 빨리 정리하는 식입니다.

물론 효과는 있습니다. 하지만 개인 단위로만 AI를 쓰면 팀의 맥락은 흩어지기 쉽습니다. 같은 질문을 여러 사람이 따로 하고, 비슷한 문서를 각자 만들고, 중요한 판단이 개인 대화창 안에 남습니다.

AX는 여기서 한 단계 더 나아갑니다.

“각자가 AI를 잘 쓰는가?”보다 “우리 팀의 일하는 방식이 AI와 함께 일하도록 바뀌었는가?”를 봐야 합니다.

AI가 팀의 공통 자료를 읽고, 같은 목표를 기준으로 움직이고, 같은 채널에 결과를 남길 때 생산성은 개인을 넘어 팀 단위로 올라갑니다.

2. AI를 슬랙에 팀원처럼 초대하면 일이 훨씬 자연스러워집니다

AI를 슬랙 같은 협업 공간에 초대하면 일하는 흐름이 훨씬 자연스러워집니다. 따로 창을 열어 질문하고 답을 복사해오는 대신, 팀이 대화하는 자리에서 바로 AI를 부를 수 있기 때문입니다.

예를 들어 회의가 끝난 뒤 “오늘 결정된 내용만 정리해줘”라고 부탁할 수 있습니다. 새로 들어온 팀원에게 필요한 문서를 찾아달라고 할 수도 있고, 긴 논의 끝에 남은 할 일을 뽑아달라고 할 수도 있습니다.

이렇게 되면 AI는 개인 비서라기보다 팀 채널에 함께 있는 동료에 가까워집니다. 사람이 맥락을 다시 설명하는 시간이 줄고, 팀원들도 같은 자리에서 AI가 정리한 내용을 함께 확인할 수 있습니다.

다만 AI를 팀원처럼 쓰려면 기본적인 운영 방식은 정해두는 편이 좋습니다. 어떤 채널에서 부를지, 어떤 일을 맡길지, 어느 정도까지 스스로 처리하게 할지 정도는 팀 안에서 합의가 필요합니다.

이 기준이 있으면 AI를 쓰는 일이 훨씬 편해집니다. 매번 “어디까지 시켜도 되지?”를 고민하지 않아도 되고, AI가 남긴 결과도 팀의 공식 흐름 안에 자연스럽게 쌓입니다.

3. 사람과 AI 모두에게 역할이 있어야 합니다

AI를 팀에 붙일 때 가장 먼저 정해야 하는 건 역할입니다. 아무 일이나 던지는 방식으로는 오래가기 어렵습니다.

예를 들어 한 AI는 자료 정리를 맡고, 다른 AI는 초안 작성을 맡고, 또 다른 AI는 검토를 맡을 수 있습니다. 사람은 방향을 정하고, 중요한 판단을 하고, 외부로 나가는 결과물을 최종 확인합니다.

이렇게 나누면 일이 훨씬 단순해집니다. 누가 무엇을 맡았는지 보이고, AI에게 어떤 자료나 도구가 필요한지도 자연스럽게 정리됩니다.

반대로 역할이 없으면 팀원마다 AI에게 다른 방식으로 일을 시키게 됩니다. 결과물은 흩어지고, 같은 작업을 반복하고, 나중에는 어떤 기준으로 나온 결과인지 확인하기 어려워집니다.

AI도 팀원이 된다고 생각하면 답이 조금 쉬워집니다. 새 팀원이 들어왔을 때처럼 “이 사람은 무엇을 맡는가”, “어떤 자료를 보면 되는가”, “어떤 결과를 남겨야 하는가”를 정해주면 됩니다.

4. AI도 팀의 흐름을 알아야 일을 잘합니다

AI는 사람이 말하지 않은 분위기나 배경을 저절로 알지 못합니다. 회의에서 말로만 정한 내용, 개인 메신저에만 남은 결정, 담당자 머릿속에만 있는 기준은 AI 입장에서는 없는 정보와 같습니다.

그래서 AI를 슬랙 채널에 초대한다면, 중요한 결정과 기준은 팀이 함께 보는 곳에 남기는 편이 좋습니다.

회의에서 정한 내용은 회의록에 남기고, 우선순위가 바뀌면 채널이나 문서에 적어두고, 프로젝트 기준은 찾기 쉬운 곳에 정리해두는 식입니다. 그래야 사람도 AI도 같은 내용을 보고 움직입니다.

물론 모든 정보를 다 공개하자는 뜻은 아닙니다. 민감한 정보는 당연히 구분해야 합니다. 다만 함께 일하기로 한 범위 안에서는 필요한 맥락을 찾을 수 있어야 합니다.

AI에게는 문서와 대화 기록이 업무 환경입니다. 기록이 잘 남아 있는 팀일수록 AI가 더 빨리 이해하고, 덜 헤맵니다.

5. 사람은 더 중요한 판단에 집중해야 합니다

AI가 팀 채널 안에서 할 수 있는 일은 생각보다 많습니다. 회의 내용을 정리하고, 자료를 모으고, 초안을 만들고, 빠진 부분을 찾아볼 수 있습니다.

하지만 그렇다고 해서 사람의 역할이 사라지는 것은 아닙니다. 오히려 더 선명해집니다.

AI가 반복적인 정리와 초안을 맡아주면, 사람은 방향을 정하고 우선순위를 판단하는 데 더 많은 시간을 쓸 수 있습니다. 외부로 나가는 글, 고객에게 전달되는 답변, 중요한 의사결정은 여전히 사람이 확인해야 합니다.

AX가 좋은 방향으로 가려면 “AI가 어디까지 해줄 수 있는가”만 보지 말고 “사람은 어떤 판단에 집중해야 하는가”도 함께 봐야 합니다.

6. 팀이 어디로 가는지 AI도 알아야 합니다

AI가 팀의 일을 도우려면 “우리 팀이 지금 어디에 집중하고 있는지”를 알아야 합니다.

예를 들어 “고객 문의 처리 시간을 줄인다”, “신규 사용자가 첫 성공 경험을 더 빨리 하게 만든다”, “반복 운영 업무를 줄이고 사람이 판단해야 할 일에 집중한다” 같은 문장이 있을 수 있습니다.

이런 방향이 정리되어 있으면 AI도 더 좋은 방식으로 돕습니다. 자료를 정리할 때도 중요한 것부터 보려고 하고, 제안을 할 때도 팀이 실제로 신경 쓰는 문제에 맞춰 생각합니다.

물론 처음부터 AI에게 너무 많은 판단을 맡길 필요는 없습니다. 처음에는 정해진 일을 맡기고, 결과를 보면서 조금씩 범위를 넓히면 됩니다.

7. 신뢰는 검증 구조에서 생깁니다

AI 에이전트에게 일을 맡기려면 신뢰가 필요합니다. 그런데 신뢰는 “AI가 똑똑하다”는 인상만으로 만들어지지 않습니다.

처음에는 사람이 결과를 직접 보고, 기준을 알려주고, 필요한 경우 다시 하게 해야 합니다. 업무별 체크리스트도 필요합니다. 코드라면 테스트가 있어야 하고, 문서라면 톤과 구조에 대한 기준이 있어야 합니다. 콘텐츠라면 사실 확인과 금지 표현 기준이 있어야 합니다.

한 AI가 작업하고 다른 AI가 검토하는 방식도 유용합니다. 사람에게 오기 전에 1차 오류를 줄일 수 있기 때문입니다.

중요한 건 AI에게 맡길수록 사람의 역할이 사라지는 게 아니라는 점입니다. 오히려 사람의 역할은 더 선명해집니다. 방향 설정, 판단, 승인, 책임은 여전히 사람에게 남습니다. AI는 그 판단이 필요한 지점까지 가는 반복 작업을 줄여줍니다.

AX를 시작하는 팀이 먼저 물어볼 질문

AI를 팀 채널에 초대하기 전에 아래 질문부터 정리해보면 좋습니다.

AI를 어떤 슬랙 채널에서 부를 것인가?
AI에게 주로 어떤 일을 맡길 것인가?
AI가 참고할 문서와 자료는 어디에 정리되어 있는가?
사람과 AI의 역할을 한 문장으로 설명할 수 있는가?
중요한 결정이 개인 대화가 아니라 공유 채널이나 문서에 남는가?
팀이 지금 집중하는 방향이 짧게 정리되어 있는가?
결과물을 검증할 체크리스트나 테스트가 있는가?
AI가 반드시 사람에게 승인을 받아야 하는 작업이 구분되어 있는가?
AI가 남긴 결과를 팀 기록으로 쌓는 방식이 있는가?

AI 도입해야 한다는 건 아는데, 사내에서 어디부터 시작해야 할지 모르시는 분 있으세요?

RichLegend — Sat, 2 May 2026 15:46:52 +0900

AI 도입해야 한다는 건 아는데, 사내에서 어디부터 시작해야 할지 모르시는 분 있으세요?
현장에서 AX가 막히는 지점은 딱 두 가지라고 해요.
첫째, 복잡한 실무는 멀티에이전트 자동화가 필요한데 내부에서 구축하기가 어렵다는 것.
둘째, AI가 잘 일하려면 비즈니스 데이터가 공급되어야 하는데, 어떻게 넣을지 모르거나 쌓아둔 데이터 자체가 없는 경우가 많다는 것.
그래서 현장에서 효과적인 접근은 "가장 귀찮은 반복 업무 1개부터 AI에 연결하는 것"이에요.
작은 효용을 한 번 경험하면, 사람들은 스스로 데이터를 더 넣으려 한다고 해요.
AX는 거창한 선언이 아니에요.

rich.legend.ai

richlegendai

AX 채용 시장을 직접 들여다보니 — 경력직 중심, 재설계 역량, 그리고 진짜 AX 인재의 조건

RichLegend — Fri, 1 May 2026 15:59:02 +0900

AX 채용 시장을 직접 들여다보니 — 경력직 중심, 재설계 역량, 그리고 진짜 AX 인재의 조건

최근 AX(AI Transformation) 채용 공고를 꽤 오래 살펴볼 기회가 있었습니다.

포지션별 요건, 선호 경력, 도메인 분포까지 훑어보고 나니 하나의 흐름이 선명하게 보였습니다.

AX는 지금, 신입 시장이 아닙니다.

AX는 경력직 시장입니다 — 평균 4.3년, 중앙값 3년

공고에서 확인한 요구 경력의 평균은 약 4.3년이었고, 중앙값은 3년 정도였습니다.

신입 포지션이 아예 없는 건 아니었지만, 대부분은 인턴 또는 주니어에 가까운 수준이었습니다.

이 숫자가 의미하는 건 단순하지 않습니다.

기업들이 AI를 다룰 줄 아는 사람이 아니라, 현업의 일을 이해하고 그 구조를 바꿀 수 있는 사람을 찾고 있다는 뜻입니다.

가장 많이 본 역량 키워드 — As-Is에서 To-Be로

공고에서 가장 자주 등장한 흐름은 As-Is 분석 → To-Be 설계 → 운영 안착이었습니다.

지금 업무가 어떻게 굴러가는지 파악하고, 어디에 병목이 있는지 찾고, AI가 들어갈 수 있는 구조로 다시 설계하는 능력입니다.

여기서 중요한 포인트가 하나 있습니다.

PoC(개념 검증)에서 끝나는 게 아니라, 실제 운영까지 끌고 가는 경험을 요구한다는 점입니다.

실험에서 멈추는 게 아니라, 조직에 정착시키는 과정까지 책임져본 사람이어야 한다는 것이죠.

AX는 ChatGPT 계정 배포가 아닙니다

솔직히 말하면, 그동안 'AI 도입'이라는 이름 아래 ChatGPT 계정을 나눠주고 몇 번 교육하는 걸 AX라고 부르는 경우도 많았습니다.

하지만 채용 시장에서 보이는 AX는 그 레벨이 아닙니다.

일하는 방식 자체가 바뀌어야 AX입니다.

단순 툴 도입이 아닌, 프로세스 재설계, 구조 변화, 조직 문화의 전환까지 포함합니다.

도메인별 수요 지도 — 제조 / 금융 / 공공

AX 수요가 어느 산업에 몰려 있는지도 꽤 선명하게 보였습니다.

제조: 공정, 설계, 품질, 생산관리 영역에 AI를 연결하려는 수요
금융: 보안과 컴플라이언스 규제 안에서 AI를 적용하려는 수요
공공: B2G, R&D, 행정 자동화 중심의 수요

각 산업 특성에 맞는 도메인 이해 없이는 AX 역할을 제대로 수행하기 어렵다는 뜻이기도 합니다.

뜬구름 잡듯 'AI 잘함'으로 통하던 시대가 지나고, 이제 각 산업의 실제 업무 안으로 AI가 들어가기 시작한 것입니다.

결론 — AX 인재의 진짜 조건

AX 인재는 AI 뉴스를 많이 아는 사람이 아닙니다.

툴 이름을 많이 외운 사람도 아닙니다.

진짜 중요한 건 이것입니다.

내가 속한 조직의 일이 어떻게 흘러가는지 알고,
그 일을 AI가 들어갈 수 있는 구조로 다시 바꿀 수 있는 사람.

일을 직접 해본 경험, 시스템 안에서 굴러가는 업무를 이해해본 경험, 그리고 다른 사람의 문제를 해결 가능한 구조로 바꿔줄 수 있는 감각.

AI를 잘 아는 것도 중요하지만, 그보다 먼저 일이 어떻게 돌아가는지 알아야 합니다.

그래야 어디에 AI를 넣어야 하는지, 무엇을 자동화해야 하는지, 어떤 부분은 사람이 판단해야 하는지가 비로소 보이기 때문입니다.

AX는 SI가 아닙니다. 일하는 방식을 재설계하는 것입니다.

github에 오픈소스 SaaS 스타터킷을 배포했습니다.

RichLegend — Thu, 30 Apr 2026 13:05:24 +0900

SaaS 새로 만들 때마다 똑같은 데서 시간 다 까먹는 거, 저만 그런 거 아니죠.
로그인 붙이는 데 하루, 결제 붙이는 데 또 하루, DB 스키마 짜다 보면 정작 본 기능은 손도 못 댄 채 주말이 끝나더라고요. 매번 그러니까 어느 순간부터 새 SaaS 시작하는 게 좀 무서워졌어요.
그래서 제가 매번 쓰던 조합을 한 번에 합쳐서 github에 오픈소스 SaaS 스타터킷으로 풀었어요.

이름은 RichLegend AI SaaS Starter Kit이고, 한국어가 기본인 SaaS 보일러플레이트 / 템플릿이라고 보시면 돼요.
들어 있는 스택은 이렇게 돼요.
Next.js 16 (App Router 기반)
Clerk 인증
Polar.sh 결제 + webhook
Supabase Postgres + Drizzle ORM
next-intl 다국어 (한국어/영어, 확장 가능)
TailwindCSS + Base UI
SEO / JSON-LD / sitemap / hreflang
공개 저장소용 secret-scan
MIT라 그냥 가져다 쓰셔도 되고, 한국어가 기본이라 카피 다시 쓰는 일도 줄어요.
pnpm install 하고 .env.local 채운 다음 pnpm dev 하면 바로 /ko 화면이 떠요. 똑같은 기반 작업 또 반복하기 싫으셨던 분들에게 도움이 됐으면 해요.

https://github.com/richlegendai/richlegendai-saas-starter-kit-nextjs-v1

GitHub - richlegendai/richlegendai-saas-starter-kit-nextjs-v1

Contribute to richlegendai/richlegendai-saas-starter-kit-nextjs-v1 development by creating an account on GitHub.

github.com

AI 전환 진단 프로그램 AX Doctor v1 을 리뉴얼했습니다.

RichLegend — Wed, 29 Apr 2026 15:00:53 +0900

AI 전환 진단 프로그램 AX Doctor v1 by axq.kr
흩어져 있던 접점들을 단일 도메인으로 정리했고, AI 전환 진단 프로그램 AX Doctor by axq.kr 으로 리뉴얼했습니다.

AX Doctor는 조직의 AI 전환 준비 수준을 30문항·5분으로 진단하는 프로그램입니다.
Gartner·Cisco·Microsoft 프레임워크를 기반으로, 전략 정합성부터 문화·변화 관리까지 6개 차원을 측정합니다.
익명이고, 로그인도 필요 없습니다. 결과는 즉시 나옵니다.

"우리 조직이 AI를 도입할 준비가 됐는가"라는 질문에 데이터 기반의 답을 드립니다.

www.axq.kr

AXQ — AI Transformation 진단

01 산업 & 기본 정보 입력 회사명과 산업군을 선택하면 동종업계 평균과 비교가 가능합니다. 모두 익명 처리됩니다. 02 30문항 응답 (약 5분) 6개 핵심 Dimension에 걸쳐 5점 척도로 응답합니다. 각 질

www.axq.kr

AX 전에 DX, 데이터가 흐르는 인프라가 먼저다

RichLegend — Tue, 28 Apr 2026 16:31:19 +0900

AI를 쓰고 있다고 말하기 어려운 이유

"우리 조직은 AI를 제대로 쓰고 있는가?"

에이전트, 자동화, AX 키워드가 쏟아지지만 이 질문에 자신 있게 답하는 리더는 많지 않다.

데이터는 솔루션 안에 갇혀 있고, 꺼내려면 데이터 팀에 요청해야 하며, 보고서는 며칠 후에야 돌아온다.

최근 한 B2B SaaS 기업의 사업개발 리드가 이 문제를 '극단적 경영 가시성' — 조직의 모든 부서와 계층에서 즉시·충분히 알 수 있는 상태 — 이라는 개념으로 풀어냈다.

결론은 단순하다. 데이터가 흐르는 IT 인프라가 없으면 AI는 접근할 데이터 자체가 없다.

데이터 주권 3조건과 일의 정의

AI 활용의 출발점은 데이터 주권이다.

자사가 데이터를 직접 보유할 것, 그 데이터로 어떤 의사결정을 내려야 하는지 알 것, 데이터 간 연결이 가능할 것.

이 세 가지가 없으면 특정 솔루션에 종속된 의존성이 생기고 AI에게 넘길 일 자체를 정의하지 못한다.

"딸깍에 이르는 과정은 딸깍이 아니다."

어느 커머스 플랫폼 사업은 자사몰 자동화를 위해 900개 넘는 세부 태스크를 먼저 정의했다. 그 과정을 거친 뒤에야 AI가 대체할 항목을 분리할 수 있었다.

데이터가 흐르는 인프라가 먼저다

한 CX 솔루션은 API가 없어 요청 후 2~3주 뒤에야 데이터가 돌아왔고 그마저도 깨진 상태였다.

이런 환경에서는 어떤 AI를 붙여도 읽을 데이터가 없다.

해결책은 툴 중심 사일로를 해체하고 단일 소스 오브 트루스를 구축하는 것이다.

한 기업은 DW를 하나로 통합하고 각 필드에 의미·맥락 주석을 달았다. 그 결과 LLM이 직접 데이터를 읽게 됐고, 단순 쿼리를 데이터 팀에 의뢰하지 않아도 되는 환경이 만들어졌다.

"진짜 중요한 것은 앱이 아니라 데이터 파이프라인."

감지·실행·연결 — AI 에이전트 역할 설계

AI 에이전트의 역할은 세 단계로 나눈다.

감지(Detect) — 이상 데이터를 발견해 알려주는 수준. 여기까지만 돼도 의미 있다.

실행(Execute) — 위임된 범위 안에서 이메일 발송 등 특정 액션을 수행한다.

연결(Connect) — 문제 상황과 제안을 요약해 적절한 의사결정권자에게 넘긴다.

CRUD 권한 설계도 함께 이루어져야 한다. 어디까지 읽고, 쓰고, 지울 수 있는지를 용도와 권한에 따라 나누는 것이 보안과 자율성을 동시에 확보하는 방법이다.

AX 전에 DX, 사금이 금이 되려면

한 기업은 Claude에 MCP 접근 권한을 부여해 테이블 구조를 자동 설계하고, 고객 미팅 후 음성으로 대화 내용을 전달하면 CRM 필드에 자동 입력되는 환경을 만들었다.

기획·가공 시간은 체감 30% 수준으로 줄었고, 남은 시간에 사람을 직접 만나는 일에 집중할 수 있게 됐다.

"30년치 데이터도 그 자체로 가치를 갖지는 않는다. 사금을 캐고, 흔들고, 녹여야 금이 된다."

AX 전에 DX부터. 우리 조직의 데이터는 지금 AI가 접근할 수 있는 상태인가?

AX(AI Transformation) 진단 프로그램 v1을 만들었습니다.

RichLegend — Mon, 27 Apr 2026 10:10:57 +0900

AX 상태를 진단할 수 있는 간단하지만 핵심적인 내용으로 구성했습니다.

앞으로 계속 업데이트할 예정입니다.

https://ax-doctor.vercel.app/

AX Doctor — AI Transformation 진단

AX(AI Transformation) 성숙도를5분 만에 진단하세요 Gartner·Cisco·Microsoft AI Readiness 프레임워크 기반 30문항 설문으로 6개 핵심 Dimension의 현 수준과 우선 개선 방향을 즉시 확인합니다. 무료 진단 시작하

ax-doctor.vercel.app

AX의 성공은 기술이 아니라 '조직'이 결정한다

RichLegend — Mon, 27 Apr 2026 10:03:02 +0900

직원의 AI 접근성은 +50% 늘었지만, 정작 줄어든 것은 "사람이 직접 숙고하는 시간"이다. AX의 성공은 더 좋은 모델이 아니라 책임 있는 의사결정 구조와 실습·공유 기반의 문화가 결정한다.

왜 AI가 늘어도 AX는 어려운가

한국 딜로이트 그룹의 '기업의 AI 활용현황 2026 보고서'에 따르면 직원 AI 접근성은 50% 확대됐다. 회의록은 수 분 만에 요약되고, 보고서 초안도 즉시 나온다. 문제는 그 다음이다. 그럴듯한 결과물에 익숙해질수록 검증과 숙고가 뒤로 밀리고, 그렇게 굳어진 프로세스가 표준이 되어버리면 조직은 매일 틀린 줄도 모르는 답을 결재하게 된다.

LLM의 한계도 같은 위험을 키운다. 연구논문 Artificial Hivemind는 유사한 출력에 반복 노출될 경우 사고 자체가 동질화될 수 있다고 경고한다. 마이크로소프트 리서치(2025)도 자동화의 역설을 인용하며 "책임 설계가 없으면 조직은 결국 통제 강화로 회귀한다"고 짚었다.

처방 1. 책임 있는 의사결정 조직 재설계

리더의 일은 AI 답변을 받아쓰는 게 아니라 더 잘 판단하기 위해 깊이 숙고하는 일이다. 정답이 없는 기획·전략에서는 "결정을 검증하는 과정" 자체가 경쟁력이다. 핵심은 'AI 네이티브화' — AI를 전제로 업무를 설계하되, 그 안에서 사람이 해야 할 의사결정 영역을 분명히 구분하고 표준화된 검증·책임 구조를 함께 운영하는 것이다.

처방 2. 문화 확산 — 퍼널 4단계

AX의 본질은 기술이 아니라 문화다. 강의 한 번으로는 정착하지 않는다. 마케팅의 퍼널 효과를 그대로 적용할 수 있다.

인지 — AI 사용 불안을 줄이고 "이렇게 쓰면 된다"는 예시를 공유한다.
참여 — AI CoE(Center of Excellence)가 실무 문서를 함께 다듬어 주는 마중물이 된다.
적용 — 개선된 표준 프롬프트·템플릿으로 전사 품질을 상향 표준화한다.
공유 — 레시피 공유전·챌린지로 성공 경험의 장을 주기적으로 마련한다.
페인 포인트가 발견되고 작은 성과가 쌓이면 신뢰가 만들어지고, 그 신뢰가 다음 확산의 연료가 된다.

정부도 같은 방향이다

행정안전부는 'AI 거점리더·챔피언' 인재 양성으로 현장 거점을 세우고 있다. 재정경제부는 89개 공공기관이 참여하는 분과별 AI 활용 협의체를 가동했다. 인공지능전략위원회는 행동계획(26~28)을 통해 부처별 이행 과제를 제시했다.

마무리

AX는 더 비싼 모델을 쓰는 일이 아니다. 사람이 결정해야 할 자리를 지키고, 그 결정을 검증할 수 있는 구조와 문화를 만드는 일이다. 검증 없이 표준이 된 프로세스가 우리 회의실에도 한두 개쯤 있다면, 지금이 시작할 가장 좋은 때다.

AI 전환(AX)보다 DX(Digital Transformation)이 먼저다.

RichLegend — Thu, 23 Apr 2026 10:27:31 +0900

AI 전환(AX)을 서두르는 조직이 늘어나고 있다. 하지만 현장에서 보면, 많은 팀이 ‘AI를 도입하면 뭔가 달라질 것’이라는 기대만으로 움직이고 있다. 문제는 AX가 독립적인 변화가 아니라, 기존 디지털 전환(DX)의 연장선이라는 점이다. 기반 없이 얹힌 AI는 생산성을 높이기보다 오히려 혼란을 키운다.

AX를 시작하기 전에 반드시 점검해야 할 첫 번째는 데이터 파이프라인이다. 많은 조직이 데이터를 가지고 있다고 말하지만, 실제로는 활용 가능한 상태로 흐르고 있지 않은 경우가 많다. 데이터가 수집되고 저장되는 것과, 그것이 분석되고 의사결정에 쓰이는 것은 완전히 다른 이야기다. AI는 결국 데이터를 입력으로 삼기 때문에, 이 흐름이 정리되어 있지 않다면 결과 역시 불안정할 수밖에 없다.

두 번째는 반복 업무의 자동화 수준이다. AX는 자동화를 대체하는 개념이 아니라, 자동화를 기반으로 고도화하는 단계다. 여전히 사람이 엑셀을 정리하고, 수작업으로 데이터를 옮기고, 반복적인 보고서를 작성하고 있다면, 그 위에 AI를 얹는 것은 비효율을 확장하는 것에 가깝다. 먼저 RPA, 스크립트, API 연동 등을 통해 기본적인 자동화를 확보해야 한다. 그 다음에야 AI가 의미 있는 개선을 만들어낸다.

세 번째는 팀의 디지털 리터러시다. AI 도구를 사용할 줄 아는 것만으로는 부족하다. 중요한 것은 문제를 구조화하고, AI가 낸 결과를 비판적으로 검토하며, 워크플로우에 맞게 재구성할 수 있는 능력이다. 이 역량이 없다면 AI는 ‘마법 같은 도구’가 아니라 ‘예측 불가능한 변수’가 된다.

결국 AX는 기술 도입의 문제가 아니라, 준비 상태의 문제다. 많은 실패 사례는 AI 성능 때문이 아니라, 적용 대상이 되는 프로세스가 정리되어 있지 않았기 때문에 발생한다. 정리되지 않은 워크플로우 위에 AI를 얹으면, 기존의 비효율과 혼란이 그대로 증폭된다.

그래서 AX는 DX를 건너뛰는 전략이 될 수 없다. 오히려 DX가 잘 되어 있는 조직일수록 AX의 효과를 빠르게 체감한다. 데이터가 흐르고, 자동화가 자리 잡고, 팀이 디지털 방식으로 사고할 수 있을 때, AI는 비로소 ‘레버리지’로 작동한다.

정리하면, AX의 본질은 ‘AI를 도입하는 것’이 아니라, ‘AI가 제대로 작동할 수 있는 상태를 만드는 것’이다. 그리고 그 출발점은 언제나 DX다.

AX 실패의 역설: 왜 당신의 자동화 프로젝트는 '유령 시스템'이 되는가?

RichLegend — Thu, 23 Apr 2026 09:58:05 +0900

AX가 실패하는 이유: 기술이 아니라 접근 방식이다.
많은 기업이 AX(업무 자동화)를 도입할 때 비슷한 패턴을 밟는다.
“우리 업무를 분석해서 자동화 설계해보자.”
그리고 몇 달 뒤, 결과는 뻔하다. 시스템은 남지만 현업은 쓰지 않는다.

왜 이런 일이 반복될까?
핵심은 AX 대상 업무가 ‘고약한 문제’라는 데 있다.
해보기 전까지는 진짜 병목이 어디인지 알 수 없다.
사람의 습관, 예외 케이스, 책임 구조가 계속 튀어나오며 계획을 흔든다.

그런데 많은 기업은 폭포수 방식으로 접근한다.
즉, “처음에 모든 걸 정의할 수 있다”는 가정 위에서 출발한다.
이 방식은 완성도를 높이는 데는 적합하지만,
예측 불가능성이 큰 AX에는 맞지 않는다.
그래서 실패한다.

AX의 올바른 접근: 작은 자동화에서 시작하기
AX는 거대한 설계가 아니라 작은 시도에서 출발해야 한다.

1. 작은 자동화를 실제 업무에 붙인다.
2. 현업의 반응을 관찰한다.
3. 문제를 다시 정의한다.
4. 반복한다.

이 과정을 통해 조직은 단순히 자동화를 구축하는 것이 아니라,
문제를 정의하는 속도를 높인다.
자동화는 결과물이 아니라 학습을 위한 도구가 된다.

폭포수 vs AX: 완성도 vs 학습 속도
폭포수 방식은 완성도를 올리는 구조다.

AX는 학습 속도를 올리는 게임이다.

즉, AX의 성공은 기술적 완성도가 아니라
얼마나 빠르게 문제를 재정의하고 개선할 수 있는지에 달려 있다.

결론
AX는 단순히 “업무를 자동화한다”는 프로젝트가 아니다.
조직이 문제를 정의하고 학습하는 능력을 키우는 과정이다.
작은 자동화부터 시작해, 현업과 함께 배우고,
반복하며 점차 확장하는 접근만이 AX를 성공으로 이끈다.

AX(AI Transformation) - 기획서부터 백엔드, 프론트엔드, 배포까지, AI가 바꾼 개발 파이프라인 이야기

RichLegend — Wed, 22 Apr 2026 09:17:47 +0900

AX(AI Transformation) - 기획서부터 백엔드, 프론트엔드, 배포까지, AI가 바꾼 개발 파이프라인 이야기

얼마 전까지만 해도 "AI 잘 쓰는 개발자"의 기준은 코드 자동완성을 얼마나 잘 활용하느냐였습니다. 커서(Cursor)를 쓰냐, Claude Code를 쓰냐. 그게 전부인 줄 알았어요.

그런데 어느 순간부터 그 질문이 달라지기 시작했습니다. "어떤 AI 에디터를 쓰냐"가 아니라, "어떤 파이프라인으로 개발하느냐"로. 그 변화를 직접 겪으면서, 저는 꽤 많은 것을 다시 생각하게 됐습니다.

AI 에디터를 넘어 파이프라인으로: 파도의 방향이 바뀌었다.

2023년에 DX(디지털 전환)가 있었다면, 2025년엔 AX(AI 전환)가 왔습니다. 이름만 바뀐 게 아닙니다. 결이 다릅니다.

DX는 오프라인에 있던 것을 온라인으로 옮기는 작업이었습니다. 예약 시스템을 만들고, 재고 관리를 엑셀에서 SaaS로 이전하고. 비교적 명확한 목적지가 있었죠.

AX는 좀 다릅니다. "AI로 뭘 해야 하지?"라는 질문 자체가 출발점인 경우가 많습니다. 그래서 많은 팀이 가장 손쉬운 것부터 잡습니다. 코드 자동완성. 자동 테스트 생성. PR 요약.

나쁜 선택은 아닙니다. 그런데 거기서 멈추는 팀과, 그다음을 보는 팀 사이에 이미 격차가 생기고 있습니다.

1세대 AI 도입이 "AI로 코드를 빠르게 짜는 것"이었다면, 2세대는 다릅니다. 기획서부터 배포까지, 산출물 전 공정에 AI가 읽고 쓸 수 있는 언어를 심는 것. 그게 지금 제가 생각하는 진짜 AX입니다.

직접 겪어본 이야기: 내가 파이프라인을 만들게 된 이유

처음엔 솔직히 불편했습니다. 내가 짜야 할 코드를 AI가 대신 쓴다는 게 왠지 어색했거든요.

그런데 방향을 바꾸니 달라졌습니다. AI에게 코드를 맡기는 게 아니라, AI가 일할 수 있는 환경을 설계하는 것이 제 일이 됐습니다.

그 과정에서 겪은 일들이 있습니다.

첫 번째. 저는 Claude Code 환경에 훅(hook), 스킬(skill), 에이전트 계층을 직접 만들어 쌓았습니다. 처음엔 "이게 AI 생산성이랑 무슨 관계가 있나?" 싶었어요. 그런데 써보니 알겠더라고요. AI가 실수를 덜 하는 환경이 결국 생산성의 본체였습니다. AI 자체보다 AI를 둘러싼 구조가 더 중요했습니다.

두 번째. Figma에서 컴포넌트를 코드로 자동 변환하는 걸 해봤습니다. 처음엔 기대가 컸습니다. 그런데 디자인 토큰이 정리 안 된 상태에서 돌리니 쓸 수 없는 코드가 나왔어요. AI가 나쁜 게 아니었습니다. 제가 AI에게 줄 재료를 준비 안 한 거였습니다.

세 번째. Vercel에 환경변수를 설정하다가 런타임에서만 인증이 실패하는 이슈를 겪었습니다. 원인은 $ 문자가 포함된 값을 대시보드에 넣을 때 \$로 이스케이프된 채 저장된 것이었습니다. AI가 검토한 코드에는 문제가 없었습니다. 우리가 AI에게 준 컨텍스트에 구멍이 있었던 겁니다.

세 가지 사례에서 공통점이 보였습니다. 문제는 항상 AI 이전 단계에 있었습니다. AI에게 무엇을 어떻게 줄 것인가, 그 준비가 개발 생산성의 진짜 열쇠였습니다.

왜 PRD부터 시작해야 하는가: 스펙 없이 시작한 코드는 결국 다시 짠다.

AI 에이전트에게 "API 만들어줘"라고 말하면 뭔가 나오긴 합니다. 그런데 그게 우리가 원하는 건지 보장할 수 없습니다. 어떤 인증 방식인지, 실패 시 어떻게 처리하는지, 어떤 응답 구조를 써야 하는지 — 그 맥락이 없으면 AI는 그냥 그럴듯한 코드를 만들 뿐입니다.

문제는 요청 방식이 아닙니다. 입력 자체입니다.

현업에서 쓰는 PRD(Product Requirements Document, 제품 요구사항 문서)의 문제가 여기 있습니다. 대부분의 PRD는 사람이 읽기 위해 씁니다. "사용자가 로그인 버튼을 누르면 인증 프로세스가 시작된다." 이 문장은 사람에게는 자연스럽지만 AI에게는 모호합니다. 어떤 인증 방식인지, 실패 시 어떻게 처리하는지, 어떤 상태를 반환해야 하는지가 없습니다.

그래서 PRD를 다시 써야 합니다. 명시적 제약, 수용 기준(acceptance criteria), 데이터 계약이 담긴 AI가 읽을 수 있는 문서로. 그게 파이프라인의 진짜 출발점입니다.

요즘은 이걸 **컨텍스트 엔지니어링(Context Engineering)**이라고 부릅니다. AI에게 무엇을 어떤 형식으로 줄 것인가를 설계하는 일 자체가 하나의 전문 영역이 된 겁니다.

파이프라인 5단계: 기획에서 배포까지

개발 파이프라인에는 순서가 있습니다. 상류가 제대로 정의되어야 하류가 흔들리지 않습니다. AI를 쓸수록 이 원칙이 더 선명해집니다.

1단계 — PRD 표준화

PRD를 AI가 읽을 수 있는 형식으로 바꾸는 데서 시작합니다. YAML 프론트매터에 기능 ID, 수용 기준, 의존성, 데이터 타입을 명시합니다. "사용자가 가입할 수 있다"가 아니라, "이메일 + 비밀번호를 받아 users 테이블에 INSERT하고, 중복 시 409를 반환한다"로 씁니다. 처음엔 귀찮습니다. 그런데 이게 이후 모든 단계의 재료가 됩니다.

2단계 — 디자인 시스템 토큰화

Figma Variables를 JSON 토큰으로 추출하고, 그것이 Tailwind 설정이나 CSS 변수로 자동 연동되게 합니다. 디자이너가 브랜드 컬러를 바꾸면 코드가 따라 움직이는 구조. 이게 되어 있지 않으면, 컴포넌트를 AI가 아무리 잘 만들어도 스타일 불일치가 수동으로 쌓입니다.

3단계 — API 스펙 먼저

PRD에서 정의한 요구사항이 OpenAPI 스펙 또는 Zod 스키마로 정리됩니다. 코드를 먼저 짜는 게 아닙니다. 어떤 데이터를 주고받을지를 먼저 정합니다. 이 스펙이 명확하면 프론트엔드와 백엔드가 병렬로 개발해도 충돌이 없습니다. AI도 스펙에서 시작하면 훨씬 정확한 코드를 만듭니다.

4단계 — 프론트엔드 조립

디자인 토큰, API 스펙, PRD 요구사항이 모두 AI가 읽을 수 있는 형태로 갖춰져 있으면 프론트엔드 개발은 AI가 상당 부분 조립합니다. 컴포넌트 생성, API 연동, 에러 핸들링. 사람은 설계를 검토하고 엣지 케이스를 판단합니다.

5단계 — 하네스(검증 게이트)

하네스(harness)란 AI가 만든 결과물을 자동으로 검증하는 장치입니다. 타입 체크, 빌드 검증, 런타임 테스트, AI 코드 리뷰어. 이 게이트 없이 파이프라인을 돌리는 건 안전장치 없이 공장을 가동하는 것과 같습니다. 실수가 빠르게 누적됩니다.

시작하는 팀을 위한 현실적인 조언

"그럼 당장 뭘 해야 하나요?"라는 질문을 많이 받습니다.

다짜고짜 에이전트부터 도입하지 마세요. 저도 그랬다가 돌아온 경험이 있습니다. AI 에이전트는 좋은 재료가 있을 때 진짜 힘을 발휘합니다. 재료가 엉망이면 결과도 엉망입니다.

첫 주에 할 일은 하나입니다. PRD 하나를 골라서 AI가 이해할 수 있는 형식으로 다시 씁니다. 수용 기준을 명시적으로, 데이터 흐름을 타입과 함께. 그것만 해도 충분합니다.

첫 달에 할 일은 두 가지입니다. Figma 디자인 토큰 정리, 그리고 OpenAPI 스펙 기반으로 엔드포인트 하나를 파이프라인화합니다. 한 번 성공하면 팀 전체가 느낍니다. 뭔가 달라지고 있다는 걸.

첫 분기에 할 일은 자동화와 회고입니다. 리뷰 게이트를 CI에 붙이고, 실패했던 것들을 회고합니다. AI 실수의 패턴이 보이기 시작합니다. 그 패턴이 다음 하네스를 설계하는 재료가 됩니다.

핵심은 이겁니다. AI에게 일을 맡기는 게 아니라, AI가 일할 수 있는 환경을 만드는 것이 AX입니다.

사용자는 완성된 화면을 봅니다. 버튼이 잘 눌리는지, 속도가 빠른지. 그게 전부처럼 보이죠.

그런데 그 화면의 품질은 PRD가 얼마나 명확했는지, 디자인 토큰이 얼마나 잘 정의됐는지, API 스펙이 얼마나 구체적이었는지에 달려 있습니다. 사용자 눈에 보이지 않는 곳에서 품질이 결정됩니다.

AI가 바꾼 건 단순히 코드 작성 속도가 아닙니다. 상류 산출물의 품질이 하류 결과를 결정한다는 원리를 더 선명하게 드러낸 것입니다.

그 파이프라인을 설계하는 사람이, 다음 시대의 개발자라고 생각합니다.

ChatGPT Canvas(캔버스) 완벽 활용법! 실무자가 알려주는 진짜 꿀팁 모음 (2024년 최신 가이드) by 일하지마닷컴AI 리치레전드

RichLegend — Thu, 7 Nov 2024 16:44:56 +0900

ChatGPT Canvas(캔버스) 완벽 활용법! 실무자가 알려주는 진짜 꿀팁 모음 (2024년 최신 가이드) by 일하지마닷컴AI 리치레전드

안녕하세요, 일하지마닷컴AI - 디지털노마드 N잡러 개발자 리치레전드입니다.

이번 포스팅에서는 제가 AI 자동화 프로그램을 개발하면서 실제로 활용하고 있는 ChatGPT Canvas의 모든 노하우를 여러분과 공유하려고 해요.

ChatGPT Canvas의 강력한 기능들을 200% 활용하는 방법, 함께 알아볼까요?

ChatGPT Canvas가 특별한 이유

요즘 정말 다양한 AI 도구들이 쏟아져 나오고 있죠? 그중에서도 ChatGPT Canvas는 특별한 점이 있어요. 기존의 ChatGPT와는 차원이 다른 작업 환경을 제공한다는 거예요.

• 다중 채팅 관리로 복잡한 프로젝트도 한눈에
• 드래그 앤 드롭으로 작업물을 자유자재로 구성
• 실시간으로 다른 팀원들과 협업 가능
• 나만의 프롬프트 템플릿 만들기 지원

Canvas 시작 전 체크리스트

Canvas를 제대로 사용하기 위한 필수 준비사항들을 정리해봤어요.

• OpenAI 계정 생성하기
• GPT-4 모델 접근 권한 확보 (추천)
• 안정적인 인터넷 환경 확인
• 크롬 브라우저 최신 버전 설치

이런 기본적인 환경만 갖추면, 여러분도 바로 시작하실 수 있어요.

실무자가 알려주는 Canvas 실전 활용법

자, 이제부터가 진짜 핵심이에요. 제가 일하지마닷컴AI 리치레전드로서 실제 업무에서 활용하고 있는 Canvas 꿀팁들을 낱낱이 공개할게요.

• 프롬프트 라이브러리 구축하기
업무별로 자주 쓰는 프롬프트를 정리해두면 정말 편해요.

• 멀티 채팅 프로세스 활용하기
복잡한 프로젝트를 주제별로 나누어 관리하면 효율이 확 올라가요.

• 캔버스 레이아웃 최적화하기
자주 쓰는 기능은 드래그해서 쉽게 접근할 수 있게 배치하세요.

프로그래머가 직접 겪은 Canvas 활용 사례

제가 RPA 프로그램을 개발하면서 Canvas를 어떻게 활용했는지 실제 사례를 들어볼게요.

• 코드 최적화 작업
여러 버전의 코드를 동시에 분석하고 개선할 수 있었어요.

• API 문서 자동화
반복적인 문서 작업을 Canvas로 자동화했더니 시간이 반으로 줄었어요.

• 시스템 설계 브레인스토밍
복잡한 시스템 구조도 Canvas에서 체계적으로 정리할 수 있었죠.

일하지마닷컴 AI의 특별한 자동화 서비스

저희 일하지마닷컴 AI는 ChatGPT Canvas의 강력한 기능을 활용한 맞춤형 자동화 서비스를 제공하고 있어요.

• RPA 자동화 프로그램 개발
• 엑셀 매크로 솔루션 구축
• 맞춤형 웹 크롤링 시스템 구현
• 데이터 스크래핑 자동화

이 모든 프로그램은 파이썬을 기반으로 개발되며, Canvas의 강력한 기능과 결합하여 더욱 똑똑하게 작동한답니다.

여러분만의 맞춤형 자동화 프로그램이 필요하시다면 ilhajima.com을 방문해주세요. 상담 신청서에 원하시는 기능을 자세히 적어주시면, 리치레전드가 최적의 솔루션을 제안해드릴게요.

마무리: AI로 진화하는 업무 환경

지금까지 ChatGPT Canvas의 숨은 기능들과 실전 활용법을 자세히 알아보았는데요, Canvas를 제대로 활용하면 업무 효율이 정말 놀랍게 높아진답니다.

특히 자동화 도구와 결합했을 때 그 시너지가 엄청나요. 저희 일하지마닷컴AI와 함께라면 여러분의 업무 혁신이 한층 더 가까워질 거예요.

더 자세한 내용이 궁금하시다면 언제든 일하지마닷컴AI 리치레전드를 찾아주세요. 여러분의 디지털 혁신을 항상 응원하겠습니다!

인기 검색어 키워드: ChatGPT 캔버스 가이드 2024, Canvas 프롬프트 작성법, GPT4 실무 활용, 챗GPT 캔버스 업데이트, AI 업무 효율화, Canvas 비즈니스 적용, GPT Canvas 팁, 챗GPT 응용 활용, Canvas 실전 사례, AI 자동화 도구, ChatGPT Canvas 활용법, GPT 캔버스 사용법, AI 글쓰기 도구, 챗GPT 프롬프트, Canvas 초보 가이드, GPT 캔버스 강의, ChatGPT 최신기능, AI 업무 효율화, ChatGPT Canvas 팁, 캔버스 실전 활용

Claude AI 활용 가이드: 현직 개발자의 실전 경험담

RichLegend — Wed, 23 Oct 2024 09:45:46 +0900

Claude AI 활용 가이드: 현직 개발자의 실전 경험담

안녕하세요! 일하지마닷컴AI에서 RPA 매크로 프로그램을 개발하고 있는 리치레전드입니다. 오늘은 제가 실제로 업무에서 활용하고 있는 Claude AI에 대해 제 경험을 공유해드리려고 합니다.

처음 Claude를 만나다

작년에 처음 일하지마닷컴 AI를 개발하면서 Claude AI를 알게 되었을 때만 해도, 저 리치레전드는 그저 "또 하나의 챗봇이겠지"라고 생각했습니다. GPT-3.5 기반이라는 설명을 듣고 큰 기대 없이 시작했죠. 하지만 실제로 사용해보니, 제 생각이 완전히 틀렸다는 걸 깨달았습니다.

특히 개발자의 입장에서 보면, Claude는 단순한 챗봇이 아닌 든든한 동료 프로그래머 같은 존재입니다. 복잡한 알고리즘을 구현할 때나 버그를 찾아낼 때, 때로는 제가 미처 생각하지 못한 접근 방식을 제안해주기도 하죠.

실제 업무에서의 활용 사례

제가 Claude를 가장 유용하게 활용한 경험을 하나 공유해드리겠습니다. 얼마 전 네이버 뉴스 데이터를 수집하는 크롤러를 만들어야 했는데요, Claude의 도움으로 작업 시간을 절반 이상 단축할 수 있었습니다.

# 이런 복잡한 크롤링 코드도 Claude와 함께라면 쉽게 작성할 수 있습니다
def crawl_naver_news(keyword, page_num=1):
    base_url = f"https://search.naver.com/search.naver?where=news&query={keyword}&start={(page_num-1)*10+1}"

    response = requests.get(base_url)
    soup = BeautifulSoup(response.text, 'html.parser')

    news_list = []
    articles = soup.select(".news_area")
    # ... (코드 상세 내용)

물론 Claude가 제안한 코드를 그대로 사용하지는 않았습니다. 제 프로젝트의 특성에 맞게 수정하고, 예외 처리도 추가했죠. 하지만 기본 뼈대를 빠르게 잡을 수 있었다는 점에서 정말 큰 도움이 되었습니다.

개발자가 느낀 장단점

장점

실용적인 코드 제안: 단순히 동작하는 코드가 아닌, 실제 프로덕션에서 사용할 수 있는 수준의 코드를 제안받을 수 있습니다.
빠른 문제 해결: 에러 메시지를 붙여넣으면 대부분의 경우 명확한 해결책을 제시해줍니다.
자연스러운 소통: "이 부분은 이렇게 하면 어떨까요?"처럼 동료와 대화하듯 자연스러운 피드백을 주고받을 수 있습니다.

단점

실시간 정보의 한계: 새로 출시된 라이브러리나 최신 버전의 API 변경사항은 모를 수 있습니다.
맥락 이해의 한계: 프로젝트의 전체적인 구조나 비즈니스 로직을 완벽히 이해시키기는 어렵습니다.

효과적인 활용을 위한 팁

구체적인 요청하기: "이 코드 어떻게 고치면 돼?"보다는 "이 파이썬 코드에서 메모리 사용량을 줄이고 싶은데, 어떤 부분을 개선하면 좋을까요?"처럼 구체적으로 물어보세요.
단계적 접근: 큰 기능을 한 번에 요청하기보다는, 작은 단위로 나누어 요청하세요. 코드 품질도 높아지고 디버깅도 쉬워집니다.
검증하기: Claude가 제안한 코드는 반드시 테스트해보세요. 가끔 논리적 오류가 있을 수 있습니다.

마치며

AI는 분명 강력한 도구지만, 결국 그것을 어떻게 활용하느냐는 우리의 몫입니다. 일하지마닷컴AI를 개발하면서 Claude는 제게 없어서는 안 될 개발 파트너가 되었지만, 동시에 이는 제가 더 나은 개발자가 되기 위해 노력하게 만드는 자극제이기도 합니다.

여러분도 Claude를 단순한 도구가 아닌, 함께 성장하는 파트너로 생각하고 접근해보세요. 분명 일하지마닷컴AI의 리치레전드와 같이 새로운 가능성을 발견하실 수 있을 겁니다.

질문이나 의견이 있으시다면 언제든 일하지마닷컴 AI 리치레전드를 통해 연락주세요. 여러분의 AI 활용 이야기도 궁금합니다.

감사합니다!

Selenium과 Playwright 비교

RichLegend — Mon, 21 Oct 2024 09:00:03 +0900

Selenium과 Playwright 비교

안녕하세요, 일하지마닷컴AI 리치레전드입니다.

오늘은 웹 자동화 테스트에서 많이 사용되는 두 가지 도구인 Selenium과 Playwright를 비교해 보려고 합니다. 특히 파이썬을 사용하여 두 도구가 어떻게 활용될 수 있는지 구체적으로 살펴볼 것입니다.

1. 도구 소개

Selenium

2004년에 출시된 오픈 소스 웹 자동화 도구로, 다양한 언어와 브라우저를 지원합니다.
Python, Java, C# 등 여러 프로그래밍 언어와 통합할 수 있어 Python 개발자들 사이에서도 널리 쓰이고 있습니다.
Playwright

2020년 Microsoft에서 발표한 새로운 웹 자동화 도구입니다.
Python, JavaScript, TypeScript 등 여러 언어를 지원하며, 강력한 기능을 제공합니다.
현대적인 웹 테스트 환경을 위한 최신 도구로 자리 잡고 있습니다.

2. 파이썬에서의 주요 특징 비교

특징 Selenium with Python Playwright for Python
설치 방법 pip install selenium pip install playwright
브라우저 지원 Chrome, Firefox, Safari, Edge 등 Chromium, Firefox, WebKit
Python 버전 지원 Python 2.7 및 3.x Python 3.7 이상
비동기 지원 제한적 asyncio를 통한 강력한 비동기 지원
자동 대기 명시적 대기 필요 자동 대기 기능 내장

3. 코드 예제

Selenium 예제
python
코드 복사
from selenium import webdriver
from seleniuhttp://m.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://www.example.com")

element = driver.find_element(By.ID, "example-id")
element.click()

driver.quit()
Playwright 예제
python
코드 복사
from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://www.example.com")

    element = page.locator("#example-id")
    element.click()

    browser.close()
4. 파이썬 개발자를 위한 장단점 분석
Selenium with Python

장점:

오랜 역사와 넓은 사용자층 덕분에 참고할 수 있는 자료가 풍부합니다.
다양한 Python 라이브러리와의 호환성이 좋습니다.
여전히 Python 2.7 버전을 지원하여 레거시 시스템에서도 사용 가능합니다.
단점:

파이썬의 비동기 프로그래밍을 완전히 활용하기 어려워 일부 프로젝트에서는 성능상의 한계가 있습니다.
초기 설정이 다소 복잡할 수 있어, Python을 처음 접하는 개발자에게는 진입 장벽이 있을 수 있습니다.
Playwright for Python

장점:

Python의 최신 비동기 기능을 활용하여 더 빠르고 효율적인 테스트가 가능합니다.
직관적이고 현대적인 API 설계로 사용하기 편리하며 코드의 가독성이 좋습니다.
자동 대기 기능을 통해 복잡한 대기 설정 없이 안정적인 테스트가 가능합니다.
단점:

Python 3.7 이상의 버전만 지원하여 구형 시스템에서는 사용이 제한됩니다.
Selenium에 비해 Python 커뮤니티의 참고 자료가 적어 학습 시 불편할 수 있습니다.
5. 결론
Python 개발자 입장에서 두 도구 모두 각자의 강점을 지니고 있습니다. Selenium은 오랜 역사와 풍부한 커뮤니티 지원 덕분에 레거시 프로젝트나 여러 라이브러리와의 통합이 필요한 경우 유리합니다. 반면, Playwright는 최신 Python 기능을 적극 활용할 수 있고 현대적인 웹 애플리케이션 테스트에 최적화되어 있어 더 빠르고 안정적인 테스트를 제공할 수 있습니다.

프로젝트의 요구사항과 개발 환경에 따라 적절한 도구를 선택하는 것이 중요합니다. 두 도구 모두 Python 개발자가 충분히 활용할 수 있는 강력한 도구이므로, 실제 프로젝트에 적용해 보면서 각 도구의 장단점을 직접 체감해 보는 것도 좋은 방법입니다.

Claude 3.5 Sonnet의 혁신적인 기능인 Agentic Workflow

RichLegend — Mon, 21 Oct 2024 08:57:24 +0900

안녕하세요, 일하지마닷컴AI의 디지털 노마드이자 N잡러 개발자 리치레전드입니다.

오늘은 Claude 3.5 Sonnet의 혁신적인 기능인 Agentic Workflow에 대해 이야기해보려고 합니다. 제가 RPA 매크로 프로그램을 개발하며 직접 체험한 경험을 토대로, 이 기능이 어떻게 업무 효율을 극대화할 수 있는지 자세히 설명드릴게요. Agentic Workflow를 제대로 활용하면 여러분의 생산성이 200% 이상 올라갈 수 있습니다. 이제 Claude 3.5 Sonnet과 함께 Agentic Workflow의 세계로 들어가 볼까요?

Agentic Workflow란?

Agentic Workflow는 Claude 3.5 Sonnet의 주요 기능 중 하나로, 단순한 AI 챗봇의 수준을 넘어 ‘에이전트’처럼 행동하며 복잡한 작업을 단계별로 수행합니다. 기존의 AI 도구가 질문에 답하는 역할에 머물렀다면, Agentic Workflow는 프로젝트를 전반적으로 관리하고 실행할 수 있는 기능을 갖추고 있죠. 예를 들어, “웹사이트를 새로 만들고 싶어”라고 말하면 Claude AI가 다음과 같은 단계로 안내합니다:

웹사이트의 목적과 타겟 고객 정의
주요 페이지와 구조 설계
디자인 컨셉 결정
필요한 콘텐츠 목록 작성
개발 방법 선택 (예: WordPress, React)
개발 일정 수립
테스트와 론칭 계획 수립
이처럼 전체 프로젝트의 큰 그림을 그려주고, 각 단계에서 구체적인 지침과 필요한 리소스를 제시해줍니다. 마치 프로젝트 매니저, 기술 컨설턴트, 디자이너 역할을 동시에 수행하는 것 같죠.

Agentic Workflow의 핵심 특징

Agentic Workflow의 주요 특징은 다음과 같습니다:

목표 지향적 접근: 정보 제공을 넘어 최종 목표 달성을 위한 체계적인 접근을 제공합니다.
맥락 이해 및 유지: 긴 대화에서도 목표와 맥락을 일관성 있게 유지하며 작업을 진행합니다.
단계별 가이드: 복잡한 작업을 잘게 나누어 쉽게 따라할 수 있는 단계로 안내합니다.
유연한 대응: 사용자의 피드백에 따라 계획을 조정하고 예상치 못한 상황에도 대처할 수 있습니다.
다양한 역할 수행: 조언자, 코치, 프로그래머, 작가 등 여러 역할을 상황에 맞게 수행합니다.
이러한 특징 덕분에 Agentic Workflow는 단순한 AI 도우미를 넘어 다양한 업무에서 훌륭한 파트너로 자리잡을 수 있습니다.

Claude 3.5 Sonnet의 Agentic Workflow 활용 방법
Agentic Workflow를 실제로 어떻게 활용할 수 있는지 구체적으로 알아볼까요?

명확한 목표 설정: 프로젝트의 목표를 구체적으로 제시하세요. 예를 들어, "파이썬으로 네이버 뉴스에서 ‘인공지능’ 키워드로 검색된 기사 제목과 링크를 크롤링하고 싶어"라고 말하는 겁니다.
작업 계획 수립 요청: 목표가 설정되면 Claude AI에게 단계별 작업 계획을 요청하세요.
상세 지침 요청: 각 단계에 대한 구체적인 설명을 요청해 필요할 때마다 지침을 받을 수 있습니다.
코드 생성 요청: 코드 작성 단계에서는 Claude AI가 실제로 코드를 작성하고 설명까지 제공할 수 있습니다.
오류 해결: 코드 실행 중 발생하는 오류에 대한 해결 방법도 Claude AI에게 물어볼 수 있습니다.
결과 분석 및 추가 작업 제안: 작업 완료 후 Claude AI에게 수집된 데이터의 활용 방안 등을 조언 받을 수 있습니다.
프로젝트 문서화: 프로젝트가 끝나면 전체 작업 과정을 README 파일 등으로 정리해달라고 요청할 수 있습니다.
이렇게 체계적으로 활용하면, 복잡한 프로젝트도 처음부터 끝까지 일관성 있게 진행할 수 있습니다.

Agentic Workflow의 실제 사례
최근 저는 일하지마닷컴 AI를 위해 복잡한 RPA 매크로 프로그램을 개발해야 했습니다. 여러 웹사이트에서 데이터를 자동으로 수집하고 분석하는 것이 목표였죠. 하지만 어디서부터 시작해야 할지 막막했을 때, Claude 3.5 Sonnet의 Agentic Workflow가 큰 도움이 되었습니다.

프로젝트 정의: 프로젝트의 목적과 요구사항을 상세히 설명했습니다.
아키텍처 설계: Claude AI가 프로그램 구조와 필요한 모듈을 제안해줬습니다.
기술 스택 선택: Claude AI로부터 적합한 프로그래밍 언어와 라이브러리 추천을 받았습니다.
코드 작성: Claude AI가 제안한 코드를 검토하고 수정하는 방식으로 진행했습니다.
테스트 및 디버깅: 오류가 발생했을 때 Claude AI의 조언을 받아 문제를 해결했습니다.
최적화: 프로그램 성능 개선을 위한 다양한 제안도 받았습니다.
문서화: 프로젝트 전 과정을 상세히 정리한 문서를 작성했습니다.
결과적으로, Agentic Workflow 덕분에 혼자 개발했다면 한 달 이상 걸렸을 프로젝트를 단 2주 만에 끝낼 수 있었습니다.

Agentic Workflow와 다른 AI 도구들의 차이점
다른 AI 도구들과 비교하면, Agentic Workflow는 더 폭넓고 체계적인 지원을 제공합니다.

챗GPT와의 차이: 챗GPT는 주로 질의응답에 중점을 두지만, Agentic Workflow는 프로젝트 전체를 관리합니다.
AI 코딩 도우미들과의 차이: 대부분의 AI 코딩 도우미는 코드 작성과 디버깅에만 집중하지만, Agentic Workflow는 프로젝트 기획, 설계, 테스트, 문서화까지 포괄합니다.
프로젝트 관리 도구들과의 차이: 기존 도구들은 정해진 틀 안에서만 작업을 지원하지만, Agentic Workflow는 더 유연하고 창의적인 해결책을 제시할 수 있습니다.
장점과 주의점
장점:

시간 절약
프로젝트의 일관성 유지
창의적 문제 해결
새로운 기술 학습
높은 품질의 결과물
주의점:

AI에 과도한 의존은 금물
보안에 유의
AI의 맥락 이해를 항상 검토
기술적 한계 고려
일하지마닷컴 AI의 Agentic Workflow 활용 서비스
일하지마닷컴 AI는 Claude 3.5 Sonnet의 Agentic Workflow 기능을 활용해 업무 자동화 및 효율 향상 서비스를 제공합니다. 주요 서비스는 다음과 같습니다:

RPA 매크로 프로그램: 복잡한 업무 프로세스를 자동화
엑셀 매크로 프로그램: 대규모 데이터 처리와 분석 지원
웹 크롤링 프로그램: 효율적인 웹 데이터 수집
스크래핑 프로그램: 정확한 데이터 추출
모든 프로그램은 파이썬을 기반으로 개발되며, 일하지마닷컴 AI 홈페이지를 방문해 상담을 신청할 수 있습니다.

마무리
Agentic Workflow는 단순한 AI 도구를 넘어, 여러분의 든든한 협업 파트너가 될 수 있습니다. 복잡한 프로젝트도 일관성 있게 관리하고, 창의적인 해결책을 제시하며, 끊임없이 발전하는 AI와 함께 업무 효율을 극대화할 수 있죠. 일하지마닷컴 AI와 함께 스마트한 업무 환경을 만들어보세요. 여러분의 성공을 항상 응원합니다!

Selenium vs Playwright: 파이썬을 활용한 웹 자동화 도구 비교 분석

RichLegend — Fri, 26 Jul 2024 21:10:55 +0900

Selenium vs Playwright: 파이썬을 활용한 웹 자동화 도구 비교 분석

웹 자동화 테스팅 분야에서 주목받고 있는 두 가지 도구, Selenium과 Playwright에 대해 비교 분석해보려고 합니다. 특히 파이썬(Python) 언어를 사용하여 이 두 도구를 어떻게 활용할 수 있는지 살펴보겠습니다.

1. 소개

Selenium

2004년에 처음 출시된 오픈 소스 웹 자동화 도구
파이썬을 포함한 다양한 프로그래밍 언어와 브라우저를 지원
Python 개발자들 사이에서 인기 있는 웹 테스트 자동화 도구

Playwright

Microsoft에서 2020년에 출시한 비교적 새로운 도구
Python, JavaScript, TypeScript 등 다중 언어 지원
파이썬 사용자를 위한 강력한 API와 기능 제공

2. 파이썬에서의 주요 특징 비교

특징	Selenium with Python	Playwright for Python
설치 방법	pip install selenium	pip install playwright
브라우저 지원	Chrome, Firefox, Safari, Edge 등	Chromium, Firefox, WebKit
Python 버전 지원	Python 2.7 및 3.x	Python 3.7 이상
비동기 지원	제한적	asyncio를 통한 강력한 비동기 지원
자동 대기	명시적 대기 필요	자동 대기 기능 내장

3. 파이썬 코드 예제

Selenium with Python

from selenium import webdriver
from selenium.webdriver.common.by import By

driver = webdriver.Chrome()
driver.get("https://www.example.com")

element = driver.find_element(By.ID, "example-id")
element.click()

driver.quit()

Playwright for Python

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch()
    page = browser.new_page()
    page.goto("https://www.example.com")

    element = page.locator("#example-id")
    element.click()

    browser.close()

4. Python 개발자를 위한 장단점 분석

Selenium with Python

장점:

파이썬 커뮤니티에서 오랫동안 사용되어 풍부한 참고 자료
다양한 Python 라이브러리와의 호환성
Python 2.7 버전 지원 (레거시 시스템)

단점:

파이썬의 비동기 특성을 완전히 활용하기 어려움
설정이 복잡하고 Python 초보자에게는 학습 곡선이 가파를 수 있음

Playwright for Python

장점:

파이썬의 최신 기능 (asyncio 등)을 활용한 강력한 비동기 지원
Python 개발자를 위한 직관적이고 현대적인 API 설계
자동 대기 기능으로 파이썬 코드 작성 시 안정성 향상

단점:

Python 3.7 이상 버전만 지원 (레거시 시스템에서는 사용 제한)
Selenium에 비해 파이썬 커뮤니티의 자료가 상대적으로 적음

5. 결론

파이썬 개발자의 관점에서 볼 때, Selenium은 오랜 역사와 풍부한 참고 자료로 인해 여전히 강력한 선택지입니다. 특히 레거시 Python 프로젝트나 다양한 파이썬 라이브러리와의 통합이 필요한 경우에 유리할 수 있습니다.

반면 Playwright는 Python의 최신 기능을 적극 활용하고, 현대적인 웹 애플리케이션 테스팅에 최적화되어 있습니다. 파이썬의 asyncio를 활용한 비동기 프로그래밍이 필요하거나, 보다 안정적이고 빠른 테스트 실행이 필요한 프로젝트에 적합할 수 있습니다.

결국 파이썬 프로젝트의 요구사항, 팀의 기술 스택, 그리고 테스트 대상 애플리케이션의 특성을 고려하여 적합한 도구를 선택해야 합니다. Python 개발자라면 두 도구 모두 충분히 활용 가능하므로, 실제 프로젝트에 적용해보고 판단하는 것이 가장 좋은 방법일 것입니다.

Redis master-replicas sentinel 구성 시 docker-compose.yml 파일

RichLegend — Sat, 27 Apr 2024 21:37:08 +0900

docker-compose.yml 파일

bitnami/redis 이용

services:
  my-redis-a:
    hostname: redis-master
    container_name: redis-master
    image: "bitnami/redis"
    environment:
      - REDIS_REPLICATION_MODE=master
      - ALLOW_EMPTY_PASSWORD=yes
    ports:
      - 5000:6379

  my-redis-b:
    hostname: redis-replicas-1
    container_name: redis-replicas-1
    image: "bitnami/redis"
    environment:
      - REDIS_REPLICATION_MODE=slave
      - REDIS_MASTER_HOST=redis-master
      - ALLOW_EMPTY_PASSWORD=yes
    ports:
      - 5001:6379
    depends_on:
      - my-redis-a

  my-redis-c:
    hostname: redis-replicas-2
    container_name: redis-replicas-2
    image: "bitnami/redis"
    environment:
      - REDIS_REPLICATION_MODE=slave
      - REDIS_MASTER_HOST=redis-master
      - ALLOW_EMPTY_PASSWORD=yes
    ports:
      - 5002:6379
    depends_on:
      - my-redis-a

  redis-sentinel-1:
    container_name: sentinel1
    image: 'bitnami/redis-sentinel:latest'
    environment:
      - REDIS_SENTINEL_DOWN_AFTER_MILLISECONDS=3000
      - REDIS_MASTER_HOST=redis-master
      - REDIS_MASTER_PORT_NUMBER=6379
      - REDIS_MASTER_SET=mymaster
      - REDIS_SENTINEL_QUORUM=2
    ports:
      - 26379:26379
    depends_on:
      - my-redis-a
      - my-redis-b
      - my-redis-c

  redis-sentinel-2:
    container_name: sentinel2
    image: 'bitnami/redis-sentinel:latest'
    environment:
      - REDIS_SENTINEL_DOWN_AFTER_MILLISECONDS=3000
      - REDIS_MASTER_HOST=redis-master
      - REDIS_MASTER_PORT_NUMBER=6379
      - REDIS_MASTER_SET=mymaster
      - REDIS_SENTINEL_QUORUM=2
    ports:
      - 26380:26379
    depends_on:
      - my-redis-a
      - my-redis-b
      - my-redis-c

  redis-sentinel-3:
    container_name: sentinel3
    image: 'bitnami/redis-sentinel:latest'
    environment:
      - REDIS_SENTINEL_DOWN_AFTER_MILLISECONDS=3000
      - REDIS_MASTER_HOST=redis-master
      - REDIS_MASTER_PORT_NUMBER=6379
      - REDIS_MASTER_SET=mymaster
      - REDIS_SENTINEL_QUORUM=2
    ports:
      - 26381:26379
    depends_on:
      - my-redis-a
      - my-redis-b
      - my-redis-c

redis-cli 로 어떤 pod가 master 역할을 하는지 확인하는 명령어

redis-cli info | grep role

Amazon Linux 2023 에 Redis 설치하기

RichLegend — Fri, 19 Apr 2024 00:02:53 +0900

Redis 설치

sudo yum -y install openssl-devel gcc  
wget http://download.redis.io/redis-stable.tar.gz  
tar xvzf redis-stable.tar.gz  
cd redis-stable  
make distclean  
make redis-cli BUILD\_TLS=yes  
sudo install -m 755 src/redis-cli /usr/local/bin/

실행

./redis/src/redis-server

설치한 레디스 파일 전역 디렉토리로 복사

sudo cp src/redis-server src/redis-cli /usr/local/bin/

config 파일을 /etc/redis로 복사

sudo mkdir /etc/redis
sudo cp src/redis.conf /etc/redis

config 설정 변경

sudo vi /etc/redis/redis.conf

이후 redis-server 명령어로 레디스 실행

Spock 테스트 시 java.lang.NullPointerException: Cannot invoke method save() on null object 오류

RichLegend — Sat, 30 Mar 2024 15:08:38 +0900

문제점

Spock 테스트 시 Repository를 주입받지 못하는 오류가 발생

해결

build.gradle 에서 spring 3.2.4 버전을 기준으로 spock 버전을 재설정하여 해결

testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'

mariadb testcontainers

// testcontainers
testImplementation 'org.testcontainers:spock:1.19.7'
testImplementation 'org.testcontainers:mariadb:1.19.7'

build.gradle 전체

plugins {
    id 'java'
    id 'org.springframework.boot' version '3.2.4'
    id 'io.spring.dependency-management' version '1.1.4'
    id 'groovy'
}

group = 'com.valletta'
version = '0.0.1-SNAPSHOT'

java {
    sourceCompatibility = '21'
}

configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
}

bootJar {
    archiveFileName = 'app.jar'
}

repositories {
    mavenCentral()
}

dependencies {
    implementation 'org.springframework.boot:spring-boot-starter-data-jpa'
    implementation 'org.springframework.boot:spring-boot-starter-web'
    compileOnly 'org.projectlombok:lombok'
    runtimeOnly 'org.mariadb.jdbc:mariadb-java-client'
    annotationProcessor 'org.springframework.boot:spring-boot-configuration-processor'
    annotationProcessor 'org.projectlombok:lombok'
    testImplementation 'org.springframework.boot:spring-boot-starter-test'

    testImplementation 'org.spockframework:spock-core:2.4-M1-groovy-4.0'
    testImplementation 'org.spockframework:spock-spring:2.4-M1-groovy-4.0'

    // testcontainers
    testImplementation 'org.testcontainers:spock:1.19.7'
    testImplementation 'org.testcontainers:mariadb:1.19.7'
}

tasks.named('test') {
    useJUnitPlatform()
}

Docker - docker bind: an attempt was made to access a socket in a way forbidden by its access permissions. 오류 시

RichLegend — Fri, 29 Mar 2024 20:50:20 +0900

원인

사용하고자 하는 포트가 사용이 제한되었기 때문입니다.

해결 방법

powershell을 관리자 권한으로 열어서 아래 명령어를 입력하면 제한된 포트들 리스트들이 나옵니다.

netsh interface ipv4 show excludedportrange protocol=tcp

아래 순서대로 해주면 원하는 포트로 도커를 실행시킬 수 있습니다.

net stop winnat netsh int ipv4 add excludedportrange protocol=tcp startport=6379

numberofports=1
또는
netsh int ipv4 add excludedportrange protocol=tcp startport=6379 numberofports=1

set start winnat

docker ps 명령어로 도커 컨테이너가 잘 생성되었는지 확인할 수 있습니다.

Pycharm - Cannot connect to the Docker daemon at unix:///var/run/docker.sock 오류

RichLegend — Tue, 26 Mar 2024 13:27:14 +0900

해결 방법

터미널에서 아래 명령어를 실행합니다.

# {name}에는 자신이 macOS에 설정한 값을 넣는다.
sudo ln -s /Users/{name}/.docker/run/docker.sock /var/run/

AWS Cloudwatch - Log Insights 쿼리 예시 및 설명

RichLegend — Wed, 20 Mar 2024 16:36:45 +0900


# fields @timestamp, @message, @logStream, @log
fields @timestamp
| parse @message "* * [*] * - [*] [*] : *" as springProfile, appName, instanceId, logLevel, traceId, classPath, errorMessage
| filter logLevel = "ERROR"
| filter appName = "goods-service"
| filter traceId = "aaaaabbbbcccc123123"
| sort @timestamp desc
| limit 1000

@timestamp 필드를 출력으로 선택합니다.
@message 필드를 지정된 패턴에 따라 파싱하 springProfile, appName, instanceId, logLevel, traceId, classPath, errorMessage 필드로 분리합니다.
logLevel 필드를 "ERROR"로 필터링하여 오류 로그만 선택합니다.
appName 필드를 "goods-service"로 필터링하여 특정 어플리케이션 로그만 선택합니다.
traceId 필드를 "65fa77ba7e360da8f0ca7ae7ca81d965"로 필터링하여 특정 추적 ID를 가진 로그만 선택합니다.
@timestamp 필드를 내림차순으로 정렬합니다.
최대 1000개의 결과만 반환합니다.

Springdoc - use-fqn 설정으로 스웨거에서 Response 이름 충돌 문제 해결하기

RichLegend — Tue, 19 Mar 2024 09:16:47 +0900

스웨거 문서에서 Response 모델 이름이 충돌하여 발생하는 문제가 있을 수 있습니다.
Springdoc를 사용하여 간단하게 해결할 수 있습니다.

Springdoc는 스프링 부트 애플리케이션에서 OpenAPI 3.x 스펙을 지원하는 라이브러리입니다.
이를 사용하여 스웨거 문서를 생성하고 커스터마이징할 수 있습니다.
Springdoc를 사용하여 Response 이름 충돌 문제를 해결하는 방법에 대해 알아보겠습니다.

application.yml 설정하기: use-fqn 옵션을 true로 설정하여 Response 모델의 완전한 클래스 경로(Fully Qualified Name)를 사용하도록 설정합니다.
이를 통해 스웨거가 동일한 이름을 가진 모델을 구분할 수 있게 됩니다.

springdoc:
  use-fqn: true

위의 설정을 적용했을 때 Response 모델 이름이 충돌하지 않고 정확한 예시 값이 표시됩니다.

application.yml - springdoc 부분

springdoc:
  version: '1.6.13'
  api-docs:
    enabled: true
    path: /v3/api-docs
    groups:
      enabled: true
  swagger-ui:
    path: /swagger-ui.html
    tagsSorter: alpha
    use-root-path: true
    groups-order: desc
  cache:
    disabled: true
  use-fqn: true

JPA에서 @IdClass를 사용한 복합 주키 매핑

RichLegend — Fri, 15 Mar 2024 09:59:01 +0900

JPA에서 @IdClass를 사용한 복합 주키 매핑
자바 영속성 API(JPA)에서는 @IdClass 주석을 사용하여 복합 주키를 지정합니다.
이를 통해 엔터티 클래스와 별도로 기본 키 클래스를 정의할 수 있습니다.
예제를 통해 @IdClass를 사용하여 복합 주키 매핑하는 방법을 살펴보겠습니다.

엔터티 클래스: UserGroupMappingEntity

java
Copy code
import javax.persistence.*;

@Getter
@Setter
@ToString
@Entity
@Table(name = "user_group_mapping")
@IdClass(UserGroupMappingId.class)
public class UserGroupMappingEntity extends BaseEntity {

    @Id
    @Column(name = "user_group_id")
    private String userGroupId;

    @Id
    @Column(name = "user_id")
    private String userId;

    @Column(name = "user_group_name")
    private String userGroupName;

    private String description;
}

기본 키 클래스: UserGroupMappingId

java
Copy code
import java.io.Serializable;

@Getter
@Setter
@ToString
public class UserGroupMappingId implements Serializable {

    private String userGroupId;

    private String userId;
}

이 예제에서는:

UserGroupMappingEntity 클래스는 "user_group_mapping" 테이블에 매핑된 엔터티를 나타냅니다.
@IdClass(UserGroupMappingId.class)를 사용하여 UserGroupMappingId 클래스가 이 엔터티의 복합 기본 키를 포함한다는 것을 지정합니다.
UserGroupMappingId 클래스는 복합 기본 키 필드 userGroupId와 userId를 정의합니다.
UserGroupMappingEntity 클래스의 기본 키 필드는 @Id로 주석이 달려 있으며, 이는 이들이 복합 기본 키의 일부임을 나타냅니다.
UserGroupMappingEntity 클래스의 다른 필드는 테이블의 열에 매핑됩니다.

이 접근 방식을 사용하면 엔터티 모델에서 복합 기본 키를 깔끔하게 나타낼 수 있으며, 특히 기존 데이터베이스나 복합 기본 키가 있는 테이블과 작업할 때 유용합니다.

git flow 운영 정책

RichLegend — Wed, 6 Mar 2024 14:34:17 +0900

서버

dev : 개발 단계 확인
stage : QA 검수등의 사용자 테스트
prod : 운영

브랜치

feature : 담당자 기능 브랜치
develop : 개발 브랜치
stage : QA 검수등 테스트 브랜치
release : 배포 브랜치
- 일반적인 gitflow 에서는 develop 브랜치가 안정화 되었을때 생성하나, 배포시 브랜치 머지용도로 사용
master : 운영 브랜치

상품 git Flow

[1안]

기본 프로세스

feature → 개발 → PR → develop , release 머지
1. develop 머지 후 개발자 테스트 수행 중 변경사항 발생 시 위 프로세스(1번)와 동일 수행
release → stage, develop 머지
1. 만약, 개발자가 develop 머지 없이 release에만 머지를 수행할 경우를 대비하여 hook 설정
  1. hook 내용
    1. 로컬에서 release upstream 반영 시 develop에 커밋해쉬정보가 존재하는지 검증합니다.
    2. 위치 : 프로젝트/.git/hooks

[2안]

release를 develop과 stage 에 반영
릴리즈에 없는 내용이 develop이나 stage 에 반영 할 수 없음
1. feature를 release를 거치지 않고 올리거나, develop, stage 에서 직접 수정후 push 불가
develop 을 stage로 반영 할 수 없음
v2에 개발된 소스가 배포일자 변경등으로 v1에 포함되어야 하는 경우
1. v2 전체가 v1으로 포함되어도 되는경우
  1. v2에 v1을 pull 받아 싱크 맞추고 머지
2. v2 일부가 v1으로 포함되어야 하는 경우
  1. feature에 pull 받아 싱크 맞추고 release v1에 머지

→ 해당 머지과정에서 컨플릭트가 발생할 수 있음(base 브랜치가 다르므로), 발생 된 컨플릭트는 담당자가 해결 후 머지

v1에 올린 내용을 수정해야 할 경우 (스테이지 검수과정에서 변경 필요 시)
1. 해당 release 기준으로 피처를 재생성 및 기존 feature에 해당 release를 pull 받아서, 싱크 맞추고 변경 개발 수행

지라 티켓 관련

소스 변경이 필요한 작업은 티켓을 생성
QA 할 내용은 지라 release 에 티켓 추가
hotfix의 경우 선배포 후 티켓추가 가능

브랜치 생성 및 수행 기준

feature는 develop 기준으로 생성 (PR 수행)
stage는 release 머지
- 스테이지 = master 싱크로 배포할 내용만 머지함.
- 스테이지에는 release 한개의 브랜치만 머지함.
  - ex) 11월 7일 배포건 → release/v231107 → stage
  - ex) 11월 21일 배포건 → release/v231121 → stage
release는 stage 기준으로 생성
- 브랜치명 : release 티켓 명 (ex . v231026)
- 생성시점 : 배포일자 확정 즉시
- 머지 : feature → release
- release → stage 시 release → develop 동시 수행 필요
hotfix 는 master 기준으로 생성
- 케이스 긴급하게 수정후 바로 머지해야 할 경우
  - develop, master 머지
    - cf) gitFlow 사용 시 develop, master 동시 머지 됨.
- 케이스 당장 배포하지 않아도 되는 경우
  - PR 수행 후 develop, master 머지 ( PR 시 머지대상 브랜치는 master)

GitFlow 설명

feature

설명
- start feature : develop 기준으로 생성
- publish feature : upstream 반영
- finish feature : develop 머지
사용 예
- start feature → 개발 → publish feature → PR(비트버켓) → 머지

release

설명
- start release : develop 기준으로 생성
- publish release : push(upStream 반영)
- finish release : develop , master 머지
사용 예
- master 브랜치 기준 release/{릴리즈티켓명} 생성 후 push(upStream 반영)
- release/{릴리즈티켓명} 에 배포 내용 머지
- finish release : develop , master 머지 → 각 브랜치(develop , master) push → 배포

hotfix

설명
- start hotfix : master 기준으로 생성
- publish hotfix : push(upStream 반영)
- finish hotfix : develop , master 머지
사용 예
- start hotfix → publish hotfix → PR → finish hotfix → 각 브랜치(develop , master) push → 배포

ReflectionTestUtils를 사용하여 private 변수나 메소드(함수)를 테스트할 수 있습니다

RichLegend — Sun, 27 Aug 2023 12:40:57 +0900

ReflectionTestUtils

대상 Class

@Component
@Getter
public class ReflectionTestUtilsComponent {

    private int privateValue;

    private int privateMethod(int a, int b) {
        privateValue += a;
        privateValue += b;
        return privateValue;
    }
}

private 변수 테스트

형태

static void	setField(Class<?> targetClass, String name, Object value)

static void	setField(Class<?> targetClass, String name, Object value, Class<?> type)

static void	setField(Object targetObject, Class<?> targetClass, String name, Object value, Class<?> type)

static void	setField(Object targetObject, String name, Object value)

static void	setField(Object targetObject, String name, Object value, Class<?> type)

사용 예시

@Test
public void testPrivateValue() {
    ReflectionTestUtils.setField(reflectionTestUtilsComponent, "privateValue", 100);
    // ReflectionTestUtils.setField(대상 객체, "변수명", 원하는 값);

    Assertions.assertEquals(100, reflectionTestUtilsComponent.getPrivateValue());
}

private 메소드(함수) 테스트

형태

static <T> T	invokeMethod(Class<?> targetClass, String name, Object... args)

static <T> T	invokeMethod(Object targetObject, Class<?> targetClass, String name, Object... args)

static <T> T	invokeMethod(Object target, String name, Object... args)

사용 예시

@Test
public void testPrivateMethod() {
    ReflectionTestUtils.setField(reflectionTestUtilsComponent, "privateValue", 100);
    // ReflectionTestUtils.setField(대상 객체, "변수명", 원하는 값);

    Assertions.assertEquals(103, (Integer) ReflectionTestUtils.invokeMethod(reflectionTestUtilsComponent, "privateMethod", 1, 2));
    // ReflectionTestUtils.invokeMethod(대상 객체, "메소드(함수)명", 인자);

    Assertions.assertEquals(103, reflectionTestUtilsComponent.getPrivateValue());
}

Springboot 테스트 - p6spy 적용하는 방법

RichLegend — Sat, 19 Aug 2023 10:51:11 +0900

@Slf4j
@DisplayName("JPA 연결 테스트")
@Import(JpaConfig.class)
@ImportAutoConfiguration({DataSourceDecoratorAutoConfiguration.class, P6SpySqlFormatter.class})
@ActiveProfiles("local")

@Configuration
public class P6SpySqlFormatter {

    @PostConstruct
    public void setLogMessageFormat() {
        P6SpyOptions.getActiveInstance().setLogMessageFormat(P6spySqlFormatConfiguration.class.getName());
    }

    static public class P6spySqlFormatConfiguration implements MessageFormattingStrategy {

        // 표기에 허용되는 filter
        private static final String ALLOW_FILTER = "com.hanssem";

        @Override
        public String formatMessage(int connectionId, String now, long elapsed, String category, String prepared, String sql, String url) {

            sql = formatSql(category, sql);
            if (sql.trim().isEmpty()) { // sql 이 없다면 출력하지 않아도 됨
                return "";
            }

            // stack 을 구성하는 Format을 만든다
            return sql + createStack(connectionId, elapsed);
//            return sql + "\n\n";
        }

        private String formatSql(String category, String sql) {

            if (sql == null || sql.trim().isEmpty()) {
                return sql;
            }

            // Only format Statement, distinguish DDL And DML
            if (Category.STATEMENT.getName().equals(category)) {
                String tmpsql = sql.trim().toLowerCase(Locale.ROOT);
                if (tmpsql.startsWith("create") || tmpsql.startsWith("alter") || tmpsql.startsWith("comment")) {
                    sql = FormatStyle.DDL.getFormatter().format(sql);
                } else {
                    sql = FormatStyle.BASIC.getFormatter().format(sql);
                }

                sql = "|\n--------------------------------------" + sql;
            }

            return sql;
        }

        // stack 콘솔 표기
        private String createStack(int connectionId, long elapsed) {
            Stack<String> callStack = new Stack<>();
            StackTraceElement[] stackTrace = new Throwable().getStackTrace();

            for (StackTraceElement stackTraceElement : stackTrace) {
                String trace = stackTraceElement.toString();

                // trace 항목을 보고 내게 맞는 것만 필터
                if (trace.startsWith(ALLOW_FILTER)) {
                    callStack.push(trace);
                }
            }

            StringBuilder sb = new StringBuilder();
            int order = 1;
            while (!callStack.isEmpty()) {
                sb.append("\n\t\t").append(order++).append(".").append(callStack.pop());
            }

            return new StringBuffer().append("\n\tCall Stack:").append(sb)
                .append("\n--------------------------------------\n")
                .toString();
        }
    }
}

springboot 3.0 이상 p6spy 설정 (로깅이 안될 경우)

RichLegend — Wed, 16 Aug 2023 22:53:55 +0900

springboot 3.0 이상 p6spy 설정 (로깅이 안될 경우)

springboot가 업데이트되면서 p6spy의 쿼리 로깅이 잘 안되는 문제가 있습니다.

아래 추가 설정을 통해서 순서와 상관없이 진행을 하시면 해결이 됩니다.

단, 개발 환경에만 적용하기!

1. build.gradle 의존성 추가

implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.8.1'

2. [project]/src/main/resources/META-INF/spring 경로에 파일 추가

* 파일 경로 : /src/main/resources/META-INF/spring/

* 파일명 : org.springframework.boot.autoconfigure.AutoConfiguration.imports

* 파일 내용

com.github.gavlyukovskiy.boot.jdbc.decorator.DataSourceDecoratorAutoConfiguration

3. [project]/src/main/resources 경로에 파일 추가

* 파일 경로 : /src/main/resources/

* 파일명 : spy.properties

* 파일 내용

appender=com.p6spy.engine.spy.appender.Slf4JLogger

4. application.yml 에서 다른 쿼리 로그는 헷갈리지 않도록 안보이게 설정

5. p6spy 로그를 줄바꿈 formatting하여 가독성 높이기

* config 패키지에 P6spyLogMessageFormatConfiguration.java 생성

파일명은 상관없습니다. 파일 내용이 중요합니다.

@Configuration
public class P6spyLogMessageFormatConfiguration {

    @PostConstruct
    public void setLogMessageFormat() {
        P6SpyOptions.getActiveInstance().setLogMessageFormat(P6spySqlFormatConfiguration.class.getName());
    }

    static public class P6spySqlFormatConfiguration implements MessageFormattingStrategy {

        // 표기에 허용되는 filter
        private static final String ALLOW_FILTER = "com.creed";

        @Override
        public String formatMessage(int connectionId, String now, long elapsed, String category, String prepared, String sql, String url) {

            sql = formatSql(category, sql);
            if (sql.trim().isEmpty()) { // sql 이 없다면 출력하지 않아도 됨
                return "";
            }

            // stack 을 구성하는 Format을 만든다
            return sql + createStack(connectionId, elapsed);
        }

        private String formatSql(String category, String sql) {

            if (sql == null || sql.trim().equals("")) {
                return sql;
            }

            // Only format Statement, distinguish DDL And DML
            if (Category.STATEMENT.getName().equals(category)) {
                String tmpsql = sql.trim().toLowerCase(Locale.ROOT);
                if (tmpsql.startsWith("create") || tmpsql.startsWith("alter") || tmpsql.startsWith("comment")) {
                    sql = FormatStyle.DDL.getFormatter().format(sql);
                } else {
                    sql = FormatStyle.BASIC.getFormatter().format(sql);
                }
                sql = "|\nFormatSql(P6Spy sql, Hibernate format):" + sql;
            }

            return sql;
        }

        // stack 콘솔 표기
        private String createStack(int connectionId, long elapsed) {
            Stack<String> callStack = new Stack<>();
            StackTraceElement[] stackTrace = new Throwable().getStackTrace();

            for (StackTraceElement stackTraceElement : stackTrace) {
                String trace = stackTraceElement.toString();

                // trace 항목을 보고 내게 맞는 것만 필터
                if (trace.startsWith(ALLOW_FILTER)) {
                    callStack.push(trace);
                }
            }

            StringBuilder sb = new StringBuilder();
            int order = 1;
            while (callStack.size() != 0) {
                sb.append("\n\t\t").append(order++).append(".").append(callStack.pop());
            }

            return new StringBuffer().append("\n\n\tConnection ID: ").append(connectionId)
                    .append("\n\tExcution Time: ").append(elapsed).append("ms")
                    .append("\n\tCall Stack:").append(sb)
                    .append("\n--------------------------------------")
                    .toString();
        }
    }
}

springboot - SQL Binding 로깅 안되는 문제

RichLegend — Wed, 16 Aug 2023 22:27:06 +0900

application.yml

logging:
  level:    
    org.hibernate.orm.jdbc.bind: trace

org.hibernate.orm.jdbc.bind: trace

스프링부트 버젼 3.0.0 부터는 하이버네이트가 6.1.5로 버전업이 되면서 하이버네이트가 로깅하는 방식을 변경했습니다.

바인딩 잘 되는 것 확인!!

querydsl - @QueryProjection

RichLegend — Wed, 16 Aug 2023 22:05:46 +0900

public class MemberDto {
    private String name;
    private int age;

    @QueryProjection // 어노테이션 추가
    public MemberDto(String name, int age) {
        this.name = name;
        this.age = age;
    }
}


public void findDtoByQueryProjection() {
	queryFactory
		.select(new QMemberDto(member.name, member.age))
		.from(member)
		.fetch();
}

QDto로 생성된 생성자를 사용하는 방법
런타임 에러와 컴파일 에러 모두 잡을 수 있다.
하지만 DTO 특성상 전 계층(Service, Controller)에 데이터를 전달하기 위한 객체인데 모든 사용에서 Querydsl 의존성을 가지게 된다.

참고

https://velog.io/@daoh98/Querydsl-QuerydslPredicateExecutor-%EC%99%80-Querydsl-%EC%98%AC%EB%B0%94%EB%A5%B8-%EC%82%AC%EC%9A%A9%EB%B2%95

Springboot 3.0.0 이상 - Querydsl build.gradle 설정 및 NoClassDefFoundError 오류 대응 방법

RichLegend — Wed, 16 Aug 2023 20:15:46 +0900

1. build.gradle 에 의존성 추가 및 Q class 설정

// ************* 최상단
buildscript {
    ext {
        queryDslVersion = "5.0.0"
    }
}



// ************* 의존성 부분
// queryDSL 설정
    implementation "com.querydsl:querydsl-jpa:${queryDslVersion}:jakarta"
    implementation "com.querydsl:querydsl-core"
    implementation "com.querydsl:querydsl-collections"

    annotationProcessor "com.querydsl:querydsl-apt:${queryDslVersion}:jakarta" // querydsl JPAAnnotationProcessor 사용 지정
    annotationProcessor "jakarta.annotation:jakarta.annotation-api" // java.lang.NoClassDefFoundError (javax.annotation.Generated) 대응 코드
    annotationProcessor "jakarta.persistence:jakarta.persistence-api" // java.lang.NoClassDefFoundError (javax.annotation.Entity) 대응 코드



// ************* 하단
// Querydsl 설정부
def querydslDir = 'src/main/generated'

// querydsl QClass 파일 생성 위치를 지정
tasks.withType(JavaCompile) {
    options.getGeneratedSourceOutputDirectory().set(file(querydslDir))
}

// java source set 에 querydsl QClass 위치 추가
sourceSets {
    main.java.srcDirs += [querydslDir]
}

// gradle clean 시에 QClass 디렉토리 삭제
clean {
    delete file(querydslDir)
}

2. ".gitignore" 파일에 추가

/src/main/generated/

* 발생할 수 있는 오류들 해결

1. java.lang.NoClassDefFoundError:javax/persistence/Entity
2. attempt to recreate a file for type qclass
3. could not find class file for querydsl
4. Unable to load class 'javax.persistence.Entity'.

JUnit 테스트 시 "Sharing is only supported for boot loader classes because bootstrap classpath has been appended" 경고

RichLegend — Wed, 16 Aug 2023 17:39:01 +0900

JUnit 테스트 시

"Sharing is only supported for boot loader classes because bootstrap classpath has been appended" 경고

프로그램을 실행하는데 문제는 없지만 계속 경고가 떠서 신경이 쓰이는 문구였습니다.

구글링을 해본 결과를 모두 적용해 봤지만 모두 실패ㅠㅠ

1. (실패) 인텔리제이 -> Settings - Build, Execution, Deployment -> Debugger -> Async Stack Traces

또는 설정 - async 로 검색 -> Async Stack Traces 선택

Instrumenting agent (requires debugger restart) 체크박스 해제

2. (실패) Run/Debug Configurations -> Modify options -> "optimization" 타이핑 검색

Disable Launch optimization 체크

3. (성공!!) Run/Debug Configurations -> Edit configuration template -> JUnit -> VM options -> "-Xshre:off" 추가

이후에 모든 테스트에서 경고 메시지가 사라졌습니다!!

p6spy 쿼리 로그 - 멀티 라인으로

RichLegend — Tue, 28 Mar 2023 14:16:24 +0900

config에 2개의 파일 추가

package com.hanssem.remodeling.content.common.config;

import com.p6spy.engine.common.P6Util;
import com.p6spy.engine.logging.Category;
import com.p6spy.engine.spy.appender.MessageFormattingStrategy;
import org.hibernate.engine.jdbc.internal.FormatStyle;

import java.util.Arrays;
import java.util.List;
import java.util.Locale;
import java.util.Stack;

public class P6spySqlFormatConfiguration implements MessageFormattingStrategy {

    // 표기에 허용되지 않는 filter
    private List<String> DENIED_FILTER = Arrays.asList("Test1", this.getClass().getSimpleName());

    // 표기에 허용되는 filter
    private String ALLOW_FILTER = "com.hanssem";

    @Override
    public String formatMessage(int connectionId, String now, long elapsed, String category, String prepared, String sql, String url) {

        sql = formatSql(category, sql);
        if (sql.trim().isEmpty()) { // sql 이 없다면 출력하지 않아도 됨
            return "";
        }

        // stack 을 구성하는 Format을 만든다
        return sql + createStack(connectionId, elapsed);
    }

    private String formatSql(String category,String sql) {

        if (sql ==null || sql.trim().equals("")) return sql;

        // Only format Statement, distinguish DDL And DML
        if (Category.STATEMENT.getName().equals(category)) {
            String tmpsql = sql.trim().toLowerCase(Locale.ROOT);
            if (tmpsql.startsWith("create") || tmpsql.startsWith("alter") || tmpsql.startsWith("comment")) {
                sql = FormatStyle.DDL.getFormatter().format(sql);
            } else {
                sql = FormatStyle.BASIC.getFormatter().format(sql);
            }
            sql = "|\nFormatSql(P6Spy sql, Hibernate format):" + sql;
        }

        return sql;
    }

    // stack 콘솔 표기
    private String createStack(int connectionId, long elapsed) {
        Stack<String> callStack = new Stack<>();
        StackTraceElement[] stackTrace = new Throwable().getStackTrace();

        for (StackTraceElement stackTraceElement : stackTrace) {
            String trace = stackTraceElement.toString();

            // trace 항목을 보고 내게 맞는 것만 필터
            if (trace.startsWith(ALLOW_FILTER)) {
                callStack.push(trace);
            }
        }

        StringBuffer sb = new StringBuffer();
        int order = 1;
        while (callStack.size() != 0) {
            sb.append("\n\t\t" + (order++) + "." + callStack.pop());
        }

        return new StringBuffer().append("\n\n\tConnection ID:").append(connectionId)
                .append(" | Excution Time:").append(elapsed).append(" ms\n")
                .append("\n\tExcution Time:").append(elapsed).append(" ms\n")
                .append("\n\tCall Stack :").append(sb).append("\n")
                .append("\n--------------------------------------")
                .toString();
    }
}

P6spySqlFormatConfiguration.java

package com.hanssem.remodeling.content.common.config;

import com.p6spy.engine.spy.P6SpyOptions;
import org.springframework.context.annotation.Configuration;

import javax.annotation.PostConstruct;

@Configuration
public class P6spyLogMessageFormatConfiguration {

    @PostConstruct
    public void setLogMessageFormat() {
        P6SpyOptions.getActiveInstance().setLogMessageFormat(P6spySqlFormatConfiguration.class.getName());
    }
}

P6spyLogMessageFormatConfiguration.java

IntelliJ 에서 JUnit 테스트 - andExpect jsonPath 오류 시

RichLegend — Tue, 28 Mar 2023 14:10:51 +0900

수동으로 import 필요

import static org.hamcrest.Matchers.is;
import static org.springframework.test.web.servlet.result.MockMvcResultMatchers.jsonPath;

@Test
    @DisplayName("카카오 블로그 테스트")
    void testKakaoBlog() throws Exception {

        String url = "/api/v1/blog/search/kakao";

        BlogSearchRequest request = BlogSearchRequest.builder()
                .query("테스트")
                .sort("accuracy")
                .size(100)
                .page(1)
                .build();

        ResultActions resultActions = mockMvc.perform(
                get(url)
                        .param("page", "1")
                        .param("size", "20")
                        .param("query", "테스트")
                        .param("sort", "accuracy")
        );

        String expectByTitle = "title";

        // Then
        resultActions
                .andExpect(status().isOk())
                .andExpect(content().contentType(MediaType.APPLICATION_JSON))
//                .andExpect((ResultMatcher) jsonPath("$[0]").exists())
//                .andExpect(jsonPath(expectByTitle, "Kyeongho Yoo").exists())
//                .andExpect(jsonPath("$.length()", is(2)))
//                .andExpect(content().json(, ""))
//                .andExpect(jsonPath("$.data[0].content[0].blogName[0]", equalTo("엠오엠")))
//                .andExpect(jsonPath("$.nm", notNullValue())
//                .andExpect(jsonPath("$.nm", notNullValue())
//                .andExpect(jsonPath("$.title", is(aaa)))
//                .andExpect(jsonPath(new Matcher)))

                .andExpect(jsonPath("$.content[0].blogName", is("엠오엠")))
                .andExpect(jsonPath("$.content[1].blogName", is("지식센터")))
                .andExpect(jsonPath("$.content[1].blogName", notNullValue()))
                .andDo(print());
    }

Webflux - Webclient - header 복수개 적용 방법

RichLegend — Tue, 28 Mar 2023 14:07:56 +0900

private HttpHeaders createHeaders() {
        HttpHeaders headers = new HttpHeaders();

        headers.add("X-Naver-Client-Id", clientId);
        headers.add("X-Naver-Client-Secret", clientSecret);

        return headers;
    }

    @Bean
    public WebClient kakaoWebClient() {

        return WebClient.builder()
                .baseUrl(baseurl)
                .defaultHeaders((headers -> {headers.addAll(createHeaders());}))
                .build();
    }
}

Swagger - enum을 코드로 노출되도록 - @JsonValue 어노테이션

RichLegend — Tue, 28 Mar 2023 14:04:49 +0900

@Getter
@NoArgsConstructor
public enum ApiType {

    KAKAO("kakao", "카카오"),
    NAVER("naver", "네이버");

    private String code;
    private String name;

    ApiType(String code, String name) {
        this.code = code;
        this.name = name;
    }

    @JsonValue
    public String getCode() {
        return code;
    }

    public String getName() {
        return name;
    }

    public static ApiType code(String code){
        switch (code){
            case "kakao" :
                return KAKAO;
            case "naver" :
                return NAVER;
            default:
                return KAKAO;
        }
    }

    @Override
    public String toString() {
        return code;
    }
}

@JsonValue 어노테이션을 붙여줘야 Swagger에서 code로 나온다.

IntelliJ 실행 시 Address already in use: bind 오류가 날 때

RichLegend — Thu, 9 Mar 2023 14:23:21 +0900

cmd 관리자 모드 실행 후

net stop winnat
net start winnat

remote 저장소 push할 때 reject 오류 조치방법

RichLegend — Wed, 8 Mar 2023 13:53:03 +0900

오류 내용

Push to origin/master was rejected

GitHub에서 Readme를 포함시켜 Repository를 생성한 후, 해당 Repository를 remote로 추가하여 push 하니 생긴 오류.

Repository에 Readme파일이 이미 존재하여 생기는 오류

1. 동기화를 위해 pull

git pull --rebase origin main

2. 강제로 push

git push origin +main

pull 이전에 발생한 변경사항을 무시(삭제)하고 현재 작업 내용을 강제로 push해도 된다.
이 경우 pull 되지 않은 변경사항은 소실되기 때문에 주의해야 함.

나의 경우에는 README를 건드렸던게 중요하지 않았어서 강제로 push했다.

(나의 경우는 동기화 pull후 다시 push했다.)

깃허브에서 확인해보면 해당 README의 변경사항은 사라졌고, 그외 작업내용들은 정상적으로 업로드되었음을 확인할 수 있다.

p6spy 멀티라인 Formatter 적용

RichLegend — Tue, 7 Mar 2023 16:17:22 +0900

1. config에 2개의 파일 생성

P6spyLogMessageFormatConfiguration.java
P6spySqlFormatConfiguration.java

2. P6spySqlFormatConfiguration.java

package com.hanssem.remodeling.content.common.config;

import com.p6spy.engine.common.P6Util;
import com.p6spy.engine.logging.Category;
import com.p6spy.engine.spy.appender.MessageFormattingStrategy;
import org.hibernate.engine.jdbc.internal.FormatStyle;

import java.util.Arrays;
import java.util.List;
import java.util.Locale;
import java.util.Stack;

public class P6spySqlFormatConfiguration implements MessageFormattingStrategy {

    // 표기에 허용되지 않는 filter
    private List<String> DENIED_FILTER = Arrays.asList("Test1", this.getClass().getSimpleName());

    // 표기에 허용되는 filter
    private String ALLOW_FILTER = "com.hanssem";

    @Override
    public String formatMessage(int connectionId, String now, long elapsed, String category, String prepared, String sql, String url) {

        sql = formatSql(category, sql);
        if (sql.trim().isEmpty()) { // sql 이 없다면 출력하지 않아도 됨
            return "";
        }

        // stack 을 구성하는 Format을 만든다
        return sql + createStack(connectionId, elapsed);
    }

    private String formatSql(String category,String sql) {

        if (sql ==null || sql.trim().equals("")) return sql;

        // Only format Statement, distinguish DDL And DML
        if (Category.STATEMENT.getName().equals(category)) {
            String tmpsql = sql.trim().toLowerCase(Locale.ROOT);
            if (tmpsql.startsWith("create") || tmpsql.startsWith("alter") || tmpsql.startsWith("comment")) {
                sql = FormatStyle.DDL.getFormatter().format(sql);
            } else {
                sql = FormatStyle.BASIC.getFormatter().format(sql);
            }
            sql = "|\nFormatSql(P6Spy sql, Hibernate format):" + sql;
        }

        return sql;
    }

    // stack 콘솔 표기
    private String createStack(int connectionId, long elapsed) {
        Stack<String> callStack = new Stack<>();
        StackTraceElement[] stackTrace = new Throwable().getStackTrace();

        for (StackTraceElement stackTraceElement : stackTrace) {
            String trace = stackTraceElement.toString();

            // trace 항목을 보고 내게 맞는 것만 필터
            if (trace.startsWith(ALLOW_FILTER)) {
                callStack.push(trace);
            }
        }

        StringBuffer sb = new StringBuffer();
        int order = 1;
        while (callStack.size() != 0) {
            sb.append("\n\t\t" + (order++) + "." + callStack.pop());
        }

        return new StringBuffer().append("\n\n\tConnection ID:").append(connectionId)
                .append(" | Excution Time:").append(elapsed).append(" ms\n")
                .append("\n\tExcution Time:").append(elapsed).append(" ms\n")
                .append("\n\tCall Stack :").append(sb).append("\n")
                .append("\n--------------------------------------")
                .toString();
    }
}

3. P6spyLogMessageFormatConfiguration.java

package com.hanssem.remodeling.content.common.config;

import com.p6spy.engine.spy.P6SpyOptions;
import org.springframework.context.annotation.Configuration;

import javax.annotation.PostConstruct;

@Configuration
public class P6spyLogMessageFormatConfiguration {

    @PostConstruct
    public void setLogMessageFormat() {
        P6SpyOptions.getActiveInstance().setLogMessageFormat(P6spySqlFormatConfiguration.class.getName());
    }
}

build.gradle

RichLegend — Tue, 7 Mar 2023 16:16:14 +0900

[Gradle]

Gradle은 일종의 빌드 도구
- 여기서 말하는 빌드란 개발한 소프트웨어가 제품으로 만들어지는 일련의 과정
- 컴파일, 테스트, 배포, 문서화 등의 작업을 포함하는 절차
- 이 때 빌드의 모든 과정을 자동으로 처리할 수 있도록 도와주는 것을 빌드 도구라고 함
- 최근 대세는 Gradle
Groovy, DSL(Domain-Specific Languages, 도메인 특화 언어)
- Gradle은 groovy라는 JVM 기반의 동적 타이핑 언어를 통해 기술된다.
- Gradle은 groovy 문법 자체를 그대로 이용하지는 않고, 그루비 기반의 DSL을 사용
- DSL = 도메인 고유 언어 (기반이 되는 언어에서 파생되어 특정한 용도에 한정되어 각색한 언어)
- Gradle에 사용되는 언어는 그루비를 기반으로 작성된 Gradle DSL

[build.gradle]

build.gradle은 gradle에서 빌드 작업에 필요한 기본 설정, 동작 등을 정의하는 파일
build.gradle 파일 자체가 Project 클래스로, Project 인터페이스를 구현하는 구현체
build.gradle에 작성하는 코드들은 모두 Project 오브젝트의 프로퍼티와 메서드가 되며 Project 오브젝트는 프로젝트 이름, 변수, 메서드를 모두 포함하는 객체가 된다.
Project 오브젝트는 내부에 수많은 메서드(Methods)와 속성(Properties)을 가지고 있다. 메서드 중에 대표적인 것은 모든 java application용 build.gradle이 가진 plugins, repositories, dependencies, application 메서드이다. 우리가 Gradle Task를 이용해 java application을 빌드하게 되면 build task는 이 메서드들을 수행시킨다.

plugins

프로젝트 컴파일이나 jar 파일의 생성 작업들을 해주는 플러그인 지정
플러그인에는 빌드에 필요한 과정들을 task로 포함
빌드 시 필요한 모든 과정을 플러그인의 내부 task가 진행해줌

dependencies

의존성에 관한 설정을 관리하는 프로퍼티
프로젝트에서 필요한 라이브러리를 등록
여기에 필요한 라이브러리 등의 정보를 기술하면 그 라이브러리를 참조할 수 있음
라이브러리 지정 시 “그룹:이름:버전” 형태 사용

ext

이 블록은 gradle의 모든 task에서 사용할 수 있는 일종의 전역 변수를 선언하는 블록
gradle 에서 지원하는 변수
이 변수를 이용하여 추가 속성을 정의할 수 있다.
추가 속성은 모든 모듈에 공유가 가능하다.
변수선언을 진행한 다음 진행해야 한다.
프로젝트 전체와 서브 프로젝트에서도 접근 가능하다.
ext 메소드는 그 인자를 buildScript 에서 전역변수로 사용하기 위해 사용되는 메소드이다.

ext.javaVersion = '1.7' // 한개씩 선언
ext {
    // 여러개 한꺼번에 선언
    springVersion = '3.1.0.RELEASE'
    emailNotification = 'build@master.org'
}
 
// 가변 Key, 가변 값 형태로 코드를 통해 프라퍼티를 추가할 때는 아래 방식을 사용한다.
project.ext['keyname'] = 'value'

def

변수에 형을 생략할 때 사용
형 지정을 생략할 때 def 키워드 이용
def를 지정하는 것은 자바에서 Object 형을 지정한 것과 같음
gradle 에서 지원하는 지역변수
해당 스크립트에서만 사용할 수 있다.

* 형 생략
String message = 'hi'
def message = 'hi'
Groovy는 def라는 키워드를 이용하여 모든 타입의 변수를 선언할 수 있습니다.
반대로 형을 지정하여 생성하는 방법도 가능합니다. 위 두줄의 코드는 같은 결과를 발생시킵니다.

buildscript

빌드하는 동안 필요한 처리들을 모아놓는 곳

sourceSets

Gradle에서는 하나의 Source 디렉토리만 지원을 해줌 (src/main/java)
sourceSets는 이러한 제약사항을 지원하기 위해 사용
Java 소스와 리소스 파일의 논리적인 그룹
하나 이상의 Source 디렉토리를 Gradle에서 처리를 하기 위해 sourceSets 에 Source 디렉토리를 등록해주면 된다.
기본 프로젝트 레이아웃
통합 테스트를 위한 별도의 소스 디렉토리를 만들 경우

위의 경우 sourceSets 셋팅 (폴더가 새 소스세트의 이름과 일치하면 따로 명시할 필요 없음)

따로 명시할 경우 아래와 같음

**// 1. queryDsl version 정보 추가**
buildscript { **// 빌드 시**
    ext {
        **queryDslVersion = "5.0.0" // 빌드 시 전역변수 설정**
    }
}

plugins {
    id 'org.springframework.boot' version '2.6.3'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    **// 2. querydsl plugins 추가
    id "com.ewerk.gradle.plugins.querydsl" version "1.0.10"**
    id 'java'
}

//...

dependencies { **// 멀티모듈에서 공통으로 사용될 의존성 추가**
    **// 3. querydsl library dependencies 추가
    implementation "com.querydsl:querydsl-jpa:${queryDslVersion}"
    implementation "com.querydsl:querydsl-apt:${queryDslVersion}"**
    //...
}

test {
    useJUnitPlatform()
}

**/*
 * queryDSL 설정 추가
 */
// querydsl에서 사용할 경로 설정
def querydslDir = "$buildDir/generated/querydsl"

// JPA 사용 여부와 사용할 경로를 설정
querydsl {
    jpa = true
    querydslSourcesDir = querydslDir
}

// build 시 사용할 sourceSet 추가
// IDE의 소스 폴더에 자동으로 넣어준다.
// 개발 환경에서 생성된 Q파일들을 사용할 수 있도록 generated 디렉토리를 sourceSet에 추가해주면 개발 코드에서 생성된 Q파일에 접근할 수 있습니다.
sourceSets {
    main.java.srcDir querydslDir
}

// querydsl 컴파일시 사용할 옵션 설정
// Q파일을 생성해준다.
compileQuerydsl{
    options.annotationProcessorPath = configurations.querydsl
}

// querydsl 이 compileClassPath 를 상속하도록 설정
// 컴파일이 될때 같이 수행
configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
    querydsl.extendsFrom compileClasspath
}**

JPA (Java Persistence API)

RichLegend — Tue, 7 Mar 2023 16:13:32 +0900

JPA (Java Persistence API)

ORM

ORM (Object-Relational Mapping)
애플리케이션 Class와 RDB(Relational DataBase)의 테이블을 매핑 (연결)
어플리케이션의 객체를 RDB 테이블에 자동으로 영속화
객체는 객체대로 설계하고, 관계형 데이터베이스는 관계형 데이터베이스대로 설계한다.
ORM 프레임워크가 중간에서 매핑해 준다.
대중적인 언어에는 대부분 ORM 기술이 존재한다.

ORM 장점

SQL문이 아닌 Method를 통해 DB를 조작할 수 있어, 개발자는 객체 모델을 이용하여 비즈니스 로직을 구성하는데만 집중할 수 있음
- 내부적으로는 쿼리를 생성하여 DB를 조작함
- 하지만 개발자가 이를 신경 쓰지 않아도 됨
Query와 같이 필요한 선언문, 할당 등의 부수적인 코드가 줄어들어 각종 객체에 대한 코드를 별도로 작성하여 코드의 가독성을 높임
객체지향적인 코드 작성이 가능함. 오직 객체지향적 접근만 고려하면 되기때문에 생산성 증가
매핑하는 정보가 Class로 명시 되었기 때문에 ERD를 보는 의존도를 낮출 수 있고 유지보수 및 리팩토링에 유리
기존 방식에서 MySQL 데이터베이스를 사용하다가 ORACLE로 변환한다고 가정해보면, 새로 쿼리를 짜야하는 경우가 생김. 이런 경우에 ORM을 사용한다면 쿼리를 수정할 필요가 없음

ORM 단점

프로젝트의 규모가 크고 복잡하여 설계가 잘못된 경우, 속도 저하 및 일관성을 무너뜨리는 문제점이 생길 수 있음
복잡하고 무거운 Query는 속도를 위해 별도의 튜닝이 필요하기 때문에 결국 SQL문을 써야할 수도 있음

ORM과 SQL Mapper와의 차이점

1. SQL Mapper

myBatis, jdbcTemplate
SQL을 명시하여 직접 DB 조작
필드를 매핑시키는 것이 목적
자바 클래스와 sql을 매핑

2. ORM

JPA, Hibernate
자바 클래스와 DB 테이블을 매핑
객체간의 관계를 바탕으로 SQL 자동 생성
RDB의 관계를 Object 에 반영하는 것이 목적

JPA

JPA(Java Persistence API)
JPA는 자바 진영에서 ORM(Object-Relational Mapping) 기술 표준으로 사용되는 인터페이스의 모음
JPA를 구현한 대표적인 오픈소스로는 Hibernate가 있음
자바 어플리케이션에서 관계형 데이터베이스를 사용하는 방식을 정의한 인터페이스
JPA는 API의 규격 인터페이스일 뿐 (라이브러리나 프레임워크가 아님)
JPA 2.1 표준 명세를 구현한 구현체 : Hibernate, EclipseLink, DataNucleus, OpenJPA, TopLink Essentials 등이 있다. (ORM 프레임워크)

JPA 는 애플리케이션과 JDBC 사이에서 동작하여 개발자가 JPA 를 사용하면, JPA 내부에서 JDBC API 를 사용하여 SQL 을 호출, DB 와 통신한다.

왜 JPA를 사용해야 할까?

1. 생산성

JPA를 사용하면 자바 컬렉션에 저장하듯이 JPA에게 저장할 객체를 전달하면 된다.
지루하고 반복적인 코드를 개발자가 직접 작성하지 않아도 되며, DDL문도 자동으로 생성해주기 때문에 데이터베이스 설계 중심을 객체 설계 중심으로 변경할 수 있다.

2. 유지보수

필드를 하나만 추가해도 관련된 SQL과 JDBC 코드를 전부 수행해야 했지만 JPA는 이를 대신 처리해주기 때문에 개발자가 유지보수해야하는 코드가 줄어든다.
SQL을 직접 작성하는 것이 아닌, 객체를 사용하여 동작 -> 재사용성 up
기존 SQL 방식 : 테이블 필드 변경시 모든 SQL을 수정해야 한다.
JPA 방식 : Entity 객체에 필드만 추가하면 된다.

3. 패러다임의 불일치 해결

JPA는 연관된 객체를 사용하는 시점에 SQL을 전달할 수 있고, 같은 트랜잭션 내에서 조회할 때 동일성도 보장하기 때문에 다양한 패러다임의 불일치를 해결한다.

4. 성능

애플리케이션과 데이터베이스 사이에서 성능 최적화 기회를 제공한다.
같은 트랜잭션안에서는 같은 엔티티를 반환하기 때문에 데이터 베이스와의 통신 횟수를 줄일 수 있다.
트랜잭션을 commit하기 전까지 메모리에 쌓고 한번에 SQL을 전송한다.

5. 데이터 접근 추상화와 벤더 독립성

RDB는 같은 기능이라도 벤더마다 사용법이 다르기 때문에 처음 선택한 데이터베이스에 종속되고 변경이 어렵다. JPA는 애플리케이션과 데이터베이스 사이에서 추상화된 데이터 접근을 제공하기 때문에 종속이 되지 않도록한다.
만약 DB가 변경되더라도 JPA에게 알려주면 간단하게 변경이 가능하다.

JPA와 객체 그래프 탐색

신뢰할 수 있는 엔티티, 계층

class MemberService {
	...
    public void process(){
    	// 기존 방식처럼 직접 구현한 DAO에서 객체를 가져온 경우
    	Member member1 = memberDAO.find(memberId);
        member1.getTeam(); // 엔티티를 신뢰할 수 없음
        member1.getOrder().getDelivery();
        
        // JPA를 통해서 객체를 가져온 경우
        Member member2 = jpa.find(Member.class, memberId);
        member2.getTeam(); // 자유로운 객체 그래프 탐색
        member2.getOrder().getDelivery();    
    }
}

내가 아닌 다른 개발자가 직접 구현한 DAO에서 가져오는 경우
- DAO에서 직접 어떤 쿼리를 날렸는지 확인하지 않는 이상, 그래프 형태의 관련된 객체들을 모두 잘 가져왔는지 알 수 가 없다.
- 즉, 반환한 엔티티를 신뢰하고 사용할 수 없다.
JPA를 통해서 가져오는 경우
- 객체 그래프를 완전히 자유롭게 탐색할 수 있게 된다.
- 동일한 트랜잭션에서 조회한 엔티티는 같음을 보장한다.

JPA의 성능 최적화 기능

1. 1차 캐시와 동일성(identity) 보장 - 캐싱 기능

같은 트랜잭션 안에서는 같은 엔티티를 반환 - 조회 성능 향상
동일 조건인 경우 쿼리를 2번 실행하지 않고, 캐시에서 읽어들임

String memberId = "100";
Member member1 = jpa.find(Member.class, memberId);  // DB에서 가져옴
Member member2 = jpa.find(Member.class, memberId);  // 1차 캐시에서 가져옴
member1 == member2;  // 같다

2. 트랜잭션을 지원하는 쓰기 지연 (transactional write-behind) - 버퍼링 기능

(1) INSERT

// 1. 트랜잭션을 커밋할 때까지 INSERT 쿼리를 수행하지 않음
transaction.begin();	// 트랜잭션 시작
em.persist(memberA);
em.persist(memberB);
em.persist(memberC);

// 2. 커밋하는 순간 데이터베이스에 INSERT 쿼리를 일괄 처리한다.
// JDBC BATCH SQL 기능을 사용해서 한번에 SQL 전송
transaction.commit();	// 트랜잭션 커밋

(2) UPDATE

// 1. UPDATE, DELETE로 인한 로우 락(ROW LOCK) 시간 최소화
transaction.begin();	// 트랜잭션 시작
changeMember(memberA);
deleteMember(memberB);

비즈니스_로직_수행();	// 비즈니스 로직 수행하는 동안 DB 로우 락이 걸리지 않는다.

// 커밋하는 순간 데이터베이스에 UPDATE, DELETE 쿼리를 보내고 바로 커밋
transaction.commit();	// 트랜잭션 커밋

3. 지연 로딩(Lazy Loading)

(a) 지연 로딩

객체가 실제로 사용될 때 로딩하는 전략

(b) 즉시 로딩

JOIN 쿼리로 한번에 연관된 객체까지 미리 조회하는 전략

어플리케이션 개발시 기본적으로 지연 로딩을 설정한 후 필요한 경우에 즉시 로딩으로 옵션을 변경하는 것을 추천한다.

상속 관계

JAVA에서는 부모클래스와 자식클래스의 관계 즉, 상속관계가 존재하는데 데이터베이스에서는 이러한 객체의 상속관계를 지원하지 않는다. 이런 상속관계를 JPA는 아래와 같은 방식으로 해결하였다.

위의 구조에서 만약 Album 클래스를 저장한다고 가정해보자.

// Album 객체저장
jpa.persist(album);

그러면 JPA는 위의 코드를 아래의 쿼리로 변환해서 실행한다.

INSERT INTO ITEM (ID, NAME, PRICE) .....
INSERT INTO ALBUM (ARTIST) .....

위처럼 저장하면 당연히 조회할때도 두 테이블을 엮어서 가져올 것이다. 조회하는 JAVA코드와 변환되는 쿼리를 보도록하자.

// JAVA 코드
String albumId = "id100";
Album album = jpa.find(Album.class, albumId);

// 변환된 쿼리
SELECT I.*, A.*
  FROM ITEM I
  JOIN ALBUM A ON I.ITEM_ID = A.ITEM_ID

연관 관계

위와 같이 상속관계에 대한 접근도 제공해주는데 객체지향에는 연관관계라는 것도 있다.
코드로 따지면 Class에서 또 다른 Class Type을 필드 변수로 가지고 있는것이다.
객체관계와 이를 테이블 구조로 나타낸 아래의 그림을 보도록하자.

위의 그림은 Member 클래스가 Team 타입의 team 필드 변수를 가지고 있는 형태인데, 코드로 나타내면 아래와 같다.

class Member {
 String id;
 Team team;
 String username;
}

class Team {
 Long id;
 String name;
}

그렇다면 Team 객체를 참조하는 필드를 가지고 있는 Member 객체는 어떻게 저장할까?

Member member = new Member();
member.setId("100");
member.setUsername("dbjh");

Team team = new Team();
team.setName("dev_team");

member.setTeam(team);
jpa.persist(member);

위처럼 Member 객체의 team 필드에 Team 객체를 set하고 Member 객체를 DB에 저장하게 되면 JPA는 아래와 같은 코드를 데이터베이스에게 실행하라고 할것이다.

INSERT INTO MEMBER (ID, TEAM_ID, USERNAME) ....
INSERT INTO TEAM (ID, NAME) ....

이렇게 저장 후 Member 객체만 조회하면, Team 객체 정보도 가져와서 Member 객체의 team필드에 주입해주기 때문에 아래와 같이 사용할 수 있다.

// JAVA 코드
Member member = jpa.find(Member.class, memberId);
Team team = member.getTeam();

// 변환된 쿼리
SELECT M.*, T.*
 FROM MEMBER M
 JOIN TEAM T ON M.TEAM_ID = T.TEAM_ID

위와 같은 구조들이 더 복잡해진다고 해도 JPA는 이를 모두 지원해주기 때문에 문제없이 사용할 수 있다.

JPA의 저장 및 조회는 아래와 같은 구조로 실행

**저장** : jpa.persist(member)

**조회** : Member member = jpa.find(memberId)

**수정** : member.setName("홍길동")

**삭제** : jpa.remove(member)

[저장]

MemberDAO에서 객체를 저장하고 싶을 때 개발자는 JPA에 Member 객체를 넘기면 JPA는 아래와 같이 동작한다.

Member 엔티티를 분석한다.
INSERT SQL을 생성한다.
JDBC API를 사용하여 SQL을 DB 에 날린다.

[조회]

Member 객체를 조회하고 싶을 때 개발자는 member의 pk 값을 JPA에 넘긴다.

엔티티의 매핑 정보를 바탕으로 적절한 SELECT SQL을 생성한다.
JDBC API를 사용하여 SQL을 DB에 날린다.
DB로 부터 결과를 받아온다.
결과(ResultSet)를 객체에 매핑한다.

쿼리를 JPA가 만들어 주기 때문에 Object와 RDB간의 패러다임 불일치를 해결 할 수 있다.

[수정]

JPA는 데이터 수정시, 매핑된 객체(테이블 데이터)를 조회해서 값을 변경 후 커밋하면 DB 서버에 UPDATE 문을 전송하여 UPDATE를 실행

Querydsl 스터디

RichLegend — Tue, 7 Mar 2023 16:06:46 +0900

1. 참고 페이지

Querydsl 공식 사이트

Querydsl - Unified Queries for Java

Querydsl Reference Guide

Querydsl 5.0.0 API

Querydsl 관련 소스

GitHub - lcalmsky/querydsl

2. Querydsl 특징

(1) Querydsl의 특징

Spring Data JPA가 기본적으로 제공해주는 CRUD 메서드 및 쿼리 메서드 기능을 사용하더라도, 원하는 조건의 데이터를 수집하기 위해서는 필연적으로 JPQL을 작성하게 됩니다. 간단한 로직을 작성하는데 큰 문제는 없으나, 복잡한 로직의 경우 개행이 포함된 쿼리 문자열이 상당히 길어집니다.

JPQL 문자열에 오타 혹은 문법적인 오류가 존재하는 경우, 정적 쿼리라면 어플리케이션 로딩 시점에 이를 발견할 수 있으나 그 외는 런타임 시점에서 에러가 발생합니다.

이러한 문제를 어느 정도 해소하는데 기여하는 프레임워크가 바로 QueryDSL입니다. QueryDSL은 정적 타입을 이용해서 SQL 등의 쿼리를 생성해주는 오픈소스 프레임워크입니다.

(2) QueryDSL의 장점

문자가 아닌 코드로 쿼리를 작성함으로써, 컴파일 시점에 문법 오류를 쉽게 확인할 수 있다.
자동 완성 등 IDE의 도움을 받을 수 있다.
동적인 쿼리 작성이 편리하다.
1. 물론 한계가 있어서 통계성 쿼리 등은 natvie 쿼리 등으로 해결해야한다.
쿼리 작성 시 제약 조건 등을 메서드 추출을 통해 재사용할 수 있다.

(3) Querydsl 작동 방식

기본적으로 QueryDSL은 프로젝트 내의 @Entity 어노테이션을 선언한 클래스를 탐색하고, JPAAnnotationProcessor를 사용해 Q 클래스를 생성합니다.
querydsl-apt가 @Entity 및 @Id 등의 애너테이션을 알 수 있도록, javax.persistence과 javax.annotation을 annotationProcessor에 함께 추가합니다.
- annotationProcessor는 Java 컴파일러 플러그인으로서, 컴파일 단계에서 어노테이션을 분석 및 처리함으로써 추가적인 파일을 생성할 수 있습니다.
build 폴더는 gradle에 의해 gitignore 처리된다.
- Qfile 등은 시스템이 자동으로 만들어주는 형태이고, 버전마다 조금씩 달라질 수 있기 때문에 git으로 형상관리를 하지는 않는다.
- 혹시나 src/main/generated에 들어가게 된다면, 해당 파일들은 gitignore 해줘야함도 기억하자

(4) Querydsl 관련 라이브러리

apt 라는 부분이 코드 생성과 관련된 라이브러리라고 한다.
QHello 등의 객체를 만들어주는 역할을 한다.
core, jpa 부분은 실제 querydsl의 코드를 작동하게 해주는 selectFrom.fetchOne 등의 작동을 담당하는 라이브러리

(5) 기타

Querydsl fetchResults(), fetchCount() Deprecated(향후 미지원)
- Querydsl은 향후 fetchCount() , fetchResult() 를 지원하지 않기로 결정했다.

3. Querydsl 설정 방법

공식 문서에는 Gradle에 대한 내용이 누락되어 있으며, 실제로 QueryDSL 설정 방법은 Gradle 및 IntelliJ 버전에 따라 상이

(1) gradle.build

**// 1. queryDsl version 정보 추가**
buildscript {
    ext {
        **queryDslVersion = "5.0.0"**
    }
}

plugins {
    id 'org.springframework.boot' version '2.6.3'
    id 'io.spring.dependency-management' version '1.0.11.RELEASE'
    **// 2. querydsl plugins 추가
    id "com.ewerk.gradle.plugins.querydsl" version "1.0.10"**
    id 'java'
}

//...

dependencies {
    **// 3. querydsl library dependencies 추가
    implementation "com.querydsl:querydsl-jpa:${queryDslVersion}"
    implementation "com.querydsl:querydsl-apt:${queryDslVersion}"**
    //...
}

test {
    useJUnitPlatform()
}

**/*
 * queryDSL 설정 추가
 */
// querydsl에서 사용할 경로 설정
def querydslDir = "$buildDir/generated/querydsl"

// JPA 사용 여부와 사용할 경로를 설정
querydsl {
    jpa = true
    querydslSourcesDir = querydslDir
}

// build 시 사용할 sourceSet 추가
// IDE의 소스 폴더에 자동으로 넣어준다.
// 개발 환경에서 생성된 Q파일들을 사용할 수 있도록 generated 디렉토리를 sourceSet에 추가해주면 개발 코드에서 생성된 Q파일에 접근할 수 있습니다.
sourceSets {
    main.java.srcDir querydslDir
}

// querydsl 컴파일시 사용할 옵션 설정
// Q파일을 생성해준다.
compileQuerydsl{
    options.annotationProcessorPath = configurations.querydsl
}

// querydsl 이 compileClassPath 를 상속하도록 설정
// 컴파일이 될때 같이 수행
configurations {
    compileOnly {
        extendsFrom annotationProcessor
    }
    querydsl.extendsFrom compileClasspath
}**

(2) compileQuerydsl 실행

Gradle Tasks -> compileQuerydsl 을 실행

또는 명령어를 이용하여 Querydsl query type 생성

./gradlew clean compileQuerydsl

(3) Querydsl Build 결과 확인

BUILD SUCCESSFUL 을 확인하였다면 build/generated/querydsl 경로에 Project Entity 들의 QClass 가 생성된 것을 확인할 수 있다.
프로젝트 하위 디렉토리 중 build/generated/querydsl 여기 진입하면 아까 생성한 Item Entity 가 QItem 으로 변해있는 것을 확인할 수 있습니다.
$projectDir/build/generated 디렉토리 하위에 Entity로 등록한 클래스들이 Q라는 접두사가 붙은 형태로 생성되었습니다.
이러한 클래스들을 Q 클래스 혹은 Q(쿼리) 타입이라고 합니다.
- QueryDSL로 쿼리를 작성할 때, Q 클래스를 사용함으로써 쿼리를 Type-Safe하게 작성할 수 있습니다.
git으로 소스 코드를 관리할 땐 반드시 해당 경로를 무시하도록 처리해주셔야 합니다.
QItem.java 파일을 열어보면

package io.lcalmsky.querydsl.domain;

import static com.querydsl.core.types.PathMetadataFactory.*;

import com.querydsl.core.types.dsl.*;

import com.querydsl.core.types.PathMetadata;
import javax.annotation.Generated;
import com.querydsl.core.types.Path;

@Generated("com.querydsl.codegen.EntitySerializer")
public class QItem extends EntityPathBase<Item> {

    private static final long serialVersionUID = 1540314452L;

    public static final QItem item = new QItem("item");

    public final NumberPath<Long> id = createNumber("id", Long.class);

    public QItem(String variable) {
        super(Item.class, forVariable(variable));
    }

    public QItem(Path<? extends Item> path) {
        super(path.getType(), path.getMetadata());
    }

    public QItem(PathMetadata metadata) {
        super(Item.class, metadata);
    }
}

(4) Querydsl 정상 동작 테스트

그럼 Querydsl 을 이용해 정상적으로 쿼리를 수행하는지 확인해보겠습니다.

package io.lcalmsky.querydsl.domain;

import com.querydsl.jpa.impl.JPAQueryFactory;
import org.junit.jupiter.api.Test;
import org.springframework.beans.factory.annotation.Autowired;
import org.springframework.boot.test.context.SpringBootTest;

import javax.persistence.EntityManager;
import org.springframework.transaction.annotation.Transactional;;

import static org.junit.jupiter.api.Assertions.assertEquals;

@SpringBootTest
@Transactional
class ItemTest {
    @Autowired
    EntityManager entityManager;

    @Test
    void test() {
        // given
        Item item = new Item();
        entityManager.persist(item);

        // when
        JPAQueryFactory queryFactory = new JPAQueryFactory(entityManager); // (1)
        QItem qItem = new QItem("i"); // (2)
        Item found = queryFactory.selectFrom(qItem).fetchOne(); // (3)

        // then
        assertEquals(found, item); // (4)
    }
}

(1) JPAQueryFactory를 생성합니다. 이 때 생성자로 EntityManager를 주입해줍니다.
(2) QItem 객체를 생성합니다. 생성자에는 Entity의 alias로 사용할 변수명을 입력합니다.
(3) JPQL을 작성하듯이 자바 코드로 쿼리를 작성합니다.
(4) DB에 저장된 데이터와 다시 조회해 온 데이터가 동일한지 확인합니다.

잘 동작했는지 확인하기 위해 아래 설정을 추가해줍니다.

H2 데이터베이스 가 실행되며 테이블을 직접 생성하고 포매팅된 SQL 로그를 확인할 수 있기 위함입니다.

spring:
  jpa:
    hibernate:
      ddl-auto: create
    properties:
      hibernate:
        format_sql: true
logging:
  level:
    org.hibernate.SQL: debug

테스트를 실행시킨 결과는 다음과 같습니다.

2021-07-15 19:53:33.992 DEBUG 4334 --- [           main] org.hibernate.SQL                        : 

    create table item (
       id bigint not null,
        primary key (id)
    )
// 생략
2021-07-15 19:53:35.898 DEBUG 4334 --- [           main] org.hibernate.SQL                        : 
    insert 
    into
        item
        (id) 
    values
        (?)
2021-07-15 19:53:35.906 DEBUG 4334 --- [           main] org.hibernate.SQL                        : 
    select
        item0_.id as id1_0_ 
    from
        item item0_

(5) 또 다른 예

[ Java 파일 구조 ]

[ 생성된 Q클래스 구조 ]

(6) p6spy 추가

sql문의 파라미터 출력 및 기타 기능들을 위해서 p6spy 라이브러리를 추가한다.

implementation 'com.github.gavlyukovskiy:p6spy-spring-boot-starter:1.5.8'

4. Querydsl 예제

@DisplayName("hi 내용을 포함하며 댓글이 1개 이상인 Post를 ID 내림차순으로 조회한다.")
@Test
void queryDsl_findPostsByMyCriteria_Three() {
    EntityManager entityManager = testEntityManager.getEntityManager();

    JPAQuery<Post> query = new JPAQuery<>(entityManager);
    QPost qPost = new QPost("p");

    List<Post> posts = query.from(qPost)
        .where(qPost.content.contains("hi")
            .and(qPost.comments.size().gt(0))
        ).orderBy(qPost.id.desc())
        .fetch();

    assertThat(posts).hasSize(3);
}

QueryDSL은 각종 풍부한 체이닝 메서드와 유틸리티 메서드 및 정적 타입(Q 클래스)을 기반으로 직관적으로 쿼리를 작성
JPQL을 사용해본 독자님이라면 코드가 상당히 직관적임

5. Check List

(1) 기본 Q-Type 활용

[ Q클래스 인스턴스를 사용하는 2가지 방법 ]

QMember qMember = new QMember("m"); // 별칭 직접 지정
QMember qMember = QMember.member; // 기본 인스턴스 사용

하지만 기본 인스턴스를 static import와 함께 사용하는 것을 권장한다.

(2) 결과 조회

fetch : 리스트 조회, 데이터 없으면 빈 리스트 반환
fetchOne : 단 건 조회
- 결과가 없으면 : null
- 결과가 둘 이상이면 : com.querydsl.core.NonUniqueResultException
fetchFirst : limit(1).fetchOne()
fetchResults : 페이징 정보 포함, total count 쿼리 추가 실행
- group by having 카운팅에서 해당 메소드가 명확하게 동작하지 않는 이슈가 발생하여 deprecated 처리
fetchCount : count 쿼리로 변경해서 count 수 조회
- group by having 카운팅에서 해당 메소드가 명확하게 동작하지 않는 이슈가 발생하여 deprecated 처리

(3) 페이징

실무에서 페이징 쿼리를 작성할 때, 데이터를 조회하는 쿼리는 여러 테이블을 조인해야 하지만, count 쿼리는 조인이 필요 없는 경우도 있다.
그런데 이렇게 자동화된 count 쿼리는 원본 쿼리와 같이 모두 조인을 해버리기 때문에 성능이 안나올 수 있다.
count 쿼리에 조인이 필요없는 성능 최적화가 필요하다면, count 전용 쿼리를 별도로 작성해야 한다.

OpenSearch Service 설정

RichLegend — Tue, 7 Mar 2023 16:00:06 +0900

Cloudwatch Log 구독필터 → lambda Function → AWS OpenSearch 로그 수집을 위해서는 OpenSearch에 아래와 같은 설정이 필요하다.

Backend role의 ARN은 lambda 함수의 IAM 역할 ARN이다.

오래된 인덱스 자동 삭제 하기

Index Management → State Management policies 에서 새로운 policy를 추가해 준다.

policy를 생성하고 특정 index pattern을 검색하여 자동으로 해당 policy를 적용해 준다.

index의 상태(state)를 변경해 주고, 상태(state)에따라 명령을 실행하는 방식

최근 7일치 index만 보관할 경우

index는 날짜별로 생성된다고 가정한다(cwl-YYYY.mm.dd 형식).

아래의 경우 정책(policy)의 이름은 “delete_old_indices_7d”이다.

{
    "policy": {
        "policy_id": "delete_old_indices_7d",
        "description": "A policy that delete old 7 days.",
        "last_updated_time": 1668408892087,
        "schema_version": 14,
        "error_notification": null,
        "default_state": "hot_state",
        "states": [
            {
                "name": "hot_state",
                "actions": [],
                "transitions": [
                    {
                        "state_name": "delete",
                        "conditions": {
                            "min_index_age": "7d"
                        }
                    }
                ]
            },
            {
                "name": "delete",
                "actions": [
                    {
                        "retry": {
                            "count": 3,
                            "backoff": "exponential",
                            "delay": "1m"
                        },
                        "delete": {}
                    }
                ],
                "transitions": []
            }
        ],
        "ism_template": [
            {
                "index_patterns": [
                    "cwl-*"
                ],
                "priority": 100,
                "last_updated_time": 1639009244056
            }
        ]
    }
}

EKS 배포 롤백 방법

RichLegend — Tue, 7 Mar 2023 15:56:51 +0900

이미 배포된 pod에 오류가 발생하여 롤백하여야 할 경우가 있을텐데, EKS는 배포 history기능을 통해 특정 revision으로 롤백할 수 있습니다.

배포 히스토리 보기

배포 히스토리는 deployment 단위로 볼 수 있다.

]$ kubectl -n backend rollout history deploy backend-api-template-deployment
deployment.apps/backend-api-template-deployment
REVISION  CHANGE-CAUSE
15        [2022-12-26 11:12:18] backend-api-template:dev-73
16        [2022-12-26 11:25:59] backend-api-template:dev-74
17        [2022-12-26 11:37:21] backend-api-template:dev-75
18        [2022-12-28 19:02:14] backend-api-template:dev-76
19        [2023-01-03 07:49:41] backend-api-template:dev-77
20        [2023-01-03 08:45:55] backend-api-template:dev-78
21        [2023-01-04 10:55:50] backend-api-template:dev-79
22        [2023-01-04 11:13:08] backend-api-template:dev-80
23        [2023-01-05 15:33:44] backend-api-template:dev-81
24        [2023-01-06 11:47:46] backend-api-template:dev-82
25        [2023-01-06 14:40:16] backend-api-template:dev-83

]$

명령어는 kubectl -n {namespace 이름} rollout history deploy {deployment 이름} 의 형식입니다.

kubectl -n remodeling-backend는 kb로 alias 되어 있습니다.

배포 히스토리의 내용

위의 배포 히스토리의 내용 형식은 kubernetes 가 자동으로 만들어 주는것이 아닙니다.

히스토리 내용은 아래의 명령어로 배포시에 적재가 가능합니다.

]$ kubectl --namespace=$NAMESPACE annotate deployment $IMAGE_REPO_NAME-deployment kubernetes.io/change-cause="[$DATE] $IMAGE_REPO_NAME:$SPRING_PROFILES_ACTIVE-$CODEBUILD_BUILD_NUMBER" --overwrite=true

위 내용은 AWS CodeBuild 할때 참조하여 실행하는 buildspec.yml의 맨 마지막 줄에 적용되어 있습니다.

배포 롤백

롤백시에는 위 히스토리 보기 기능을 이용하여 REVISION을 확인 후 원하는 REVISION 번호로 롤백 하면 됩니다.
롤백 명령어는 아래와 같습니다.

]$ kubectl -n backend rollout undo deploy backend-api-deployment --to-revision=24

명령어는 kubectl -n {namespace 이름} rolloute undo deploy {deployment 이름} --to-revision={revision 번호}의 형식 입니다.

현재 적용된 리비전 확인

배포 상세 정보와 배포 히스토리를 비교하여, 현재 적용된 버전을 확인할 수 있다.

]$ kubectl -n backend describe deployment.apps backend-api-template-deployment

[ec2-user@ip-10-204-*** ~]$ kubectl -n backend describe deployment.apps backend-api-template-deployment | grep -A 2 Environment
    Environment:
      DATE:        2023-02-24 16:46:05
      DOCKER_TAG:  dev-101

기타

ArgoCD와 같은 WebUI 툴을 사용하지 않는 이유는 무엇입니까?

관리상의 이슈 입니다. 현재 리모델링 프로젝트는 AWS의 리소스를 사용하고 있고, 가능한 AWS에서 제공하는 자원만으로 운영하고 있습니다. ArgoCD는 개별적으로 설치해서 써야 해서 아직 적용하고 있지 않습니다.

JWT Postman 가이드

RichLegend — Tue, 7 Mar 2023 15:48:21 +0900

인증서 이슈

EKS API의 경우, API콜 할때 인증서를 셋팅해야 한다.

아래와 같은 인증서 관련 에러 발생시

방안1] 단순히 ssl 기능 disable

방안2] 인증서 등록

JWT 토큰 셋팅

방법1] Authorization 설정

방법2] 헤더 직접 셋팅
Authorization 필드에 “Bearer {TOKEN}” 으로 셋팅

AWS command 정리 (kubectl)

RichLegend — Tue, 7 Mar 2023 15:45:09 +0900

https://kubernetes.io/docs/reference/kubectl/

Command line tool (kubectl)

Production-Grade Container Orchestration

kubernetes.io

기본

kubectl -n {NAME_SPACE} {COMMAND} {TYPE} {NAME}

목록 조회

kubectl -n backend get {TYPE}
- DEV namespace 정보 모두 조회(pod, deployment, service, cluster 등.
  - kubctl -n backend get all
- DEV POD 조회.
  - kubctl -n backend get pod
- DEV deployment 조회.
  - kubctl -n backend get delpoy

상세 조회

목록에서 조회된 항목의 상세 조회
- kubectl -n backend describe {TYPE} {NAME}
- DEV namepsace의 특정 pod 조회
  - kubectl -n backend describe pod backend-api-common-deployment-67647bc77f-hncw6
- DEV namespace의 특정 deployment 조회
  - kubectl -n backend describe deploy backend-api-common-deployment

EKS API 서버 주소 조회

kubectl cluster-info

EKS 인증서 조회

kubectl config view --minify --raw --output 'jsonpath={..cluster.certificate-authority-data}' | base64 -d

EKS JWT 토큰 조회

서비스계정 조회

kubectl get serviceaccount

JWT 토큰 조회

kubectl get secret $(kubectl get sa {서비스계정} \
    -ojsonpath="{.secrets[0].name}") \
    -ojsonpath="{.data.token}" | base64 -d

주현 - AX | Backend/Frontend Developer

백엔드 개발자를 위한 RAG 설계: 청킹, 임베딩, 벡터 검색 쉽게 이해하기

백엔드 개발자를 위한 RAG 설계: 청킹, 임베딩, 벡터 검색 쉽게 이해하기RAG가 문서를 찾는 순서부터 청킹 크기, 임베딩 모델, HNSW 설정, 검색 품질 평가까지 실무에 필요한 내용만 쉽게 정리했습니다.

먼저 알아둘 용어

RAG는 두 단계로 나누면 이해하기 쉽습니다

문서를 저장할 때

질문을 받을 때

청킹은 문서의 의미를 지키는 작업입니다

임베딩 모델은 실제 질문으로 비교합니다

벡터 검색과 BM25를 함께 사용합니다

검색 필터는 보안과 품질에 모두 필요합니다

HNSW와 IVFFlat의 차이

HNSW

IVFFlat

검색과 답변을 따로 평가합니다

처음 구현할 때는 이 순서로 진행합니다

자주 묻는 질문

청크는 몇 토큰이 좋은가요?

처음부터 Semantic Chunking을 써야 하나요?

PostgreSQL과 pgvector로 시작해도 되나요?

임베딩 모델만 바꾸고 기존 벡터를 유지할 수 있나요?

답변이 틀리면 LLM부터 바꿔야 하나요?

정리

GPT-5.6이 나왔다. GPT-5.6 Sol·Terra·Luna, 어떤 작업에 써야 할까

GPT-5.6이 나왔다. 벤치마크 성능표보다 중요한 건 따로 있다

이번 발표에서 눈에 들어온 건 토큰 효율이었다

개발자가 체감하는 성능은 다른 곳에서 드러난다

프롬프트를 짧게 쓰라는 말은 조금 조심해서 들어야 한다

Codex와 Claude Code, 하나만 고를 필요는 없다

새 모델은 같은 작업으로 비교해 보면 된다

GPT-5.6에서 기대하는 건 화려한 답이 아니다

Codex GPT-5.6 Sol [collaboration.spawn_agent] 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

Codex GPT-5.6 Sol collaboration.spawn_agent 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

바쁜 분을 위한 해결 순서

일반 질문까지 막히는 이유

가장 먼저 LazyCodex를 업데이트합니다

업데이트 후에도 같은 오류가 남는다면

Windows PowerShell에서 백업

macOS/Linux에서 백업

tool_namespace 한 줄 추가하기

TOML 중복 선언은 피해야 합니다

설정 저장 후에는 새 작업에서 확인하세요

CLI에서는 설정을 바꾸기 전에 시험할 수 있습니다

그래도 안 될 때 보는 항목

재부팅과 재설치부터 할 필요는 없습니다

참고 자료

AI를 비서처럼 사용하려면 업무 흐름부터 정리해야 합니다

AI 활용의 기준을 바꿔야 합니다

처음부터 큰 자동화를 만들 필요는 없습니다

좋은 자동화는 질문이 아니라 흐름에서 시작됩니다

하루 10분짜리 일부터 넘겨보세요

AI 시대의 생산성은 “질문력”보다 “위임력”에 가깝습니다

AX 시대, AI를 슬랙에 팀원처럼 초대하는 법

AX 시대, AI를 슬랙에 팀원처럼 초대하는 법

1. AX의 출발점은 ‘AI 사용’이 아니라 ‘팀 운영 방식’입니다

2. AI를 슬랙에 팀원처럼 초대하면 일이 훨씬 자연스러워집니다

3. 사람과 AI 모두에게 역할이 있어야 합니다

4. AI도 팀의 흐름을 알아야 일을 잘합니다

5. 사람은 더 중요한 판단에 집중해야 합니다

6. 팀이 어디로 가는지 AI도 알아야 합니다

7. 신뢰는 검증 구조에서 생깁니다

AX를 시작하는 팀이 먼저 물어볼 질문

AI 도입해야 한다는 건 아는데, 사내에서 어디부터 시작해야 할지 모르시는 분 있으세요?

AX 채용 시장을 직접 들여다보니 — 경력직 중심, 재설계 역량, 그리고 진짜 AX 인재의 조건

AX 채용 시장을 직접 들여다보니 — 경력직 중심, 재설계 역량, 그리고 진짜 AX 인재의 조건

AX는 경력직 시장입니다 — 평균 4.3년, 중앙값 3년

가장 많이 본 역량 키워드 — As-Is에서 To-Be로

AX는 ChatGPT 계정 배포가 아닙니다

도메인별 수요 지도 — 제조 / 금융 / 공공

결론 — AX 인재의 진짜 조건

github에 오픈소스 SaaS 스타터킷을 배포했습니다.

AI 전환 진단 프로그램 AX Doctor v1 을 리뉴얼했습니다.

AX 전에 DX, 데이터가 흐르는 인프라가 먼저다

AI를 쓰고 있다고 말하기 어려운 이유

데이터 주권 3조건과 일의 정의

데이터가 흐르는 인프라가 먼저다

감지·실행·연결 — AI 에이전트 역할 설계

AX 전에 DX, 사금이 금이 되려면

AX(AI Transformation) 진단 프로그램 v1을 만들었습니다.

AX의 성공은 기술이 아니라 '조직'이 결정한다

Codex GPT-5.6 Sol `collaboration.spawn_agent` 오류 해결: 멀티 에이전트를 끄기 전에 확인할 것

`tool_namespace` 한 줄 추가하기