line·2026년 7월 31일·5분 읽기큐레이션 요약

Grafana에서 자연어로 장애 원인을 분석하기: LLM 에이전트 기반 SRELens 개발기

관측성 데이터가 메트릭·로그·트레이스·프로파일별로 분산되면, 장애 원인을 파악하기 위해 사람이 여러 도구를 오가며 맥락을 연결해야 합니다. LY Corporation의 Home SRE 팀은 이를 해결하기 위해 Grafana 플러그인인 SRELens를 개발했습니다. SRELens는 자연어 질문을 바탕으로 LLM 에이전트가 관측성 데이터를 조회하고, 도구 호출과 비용·권한·안전 정책을 백엔드에서 통제하며 원인 후보를 근거와 함께 제시합니다. ## 관측성 데이터가 분산되며 발생한 문제 - 메트릭은 Grafana·IMON, 로그는 LaaS·IU, 트레이스는 IMON 트레이스·Tempo, 프로파일은 별도 도구에서 확인해야 했습니다. - 장애 분석 과정에서 시간 범위, 서비스명, 라벨, 트레이스 ID 등의 맥락을 여러 시스템에 반복해서 옮겨야 했습니다. - 자체 호스팅형 LGTM-P 스택을 구축해 데이터를 통합했습니다. - Mimir: 메트릭 - Loki: 로그 - Tempo: 트레이스 - Pyroscope: 프로파일 - OpenTelemetry Collector: 데이터 수집 및 전달 - 데이터가 한곳에 모여도 사용자가 적절한 데이터소스와 라벨, 쿼리 방법을 알아야 한다는 문제는 남았습니다. - 예를 들어 서비스명이 데이터소스마다 `service_name`, `resource.service.name` 등 다른 필드로 표현될 수 있습니다. ## 오픈소스 PoC에서 확인한 한계 - **사용자 컨텍스트와 권한 전파** - Grafana 인증 사용자 정보를 대화 기록, 사용량 한도, 조회 권한에 안정적으로 연결하기 어려웠습니다. - **시스템 프롬프트 제어** - 도구 호출 순서, 재시도, 위험 작업 제한 같은 운영 정책을 사용자 질의와 분리해 보호하기 어려웠습니다. - **짧은 도구 호출 라운드** - 메트릭·트레이스·로그를 순차적으로 확인해야 하는 장애 분석을 충분히 수행하지 못했습니다. - **데이터소스별 라벨 차이** - 올바른 데이터소스를 선택해도 라벨이나 필드가 다르면 검색 결과가 0건이 될 수 있었습니다. - **운영 및 라이선스 제약** - 사내 환경에 맞게 수정하고 배포하는 데 한계가 있었습니다. - 이를 통해 단순한 자연어 질의 기능보다, LLM 에이전트의 행동을 운영 환경에 맞게 통제하는 것이 더 중요하다는 결론을 얻었습니다. ## SRELens 아키텍처 - SRELens는 Grafana 애플리케이션 플러그인으로 동작합니다. - 프런트엔드는 Grafana 내부에 채팅 UI를 제공합니다. - 백엔드는 다음을 담당합니다. - LLM 호출 - 시스템 프롬프트 합성 - 도구 오케스트레이션 - 사용량 및 비용 제한 - 결과 크기와 재시도 제어 - 관측성 데이터 조회는 MCP 게이트웨이를 통해 수행합니다. - 업스트림 MCP 도구 외에도 Grafana 패널 검색과 이미지 렌더링을 위한 로컬 도구를 제공합니다. - `find_grafana_panel` - `render_grafana_panel` - 업스트림 도구와 로컬 도구는 `CompositeClient`를 통해 LLM에 일관된 인터페이스로 노출됩니다. ## 세 계층으로 분리한 프롬프트 설계 ### 베이스 시스템 프롬프트 - 조직 전체에 적용되는 전역 행동 정책입니다. - 다음과 같은 규칙을 포함합니다. - 도구 호출 순서 - 결과가 없을 때의 폴백 전략 - 결과가 잘렸을 때 집계 쿼리를 재실행하는 방법 - 대시보드 생성·수정·삭제 등 위험 작업의 안전 규칙 - 응답 형식과 분석 근거 제시 방식 - 관리자만 수정할 수 있으며, 별도 설정이 없으면 코드에 포함된 기본 프롬프트를 사용합니다. ### 데이터소스 프래그먼트 - 환경별 관측성 시스템 정보를 YAML 형태로 제공합니다. - 주요 내용은 다음과 같습니다. - 우선 사용할 Mimir·Loki·Tempo 데이터소스 UID - 서비스명을 찾기 위한 라벨 후보 - Loki 로그의 JSON 파싱 및 구조화 메타데이터 처리 방법 - SRE의 운영 지식을 미리 제공해 불필요한 탐색을 줄이고 분석 성공률과 속도를 높입니다. ### 사용자 프롬프트 - 담당 서비스, 선호 응답 형식, 자주 사용하는 대시보드 등 개인·팀의 맥락을 저장합니다. - Redis에 저장되며 시스템 프롬프트의 추가 컨텍스트로 주입됩니다. - 베이스 프롬프트를 덮어쓰지 않으므로 개인화가 조직 공통 안전 정책보다 우선할 수 없습니다. ## 백엔드 중심의 툴 오케스트레이션 - 프런트엔드가 시스템 프롬프트를 조립하지 않고, 백엔드 오케스트레이터가 모든 프롬프트 합성을 담당합니다. - 에이전트는 다음 루프를 반복합니다. 1. 사용자 질문을 LLM에 전달 2. LLM이 요청한 MCP 또는 로컬 도구 실행 3. 도구 결과를 다시 LLM에 전달 4. 최종 분석이 나올 때까지 반복 - 운영 안정성을 위해 코드 수준의 가드레일을 적용했습니다. - 최대 10라운드로 도구 호출 제한 - 동일 도구·동일 인자의 중복 호출 차단 - 도구별 재시도 최대 2회 - 개별 도구 결과 크기 제한 - 전체 요청이 커질 경우 오래된 도구 결과를 플레이스홀더로 치환 - `tool_call_id`를 유지해 호출과 결과의 연결 보장 - 결과가 없으면 라벨, 시간 범위, 데이터소스를 바꿔 재시도하도록 유도 ## 비용·요청량 및 장애 대응 정책 - 사용자별 일일 토큰 한도를 적용합니다. - 분당 요청 수를 제한하고, 한도 초과 시 HTTP 429를 반환합니다. - 응답 후 OpenAI가 반환한 실제 프롬프트·출력 토큰 사용량을 사용자별 일일 버킷에 기록합니다. - 사용량은 Asia/Seoul 기준 자정에 초기화됩니다. - Redis는 대화 기록, 사용자 프롬프트, 쿼터 저장에 사용됩니다. - Redis 장애가 발생해도 단일 채팅 요청은 계속 처리할 수 있도록 설계했습니다. - 대화 기록 및 개인화 기능은 제한될 수 있습니다. - SRELens 전체가 동시에 중단되지는 않습니다. ## 실제 장애 분석 방식의 변화 - 사용자는 “특정 시간대에 왜 에러가 늘었는가”처럼 자연어로 질문할 수 있습니다. - SRELens는 하나의 분석 흐름에서 메트릭, 로그, 트레이스를 연결해 확인합니다. - 예시 시나리오에서는 베타 환경의 오류 급증을 분석하면서 특정 API 요청인 `CopyMedia` 호출 증가와 관련된 원인까지 범위를 좁혔습니다. - 기존처럼 대시보드, 로그 검색 시스템, 트레이스 도구를 오가며 사람이 상관관계를 직접 맞출 필요가 줄어듭니다. - 분석 결과는 단순한 결론이 아니라 조회된 관측성 데이터와 근거를 함께 제시하는 것을 목표로 합니다. 운영 환경에서 LLM 기반 장애 분석을 도입할 때는 자연어 인터페이스보다 통제 구조를 먼저 설계하는 것이 중요합니다. 조직 정책과 환경별 데이터소스 지식을 프롬프트 계층으로 분리하고, 도구 호출·권한·비용·재시도를 백엔드 코드로 제한해야 안정적이고 재현 가능한 분석 도구를 만들 수 있습니다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜옵저버빌리티redisgrafana+3

line·2026년 7월 30일·5분 읽기큐레이션 요약

AI 에이전트를 위한 Android CLI: 대규모 모바일 개발 환경에 적용하기

LINE Android처럼 수백 개의 Gradle 모듈과 대규모 코드를 가진 저장소에서는 단순한 `grep`·`glob` 검색만으로 AI 에이전트가 의미론적 질문에 답하기 어렵고, 불필요한 결과와 재시도로 토큰 비용이 급증합니다. LINE 개발팀은 Android CLI를 문서 검색과 Android Studio 연동의 기반으로 활용하되, 고정된 바이너리·래퍼·스킬·프롬프트를 조합해 보안, 환경 일관성, 오류 처리, 토큰 효율성을 보완하고 있습니다. 핵심은 CLI를 에이전트에 그대로 노출하지 않고, 저장소 규모와 조직 환경에 맞게 통제된 인터페이스로 제공하는 것입니다. ## 대규모 Android 저장소에서 AI 에이전트가 겪는 문제 - 수백 개의 Gradle 모듈과 방대한 코드 때문에 검색 한 번에도 지나치게 많은 결과가 반환됩니다. - 검색 결과가 에이전트 컨텍스트에 포함되면서 토큰과 비용이 빠르게 증가합니다. - 텍스트 검색만으로는 다음과 같은 의미론적 질문에 정확히 답하기 어렵습니다. - 특정 심볼의 선언 위치 - 심볼의 실제 참조 위치 - IDE가 판단하는 사용되지 않는 코드나 경고 - 의존성 내부 심볼의 위치 - 관련 없는 결과를 바탕으로 에이전트가 반복 검색과 재시도를 수행하면서 비효율이 커집니다. - 따라서 Android CLI를 그대로 적용하기보다는 래퍼, 스킬, 프롬프트를 통한 보완이 필요합니다. ## 문서 검색을 Android CLI로 전환 - Android CLI는 빌드·배포, SDK 관리, 환경 진단, 공식 문서 검색, Android Studio 연동 등을 제공합니다. - 첫 적용 대상은 Android, Jetpack Compose, AndroidX, Firebase 등의 공식 문서 검색이었습니다. - 모델의 사전 학습 지식은 최신 API 변경을 반영하지 못할 수 있어 잘못된 시그니처를 생성하는 환각이 발생할 수 있습니다. - 최신 Android Knowledge Base를 직접 참조하면 문서의 권위와 최신성을 확보할 수 있습니다. - 기존에는 Google Cloud Knowledge MCP 서버를 사용했지만 다음 운영 부담이 있었습니다. - 개발자별 Google Cloud API 인증 설정 - 인증 프록시 운영 - API 할당량 제한 대응 로직 유지 - Android CLI의 `docs` 명령은 다음 두 단계로 사용됩니다. - `docs search`: 키워드로 공식 문서 검색 - `docs fetch`: 검색 결과의 KB URL로 문서 본문 조회 - 이 기능은 `get-android-dev-knowledge` 스킬로 에이전트에 제공됩니다. - 기존 MCP 방식과 비교해 인증, 프록시, 할당량 처리 인프라를 제거하고 더 적은 토큰으로 최신 문서를 참조할 수 있습니다. ## CLI 바이너리를 저장소에 번들링한 이유 LINE 팀은 전역 설치된 `android` 명령 대신 `.agents/tools/android-cli/android`처럼 저장소 내부의 고정 경로에 바이너리를 포함했습니다. ### 환경 파편화 방지 - 개발자마다 CLI 버전, 설치 위치, 운영체제가 달라지는 문제를 줄입니다. - 저장소를 클론하면 동일한 버전을 사용할 수 있습니다. - 개발자 장비뿐 아니라 CI와 AI 에이전트 실행 호스트에서도 동일한 환경을 보장합니다. ### 보안 정책과 래퍼 적용 - Android CLI는 호출 과정에서 일부 데이터를 수집할 수 있습니다. - 이를 막으려면 호출마다 `--no-metrics` 인자를 지정해야 합니다. - 에이전트가 해당 인자를 누락할 수 있으므로 모든 호출을 통과시키는 래퍼에서 강제하는 방식이 안전합니다. - 래퍼가 실제 바이너리를 안정적으로 찾으려면 바이너리 위치가 고정되어 있어야 하므로 저장소 번들링이 유리합니다. - 대규모 저장소에 이미 `git-lfs`가 적용되어 있어 바이너리 포함 비용도 감당할 수 있었습니다. ## `--no-metrics` 관련 버그와 오류 출력 개선 - Android CLI 1.0 도입 과정에서 정보 수집 기능이 `--no-metrics` 처리 전에 초기화되는 버그가 발견되었습니다. - 이 때문에 메트릭 수집을 비활성화해도 `~/.android/cli`에 쓰기를 시도할 수 있습니다. - 샌드박스나 파일 시스템 권한으로 쓰기가 차단되면 여러 페이지의 Java 스택 트레이스가 출력됩니다. - 장황한 스택 트레이스는 에이전트 컨텍스트를 불필요하게 차지하고 문제 해결도 어렵게 만듭니다. - 래퍼는 CLI 실행 전에 다음을 수행합니다. - `~/.android/cli` 디렉터리 생성 시도 - 임시 파일을 만들어 쓰기 권한 확인 - 쓰기가 막히면 한 줄짜리 파싱 가능한 오류 출력 - 에이전트는 이제 긴 예외 대신 “쓰기 권한을 부여한 뒤 재시도하라”는 원인과 조치를 직접 전달받습니다. - 반복적으로 발생하는 오류를 에이전트가 처리하기 쉬운 구조화된 메시지로 변환하는 방식은 이후 Android Studio 연동에도 적용됩니다. ## Android Studio 연동의 의미론적 기능 Android CLI 1.0에서는 실행 중인 Android Studio와 연결해 IDE 수준의 분석을 명령줄에서 수행할 수 있게 되었습니다. - `studio check` - Android Studio 실행 여부를 확인합니다. - 대상 프로젝트가 열려 있는지 확인합니다. - 프로젝트 인덱싱이 완료되었는지 확인합니다. - 다른 Studio 기능을 사용하기 위한 전제 조건입니다. - `studio analyze-file` - 빌드하지 않고 단일 파일에 IDE 인스펙션을 적용합니다. - 에러와 경고를 반환합니다. - `is never used`처럼 단순한 `grep`으로 파악하기 어려운 의미론적 문제도 찾을 수 있습니다. - `studio find-declaration` - 심볼의 선언 위치를 찾습니다. - 프로젝트 코드뿐 아니라 `.aar`, `.jar` 의존성 내부도 검색합니다. - `studio find-usages` - 특정 심볼이 사용된 위치를 찾습니다. - `studio render-compose-preview` - `@Preview`가 적용된 Jetpack Compose 화면을 PNG 이미지로 렌더링합니다. ## CLI를 래퍼와 스킬로 감싼 설계 - Android Studio 기능도 CLI를 에이전트에 직접 노출하지 않고 얇은 래퍼와 스킬을 통해 제공합니다. - 가장 먼저 `studio-check` 스킬을 만들었습니다. - 에이전트가 CLI의 복잡한 입출력과 환경 전제 조건을 직접 처리하지 않도록 하는 것이 목적입니다. - 래퍼는 권한 확인, 실행 환경 검증, 오류 메시지 정규화 같은 공통 처리를 담당합니다. - 스킬은 에이전트가 언제 어떤 기능을 사용해야 하는지 안내하는 고수준 인터페이스 역할을 합니다. 실무적으로는 대규모 저장소에서 Android CLI를 전역 도구로 배포하기보다, 버전을 고정한 바이너리를 저장소에 포함하고 모든 호출을 래퍼로 통제하는 방식을 추천할 수 있습니다. 특히 검색 결과를 무작정 늘리는 대신 문서 검색, 심볼 탐색, IDE 분석처럼 목적에 맞는 의미론적 명령을 스킬로 제공하면 토큰 낭비와 에이전트의 반복 작업을 크게 줄일 수 있습니다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜Androidgradleai-coding-agents+3

line·2026년 6월 26일·4분 읽기큐레이션 요약

프롬프팅에서 워크플로로, AI로 프런트엔드 개발 생산성 끌어올리기

코딩 속도보다 더 큰 병목은 Jira, Figma, Confluence, Slack, Git 등에 흩어진 정보를 모으고 조정하는 비용입니다. 글은 LLM을 단발성 프롬프트 도구가 아니라 반복 가능한 개발 워크플로의 실행 엔진으로 활용해야 한다고 주장합니다. 이를 통해 구현 전 요구 사항을 통합하고, 불확실성을 드러내며, 구현 후 검증까지 자동화하는 오케스트레이션 중심의 프런트엔드 개발이 가능해집니다. ## 프런트엔드 개발의 병목 변화 - 하나의 기능을 구현하려면 여러 시스템을 오가야 합니다. - 요구 사항: Jira - 디자인: Figma - 기술·정책 문서: Confluence - 의사결정과 논의: Slack - 구현과 검증: Git - 프런트엔드 개발자는 이 정보를 통합해 실제 사용 가능한 결과물로 조립하는 역할을 담당합니다. - 주요 부담은 코드를 작성하는 일보다 다음과 같은 컨텍스트 작업에 있습니다. - 티켓과 디자인 분석 - 에지 케이스 확인 - 제품·백엔드 팀과의 동기화 - 기존 코드와 재사용 가능한 구성 요소 탐색 ## 프롬프트에서 반복 가능한 워크플로로 - 단발성 프롬프트는 한 번의 작업에는 유용하지만, 반복성과 누적 효과가 부족합니다. - 워크플로는 입력부터 출력까지의 표준화된 경로입니다. - 여러 시스템에서 관련 컨텍스트 수집 - 요구 사항 요약 - 모호하거나 충돌하는 내용 식별 - 구현 계획과 파일 목록 제안 - 사람이 검토한 뒤 코드 수정 진행 - 이 구조에서 LLM은 단순히 코드를 생성하는 도구가 아니라 워크플로를 실행하는 엔진입니다. - 한 번 구축한 워크플로는 티켓의 내용이 달라져도 동일한 패턴으로 적용할 수 있어 확장성이 높습니다. ## 연결된 개발 컨텍스트와 Noah MCP - LY Corporation의 Noah MCP는 Jira, Confluence, Slack, GitHub 같은 내부 도구를 연결합니다. - AI 에이전트가 사람이 복사해 붙여넣은 정보가 아니라 실제 업무 시스템에 존재하는 컨텍스트를 직접 읽고 추론할 수 있게 합니다. - 이를 통해 개발자는 각 시스템을 수동으로 방문하고 정보를 노트에 조합하는 작업을 줄일 수 있습니다. - 핵심은 AI를 별도의 도구로 사용하는 것이 아니라 기존 업무 흐름 안에 배치하는 것입니다. ## 구현 전 요구 사항 통합 예시 기능은 검색·필터·정렬과 역할 기반 필터 표시가 있는 목록 페이지입니다. 기존 방식에서는 개발자가 Jira, Figma, Confluence, Slack, 코드베이스를 직접 확인한 뒤 계획을 작성합니다. 워크플로 기반 방식에서는 에이전트에게 다음을 요청합니다. - Jira 티켓 분석 - 관련 Confluence 문서 검색 - Slack의 최근 의사결정 확인 - 유사한 코드 구현 탐색 - 코드 수정 없이 다음 결과 반환 - 요구 사항 요약 - 프런트엔드 영향 범위 - 관련 파일 - 구현 체크리스트 - 테스트 체크리스트 - 미해결 질문 에이전트가 도출한 계획에는 다음과 같은 구체적인 정보가 포함됩니다. - `FeatureListPage.tsx`, `FeatureList.tsx` 등 신규 파일 - 기존 `useTableFilters`, `useUrlState` 훅의 재사용 - `GET /api/<feature>`의 기존 페이지네이션 API 활용 - 역할별 필터 표시 - viewer: 검색, 상태 필터, 날짜 범위 - editor: owner 필터 추가 - admin: 내부 전용 플래그 추가 - 필터·정렬·페이지 상태를 URL 파라미터와 동기화 - 로딩, 빈 결과, 검색 결과 없음 상태 구현 ## 숨겨진 요구 사항과 재작업 방지 - Slack 논의에서 필터 상태를 `localStorage`가 아니라 URL에 저장해야 한다는 결정이 발견됩니다. - URL 공유가 가능해지고 - 새로고침 후에도 상태가 유지되며 - 다른 사용자가 동일한 화면을 재현할 수 있습니다. - 코드베이스 검색을 통해 이미 존재하는 훅을 재사용할 수 있습니다. - 불필요한 중복 구현 방지 - 기존 동작과의 일관성 유지 - 개발 시간 단축 - 구현 전에 다음과 같은 미해결 사항도 드러납니다. - 필터·정렬 상태를 URL에 저장할지 여부 - 빈 상태에서 “필터 초기화” 버튼을 제공할지 여부 - 이런 문제를 PR 리뷰 단계가 아니라 구현 전에 발견하면 재작업 가능성을 줄일 수 있습니다. ## 코딩 이후의 폐쇄 루프 검증 워크플로는 코드 생성에서 끝나지 않고 검증 단계까지 포함해야 합니다. - 구현 후 원래 계획과 실제 변경 사항을 대조합니다. - 자동 검증 항목을 실행합니다. - 타입 검사 - 린트 - 관련 단위 테스트 - 스모크 테스트 또는 로컬 검증 흐름 - 에이전트는 다음 결과를 보고합니다. - 통과한 검사 - 실패 후 수정한 문제 - 자동화하지 못한 검증 - UI 상태별 스크린샷이나 확인 메모 - PR 전 남은 위험 요소 - 이 폐쇄 루프를 통해 계획, 구현, 검증이 하나의 연속된 개발 사이클이 됩니다. ## 실용적인 적용 방향 프런트엔드 팀은 먼저 Jira·문서·메신저·코드 검색을 묶은 “구현 전 분석 워크플로”부터 도입하는 것이 좋습니다. 이후 구현 계획 승인, 코드 수정, 자동 테스트, PR 전 검증을 단계적으로 연결하면 단순한 코드 생성보다 재작업 감소와 품질 향상이라는 더 큰 효과를 얻을 수 있습니다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜대규모 언어 모델ReactTypeScript+4

line·2026년 6월 17일·4분 읽기큐레이션 요약

ID-JAG The Hard Way: 실패로 배우는 AI 에이전트 보안 핸즈온

AI 에이전트의 API 접근에는 단순한 사용자 인증을 넘어, 에이전트가 특정 사용자를 대신해 정해진 범위의 작업만 수행하도록 통제하는 위임 인가가 필요하다. 글은 OAuth 기반 프로필인 ID-JAG를 활용해 Keycloak, Athenz, MCP 서버, 리소스 서버가 연계되는 전체 흐름을 로컬 핸즈온으로 재현한다. 특히 인증 정보와 실제 접근 권한을 분리하고, 기업 정책에 따라 실패 지점을 명확히 차단하는 중앙 집중형 인가 구조를 강조한다. ## ID-JAG가 해결하려는 문제 - ID-JAG는 다음 OAuth 표준을 결합해 위임된 크로스 도메인 API 접근을 지원한다. - OAuth 2.0 Token Exchange(RFC 8693) - JWT Profile for OAuth 2.0 Authorization Grants(RFC 7523) - 기존의 “사용자가 누구인가?”라는 인증 중심 질문을 다음과 같이 확장한다. - AI 에이전트가 현재 사용자를 대신해 특정 리소스에 접근할 권한이 있는가? - 요청된 권한 범위와 기업 정책을 충족하는가? - AI 에이전트에 영구적이고 포괄적인 권한을 주면 오작동이나 공격 시 피해 범위가 커지고, 사용자의 의도와 에이전트의 자율 행동을 구분하기 어렵다. - 모든 API 호출마다 사용자의 동의를 요구하면 자동화와 사용자 경험이 훼손된다. - ID-JAG는 임시 토큰 연결 대신, 정책에 기반한 명시적 위임과 중앙 집중형 신뢰 관계를 제공한다. ## 데모 아키텍처와 역할 분리 핸즈온에서는 인증과 인가 정책을 의도적으로 분리한다. - **Keycloak** - 사용자를 인증하는 업스트림 IdP다. - 로그인 결과로 원본 ID 어서션을 발급한다. - **Athenz** - KeycloakTokenExchangePlugin을 통해 연동된 IdP 인가 서버로 동작한다. - Keycloak 토큰의 발급자, 서명, 대상, 주체, 클라이언트 바인딩을 검증한다. - 기업 정책을 평가하고 최종 ID-JAG 어서션을 발급한다. - 중앙 리소스 인가 서버이자 정책 결정 지점(PDP) 역할을 한다. - **AI 에이전트** - 사용자를 대신해 ID-JAG와 액세스 토큰을 요청한다. - 장기 마스터 키가 아니라 정책으로 제한된 임시 권한을 사용한다. - **MCP 서버** - 에이전트가 호출하는 보호된 중간 리소스 서버다. - 전달받은 토큰을 인가 서버와 교환한 뒤 최종 리소스 서버에 접근한다. - **리소스 서버** - Athenz가 발급한 신뢰 가능한 토큰만 수용한다. - 업스트림 IdP의 토큰을 무조건 인가 그랜트로 인정하지 않는다. ## ID-JAG 실행 흐름 실습 환경에서는 다음 순서로 위임 접근이 진행된다. - 사용자가 Keycloak을 통해 로그인한다. - 사용자가 AI 에이전트에 작업을 지시한다. - 에이전트가 Athenz에 ID-JAG 토큰을 요청한다. - Athenz가 사용자, 클라이언트, 대상 리소스, 권한 범위 및 기업 정책을 검증한다. - 허용된 경우 에이전트가 Athenz에 액세스 토큰을 요청한다. - 에이전트가 액세스 토큰을 포함해 MCP 서버를 호출한다. - MCP 서버가 토큰 교환을 수행한다. - 교환된 토큰으로 최종 리소스 서버에 요청한다. 이 구조에서는 인증된 사용자라는 사실만으로 모든 리소스 접근이 허용되지 않으며, 각 단계에서 위임 범위와 정책을 다시 확인한다. ## 인증 토큰과 인가 그랜트의 분리 Keycloak의 ID 토큰을 곧바로 액세스 토큰으로 교환하는 방식도 기술적으로는 가능하지만, 보안 모델상 한계가 있다. - **ID 토큰** - 사용자가 클라이언트에 성공적으로 인증됐음을 나타낸다. - 특정 리소스에 접근할 권리를 직접 의미하지 않는다. - **인가 그랜트** - 특정 리소스와 권한 범위에 대한 액세스 토큰 발급을 요청하기 위해 인가 서버에 제출된다. - ID-JAG를 별도의 인가 그랜트로 사용하면 다음 실패 유형을 구분할 수 있다. - 사용자 인증 실패 - 그랜트 검증 실패 - 에이전트 위임 거부 - 기업 정책 거부 - 리소스 서버의 토큰 거부 - 이 경계는 장애 분석과 감사 추적을 명확하게 만들고, 로그인 성공이 곧 크로스 도메인 API 접근 권한으로 오해되는 것을 방지한다. ## 실패 경로를 통한 보안 검증 핸즈온은 정상 동작뿐 아니라 의도적인 설정 오류를 통해 정책 경계를 확인하도록 구성된다. - 토큰 없이 보호된 API를 호출하면 `401 Unauthorized`가 발생한다. - 엔터프라이즈 역할만 설정하고 멤버십을 누락하면 토큰 교환이 실패한다. - 에이전트에 필요한 위임 권한을 부여하지 않으면 위임 호출이 차단된다. - 각 오류는 인증, 역할, 멤버십, 위임 정책, 토큰 교환 중 어느 단계가 필요한지 보여준다. - Athenz UI에서 에이전트의 위임 권한을 제거한 뒤 다시 실행하면 차단이 발생하는 지점을 직접 추적할 수 있다. ## 중앙 정책 관리의 장점 - 기업의 위임 정책을 Athenz 한 곳에서 관리할 수 있다. - 여러 IdP, SaaS, 리소스 애플리케이션에 정책을 중복 배포할 필요가 줄어든다. - 벤더별 인가 로직에 대한 종속을 완화할 수 있다. - 시스템 간 정책 불일치와 운영상의 보안 위험을 줄인다. - Athenz가 ID-JAG 발급자이자 PDP로 기능하면서, 위임 API 접근에 대한 단일 진실 공급원이 된다. ## 실습 방법과 권장 사항 - `athenz-community/id-jag-the-hard-way` 저장소에서 튜토리얼을 실행한다. - 정상 흐름뿐 아니라 의도적으로 역할, 멤버십, 위임 권한을 제거해 실패 지점을 확인하는 것이 중요하다. - 실제 기업 환경에서는 인증 성공 여부와 별도로 리소스·권한·에이전트·정책을 명시적으로 검증해야 한다. - AI 에이전트 도입 시 장기 자격 증명 대신 제한된 범위의 단기 토큰과 중앙 정책 평가를 사용하는 방식을 권장한다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜AI 에이전트jwtauthorization+4

line·2026년 5월 29일·4분 읽기큐레이션 요약

ODW #8: Slack MCP로 사고 대응과 FAQ 생성 작업 속도를 높이는 실습형 사내 워크숍 후기

Slack에 축적된 문의와 사고 대응 정보는 중요하지만, 문서화가 늦어지거나 담당자별 품질 차이로 지식 자산화가 어려웠다. 이 글은 사내 인증 기반 Slack MCP와 Confluence·Jira MCP를 결합해 FAQ, 사고 상황 요약, 인시던트 리포트를 자동 생성하는 워크숍 사례를 소개한다. 핵심은 기술 설명보다 실제 업무를 직접 자동화해 보고, 검증된 프롬프트를 스킬로 만들어 조직 전체에서 재사용하는 데 있다. ## Slack 정보의 구조화 격차 - Slack에는 사고 대응, 문의, 프로젝트 논의 등 실시간 업무 정보가 축적된다. - 그러나 문서화가 본업에 밀리거나 담당자에 따라 기록 품질이 달라진다. - 그 결과 중요한 정보가 Slack 스레드에 묻혀 재검색과 재활용이 어려워진다. - FAQ, 사고 보고서, 진행 상황 보고서 형태로 Confluence나 Jira에 정리할 필요가 있다. ## Slack MCP 도입과 워크숍 목표 - 사내 Slack MCP는 사내 인증과 연동되어 개인 토큰이나 복잡한 OAuth 설정 없이 Slack 정보에 접근할 수 있다. - 새로운 도구의 도입을 막는 요인은 다음과 같다. - 업무 중 별도로 학습할 시간 부족 - 설정과 활용에 대한 심리적 부담 - 사내 정보 확산의 지연 - 워크숍은 Slack MCP가 공개된 직후 빠르게 열어 참가자의 관심을 실습으로 연결했다. - 목표는 깊은 기술 지식 전달보다 참가자가 당일부터 업무에 활용할 수 있게 만드는 것이었다. ## Slack MCP의 주요 기능과 확장성 - Slack MCP는 다음 기능을 제공한다. - 메시지와 스레드 조회 - 메시지 게시 및 액션 실행 - 채널과 멤버 조회 - 메시지 검색 - Confluence MCP와 결합하면 프로젝트 보고서나 FAQ를 자동 생성하고 게시할 수 있다. - Jira MCP와 결합하면 Slack 논의를 바탕으로 작업 티켓을 만들 수 있다. - 워크숍에서는 먼저 AI에게 Slack 채널에 “Hello”를 게시하게 하여 MCP의 동작을 직접 체험하게 했다. ## 문의 대응 내용을 FAQ로 변환 - Slack 문의 채널의 대화를 검색해 FAQ 형식의 마크다운으로 변환했다. - 기존 Confluence FAQ와 대조해 이미 문서화된 내용은 제외했다. - 생성된 내용을 Confluence 하위 페이지로 게시하고, 증상·해결책·원인 구조의 표로 정리했다. - 활용 흐름은 다음과 같다. - 문의 채널과 Confluence 페이지 지정 - ‘문의’를 포함한 최신 스레드 검색 - 기존 FAQ와 중복 여부 확인 - 신규 문의만 FAQ 파일로 생성 - Confluence에 게시 - 이를 통해 반복 문의를 지식 베이스로 축적하고 담당자별 답변 품질 차이를 줄일 수 있다. ## 사고 상황 요약과 인시던트 리포트 생성 ### 빠른 상황 파악 - “시스템 장애 내용 및 상황을 정리해줘”와 같은 자연어 지시로 Slack 스레드를 검색한다. - AI는 해결 상태, 고객 영향, 담당자별 조치, 장애 타임라인을 요약한다. - 예를 들어 장애 감지 시각, 원인 파악 시각, 대응 완료 시각을 한눈에 정리할 수 있다. - 매니저가 중간에 합류하거나 담당자에게 직접 묻기 전에 전체 상황을 파악할 수 있어 의사 결정이 빨라진다. ### 인시던트 리포트 자동 작성 - 사전에 정한 형식에 따라 발생 시각, 감지 시각, 장애 기간, 원인, 영향 범위, 대응 내용을 자동 구조화한다. - 데이터베이스 커넥션 풀 고갈이나 설정 변경 누락 같은 원인과 사용자 수, 영향 기능, 데이터 손실 여부 등을 보고서에 포함할 수 있다. - 사고 대응 중에는 현황 요약을, 대응 완료 후에는 공식 리포트를 생성하는 식으로 목적에 맞게 활용한다. ## 정확도와 리뷰를 높이는 방법 - Slack의 모든 정보를 그대로 사용하지 말고 분석 범위를 먼저 좁혀야 한다. - 기존 Confluence 문서와 중복 제거 - 특정 리액션이 달린 메시지만 선택 - 특정 채널이나 기간, 키워드로 검색 범위 제한 - AI가 생성한 결과를 그대로 공개해서는 안 된다. - 개인정보 포함 여부 확인 - 원본 스레드 출처 표시 - 원래 발언을 과도하게 해석하지 않았는지 검토 - 실제 실습에서도 원본 스레드의 의도와 FAQ 내용이 미묘하게 달라지는 사례가 있어 사람의 리뷰가 필요함을 확인했다. - “증상·해결책·원인 세 칼럼의 표로 작성”처럼 출력 형식을 구체적으로 지정하면 팀 문서 표준에 맞는 결과를 얻기 쉽다. ## 재사용 가능한 스킬 설계 - 반복 작업은 스킬로 저장해 프롬프트를 매번 다시 작성하지 않도록 했다. - 워크숍에서 사용한 스킬은 다음 네 가지다. - `slack-to-faq`: Slack 스레드에서 FAQ 생성 - `faq-to-confluence`: FAQ를 Confluence에 게시 - `slack-incident-status`: 사고 상황 요약 - `slack-incident-report`: 인시던트 리포트 생성 - 스킬 제작 과정은 다음과 같다. - 수동으로 여러 프롬프트를 실험 - 효과적인 지시와 출력 형식 기록 - 재사용 가능한 스킬로 정의 - 팀에 공유하고 피드백을 반영해 개선 - 이를 통해 워크숍 참가자가 같은 절차를 재현하고, 팀 전체가 일관된 품질의 결과를 얻을 수 있다. ## 워크숍 운영에서 얻은 교훈 - 신기술이 등장해 관심이 높은 시점에 빠르게 교육을 제공하면 학습 참여를 높일 수 있다. - “Hello” 게시처럼 단순한 성공 경험부터 시작한 뒤 FAQ 생성과 사고 대응으로 난도를 높이는 단계적 구성이 효과적이다. - 일반적인 기능 소개보다 문의 대응과 장애 대응처럼 실제로 시간이 많이 드는 업무를 주제로 삼아야 활용 가능성을 쉽게 체감할 수 있다. - 기술 자체보다 참가자가 직접 손을 움직여 자신의 업무에 적용해 보는 경험이 현장 정착에 중요하다. 실무에서는 Slack MCP를 전사적으로 한꺼번에 도입하기보다, 반복 문의나 인시던트 보고처럼 효과를 측정하기 쉬운 업무부터 시작하는 것이 좋다. 원본 출처와 사람의 검토 절차를 반드시 포함하고, 검증된 작업 흐름은 스킬로 표준화해 점진적으로 확산하는 방식이 적절하다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜생성형 AIslackclaude-code+4

line·2026년 5월 22일·4분 읽기큐레이션 요약

ODW #7: 세 가지 방법으로 토큰 소비량 40% 절감! ADK를 이용한 컨텍스트 엔지니어링

LY Corporation의 워크숍은 AI 에이전트의 비용 증가와 응답 정확도 저하를 해결하기 위해 컨텍스트 엔지니어링을 소개한다. 핵심은 LLM에 전달하는 프롬프트, 도구 정의, 대화 이력, 외부 데이터를 무조건 많이 제공하는 것이 아니라 작업에 필요한 고품질 정보만 적절한 형태로 선별하는 것이다. ADK의 구조화 스키마, AgentTool, MCP 도구 필터링을 활용하면 토큰 사용량을 줄이면서도 장시간 실행 에이전트의 정확도를 개선할 수 있다. ## 사내 AI 활용 확대에 따른 문제 - Claude Code, Cline, ADK 등 AI 도구의 사용자가 늘면서 토큰 소비량이 급증했다. - 프롬프트에 명시한 지시를 AI가 무시하거나 중요한 정보를 누락하는 문제가 발생했다. - 대화가 길어질수록 AI가 이전 맥락에 묻혀 엉뚱한 답변을 생성하기도 했다. - 주요 원인은 LLM에 전달되는 컨텍스트를 체계적으로 관리하지 않았기 때문이다. - 토큰 증가 요인에는 다음이 포함된다. - AI 사용 인구 증가 - 원하는 결과를 얻기 위한 반복 작업 - 싱글 에이전트에서 멀티 에이전트로의 확장 - 단발성 작업에서 장시간 실행 작업으로의 변화 - MCP 도구 정의 자체가 차지하는 토큰 - 컨텍스트 최적화 기법의 확산 부족 ## 컨텍스트 부패와 토큰 관리 - LLM 사용 비용은 입력과 출력에 사용된 총 토큰 수를 기준으로 산정된다. - 장시간 실행되는 에이전트에서는 대화 이력과 중간 결과가 계속 축적된다. - 현재 작업과 관계없는 정보가 컨텍스트에 남으면 중요한 신호가 노이즈에 묻힌다. - 이로 인해 컨텍스트 윈도 압박, 관련성 저하, 응답 정확도 하락이 발생한다. - 해결책은 필요한 정보만 추려 LLM에 전달하는 것이다. ## 컨텍스트 엔지니어링의 개념과 원칙 컨텍스트 엔지니어링은 에이전트가 사용하는 모든 문맥 정보를 설계하고 최적화하는 방법이다. - 관리 대상은 세 가지로 나뉜다. - **정적 컨텍스트**: 시스템 프롬프트, 도구 정의 - **동적 컨텍스트**: 사용자 메시지, 대화 이력, RAG 데이터 - **장기 컨텍스트**: 장시간 실행 중 축적되는 정보와 세션 상태 - 핵심 원칙은 “고품질 신호를 가진 최소한의 토큰 집합”을 찾는 것이다. - 정보를 너무 적게 주면 AI가 추측에 의존한다. - 정보를 지나치게 많이 주면 비용이 증가하고 핵심 정보가 묻힌다. - 따라서 작업에 필요한 수준으로 구체적이면서도 불필요한 정보는 제거해야 한다. - 프롬프트 엔지니어링이 지시문 작성에 초점을 둔다면, 컨텍스트 엔지니어링은 프롬프트뿐 아니라 도구, 데이터, 이력, 상태까지 포함해 전체 입력 환경을 최적화한다. ## ADK를 활용하는 이유 Google의 오픈소스 AI 에이전트 프레임워크인 ADK는 컨텍스트 엔지니어링을 팀 단위로 적용하기에 적합하다. - 개인의 CLI 숙련도에 의존하지 않고 팀의 지식을 에이전트 설계에 반영할 수 있다. - UI, API 서버, 평가 기능, 멀티 에이전트 구성을 제공한다. - 에이전트를 조합하고 도구처럼 호출할 수 있어 컨텍스트를 분리하기 쉽다. - 컨텍스트 엔지니어링을 위한 9개 핵심 컴포넌트를 조합해 사용할 수 있다. ## 주요 ADK 컴포넌트 실습에서는 다음 세 가지 기능을 중심으로 설명한다. - **Structuring Data** - 입력과 출력을 특정 JSON 스키마로 강제한다. - 에이전트 간 데이터 전달 형식을 명확히 한다. - 불필요한 자연어 설명을 줄여 토큰 사용량을 절감한다. - **AgentTool** - 다른 에이전트를 함수나 도구처럼 호출한다. - 하위 에이전트의 내부 도구와 중간 컨텍스트를 호출자에게 노출하지 않는다. - 최종 결과만 반환해 상위 에이전트의 컨텍스트 누적을 막는다. - **MCP Toolset의 `tool_filter`** - MCP 서버가 제공하는 도구 중 필요한 도구만 선택한다. - 예를 들어 Jira 티켓 검색에는 `jira_search`, 상세 조회에는 `jira_get_issue`만 허용할 수 있다. - 불필요한 도구 정의를 제거해 토큰 비용과 LLM의 판단 부담을 줄인다. ## Jira 주간 보고서 에이전트: v1의 문제 v1은 하나의 에이전트가 Jira 티켓 검색, 개별 티켓 상세 조회, 분석, 보고서 작성을 모두 수행하는 구조다. - 단일 에이전트에 Jira 관련 도구를 모두 제공한다. - 티켓마다 상세 정보를 가져와 같은 컨텍스트에 계속 축적한다. - 티켓 수가 증가할수록 컨텍스트가 커지고 컨텍스트 부패가 발생한다. - 여러 도구의 정의와 중간 결과가 함께 전달되어 토큰 사용량이 커진다. - 장시간 작업에서 중요한 티켓 정보와 불필요한 이전 정보가 섞일 가능성이 높다. ## Jira 주간 보고서 에이전트: v2의 개선 v2는 역할을 분리한 2-에이전트 구조로 변경했다. - **루트 에이전트** - Jira 티켓 목록을 검색한다. - 개별 티켓 분석 에이전트를 호출한다. - 각 분석 결과를 Markdown 표 형태의 주간 보고서로 집계한다. - **개별 티켓 분석 에이전트** - 하나의 Jira 티켓만 담당한다. - `issue_key`를 입력으로 받고 `report`를 구조화된 출력으로 반환한다. - Jira 상세 조회 도구인 `jira_get_issue`만 사용할 수 있다. - 사실만 포함하고 추측은 금지하도록 지시된다. - `AgentTool`을 통해 하위 에이전트의 내부 처리 과정은 루트 에이전트에 노출하지 않는다. - `input_schema`와 `output_schema`로 에이전트 간 데이터 형식을 제한한다. - `tool_filter`로 각 에이전트가 실제로 필요한 MCP 도구만 사용하게 한다. - 결과적으로 티켓별 상세 분석 컨텍스트가 루트 에이전트에 불필요하게 누적되는 것을 줄인다. AI 에이전트를 설계할 때는 프롬프트를 길게 작성하는 것보다 어떤 정보를 언제, 어떤 형식으로 전달할지 먼저 설계하는 것이 중요하다. 특히 작업을 하위 에이전트로 분리하고, 입력·출력 스키마와 도구 필터를 적용하면 비용과 정확도를 함께 개선할 수 있다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜대규모 언어 모델AI 에이전트쿠버네티스+3

line·2026년 5월 15일·3분 읽기큐레이션 요약

ODW #6: Git 자동화 관점에서 본 MCP와 에이전트 스킬의 장단점

AI 에이전트 개발에서는 MCP 서버보다 에이전트 스킬이 구현과 아키텍처 측면에서 간단해지는 추세다. 글은 `skill-creator`를 활용해 Git 릴리스 자동화 스킬을 만들고, 요구사항을 구체화하는 과정을 실무 예제로 설명한다. 핵심은 명확한 프롬프트와 로컬 Python 스크립트를 결합해 반복 작업을 자동화하는 것이다. ## MCP에서 에이전트 스킬로의 전환 - MCP 서버 구축보다 에이전트 스킬이 구현하기 쉽고 구조가 단순하다. - 기본 개념이나 대규모 GitHub 예제는 많지만, 일상 업무에 적용하는 실용적인 안내는 부족하다. - 이 글은 스킬 자체의 개념을 깊게 설명하기보다 실제 예제를 만들며 활용 방법을 보여주는 데 초점을 둔다. ## Git 스마트 릴리스 자동화 스킬 - 현재 디렉터리의 Git 프로젝트를 자동으로 릴리스하는 스킬을 예제로 선택했다. - `skill-creator`를 사용해 스킬 정의와 실행 스크립트를 자동 생성한다. - 핵심 작업 흐름은 다음과 같다. - 가장 최근 태그 이후의 `git log` 분석 - 변경 사항을 요약해 `CHANGELOG.md` 최상단에 추가 - `pyproject.toml`의 버전 변경 - 변경 파일 커밋 - 새 버전 태그 생성 - 스킬은 현재 터미널 경로인 `pwd`를 기준으로 동작하는 로컬 Python 스크립트 형태로 구성한다. ## 명확한 요구사항의 중요성 - 에이전트가 엉뚱한 디렉터리를 수정하거나 과도하게 복잡한 계획을 세우지 않도록 목표와 제약 조건을 프롬프트에 구체적으로 작성해야 한다. - 초기 요구사항에는 다음 내용이 포함된다. - `v0.1.0` 등 최근 태그 이후의 커밋 조회 - `CHANGELOG.md`가 없으면 새로 생성 - 버전을 patch 단위로 증가 - `chore: release v[새 버전]` 형식으로 커밋 - 새 버전의 Git 태그 생성 - 현재 작업 경로에서만 실행 ## 대화형 요구사항 구체화 에이전트는 모호한 부분을 질문하고, 사용자는 답변을 통해 스킬 동작을 확정한다. - 버전 증가 방식 - patch, minor, major 모두 지원 - 사용자가 원하는 릴리스 유형을 선택 - 최초 릴리스 - 기존 태그가 없으면 `v0.1.0`부터 시작 - 변경 로그 - Keep a Changelog 형식을 따름 - 버전, 날짜, `feat`, `fix`, `docs` 등의 변경 분류를 포함 - 원격 저장소 - 로컬 커밋과 태그 생성 후 원격 저장소에도 push - 작업 디렉터리 안전성 - 커밋되지 않은 변경 사항이 있으면 작업을 중단 - 중단 이유를 사용자에게 설명 ## 생성된 스킬의 구조 - `git-smart-release/SKILL.md` - 스킬의 메타데이터와 에이전트가 따라야 할 실행 절차를 담는다. - `git-smart-release/scripts/smart_release.py` - Git 명령 실행, 파일 수정, 버전 변경 등 실제 작업을 수행한다. - `git-smart-release/evals/evals.json` - 스킬 동작을 검증하기 위한 테스트 케이스를 담는다. ## SKILL.md와 실행 스크립트의 역할 - 프런트매터 - YAML 형식의 메타데이터다. - 에이전트가 스킬을 언제 사용할지 판단할 수 있도록 짧은 설명과 검색 정보를 제공한다. - 마크다운 본문 - 스킬 사용이 결정된 뒤 읽히는 실행 매뉴얼이다. - 구체적인 절차와 워크플로를 정의한다. - `smart_release.py` - Git 상태 확인, 로그 분석, 파일 변경, 커밋과 태그 생성 등을 직접 처리한다. - LLM이 모든 파일 내용을 직접 읽고 수정하는 대신 결정된 작업을 코드로 실행해 토큰 사용과 오류를 줄인다. ## 실무 적용 방식 - 사용자는 “릴리스해 줘”처럼 자연어로 요청할 수 있다. - 에이전트는 요청에 맞는 버전 유형을 선택하고 스킬 지침을 따른다. - 스크립트는 먼저 작업 디렉터리가 깨끗한지 확인한다. - 변경 사항이 있으면 안전을 위해 중단하고, 문제가 없을 때만 변경 로그 작성부터 커밋·태그·원격 push까지 진행한다. - 글은 이후 Python 계산기 프로젝트를 대상으로 제작한 스킬을 테스트하는 시나리오로 이어진다. 반복적인 Git 릴리스 업무를 자동화하려면 요구사항, 예외 처리, 실행 범위를 프롬프트에 명확히 적고, 실제 파일·Git 조작은 검증 가능한 스크립트로 분리하는 것이 좋다. 특히 자동 push 기능은 되돌리기 어려우므로 dirty check와 실행 전 확인 절차를 함께 두는 것을 권장한다.

원문 읽기(새 탭에서 열림)

모델 컨텍스트 프로토콜Pythonclaude-codeGit+3

line·2026년 5월 7일원문

ODW #5: 벡터 DB와 에이전트 스킬로 RAG 시스템 만들기 (새 탭에서 열림)

LY Corporation에서 진행된 이번 워크숍은 대량의 마크다운 문서를 효율적으로 검색하기 위해 ChromaDB 기반의 RAG(검색 증강 생성) 시스템을 구축하고, 이를 에이전트 스킬과 결합하여 개발자 경험을 혁신하는 방법을 다룹니다. 단순히 문서를 데이터베이스화하는 것을 넘어, AI 에이전트가 데이터의 구조와 활용법을 이해하도록 돕는 '스킬' 정의를 통해 검색 정확도와 업무 효율을 동시에 높이는 실무적인 접근법을 제시합니다. 이러한 시스템은 향후 자연어 기반의 문서 검색을 넘어 코드 생성 및 리뷰 프로세스에 지식 베이스를 직접 연결하는 핵심 도구로 활용될 수 있음을 시사합니다. ### 개발 생산성 향상을 위한 RAG의 도입 배경 * 대규모 앱 개발 과정에서 발생하는 빌드 에러, 아키텍처 가이드라인 준수 등의 문제를 해결하기 위해 방대한 문서가 존재하지만, 이를 검색하고 숙지하는 데 많은 리소스가 소모됩니다. * 동료 전문가에게 직접 질문하는 방식은 질문자와 답변자 모두의 시간을 소모하므로, 자연어로 대량의 데이터를 검색할 수 있는 자동화된 구조가 필요합니다. * RAG 기법을 도입하면 AI 에이전트에게 신뢰할 수 있는 외부 지식을 제공하여, 환각 현상을 줄이고 보다 정확한 응답을 생성할 수 있습니다. ### ChromaDB와 Swift Evolution을 활용한 데이터 적재 * 오픈소스 벡터 DB인 ChromaDB를 활용하여 로컬 환경에서 파이썬 및 자바스크립트 라이브러리를 통해 데이터를 간단히 적재하는 시스템을 구축했습니다. * 약 500여 건의 Swift 언어 사양 제안 문서(Swift Evolution)를 예제로 사용하였으며, 이는 ID(SE-XXXX), 구현 상태, 작성자 등 정형화된 메타데이터를 포함하고 있어 RAG 실습에 적합합니다. * 워크숍에서는 로컬 DB를 구축하고 MCP(Model Context Protocol) 도구를 통해 Claude Code와 같은 코딩 에이전트가 DB를 참조하도록 구성했습니다. ### 에이전트 스킬을 통한 지능형 검색 최적화 * 단순히 MCP 도구만 연결하면 에이전트가 DB의 컬렉션 명이나 메타데이터 구조를 몰라 검색에 어려움을 겪을 수 있으므로, 이를 보완하기 위한 '에이전트 스킬'을 정의했습니다. * 스킬 내부에 "Swift Evolution 지식을 검색하려면 ChromaDB의 특정 컬렉션을 참조한다"는 지침과 메타데이터 활용법을 명시하여 에이전트의 컨텍스트를 강화했습니다. * 이를 통해 사용자가 "SE-0500에 대해 조사해줘"라는 짧은 명령어만 입력해도 에이전트가 스스로 최적의 검색 파라미터를 설정하여 정확한 정보를 찾아내게 됩니다. ### RAG 시스템의 확장과 실무 적용 * 구축된 시스템은 단순한 문서 검색을 넘어, 코딩 에이전트가 스스로 지식을 검색해 코드를 생성하거나 특정 규칙에 기반하여 코드 리뷰를 수행하는 등 고도화된 업무에 활용 가능합니다. * 워크숍에서는 참가자들이 직접 마크다운 문서를 DB에 적재하고 스킬을 작성하는 실습을 진행했으며, 결과물을 사내 클라우드(Flava)에 배포하여 공유하는 방법까지 포함했습니다. * 1,000명 이상의 직원이 참여한 이번 사례는 이론적인 개념 전달과 실제 업무 문서를 활용한 실습의 균형이 AI 도구 내재화에 얼마나 중요한지를 보여줍니다. 방대한 내부 문서를 보유한 조직이라면 ChromaDB와 같은 가벼운 벡터 DB와 MCP 기반의 에이전트 스킬을 결합해 보시기 바랍니다. 초기 구축 비용 대비 개발자가 정보를 찾는 시간을 획기적으로 단축할 수 있으며, 특히 사내 코딩 표준이나 복잡한 도메인 지식을 AI 에이전트에게 즉시 학습시키는 가장 효율적인 경로가 될 것입니다.

모델 컨텍스트 프로토콜AI 에이전트RAGclaude-code+4

line·2026년 4월 24일원문

ODW #4: 코파일럿에서 파일럿으로, 에이전틱 코딩으로 구현부터 PR까지 자동화 (새 탭에서 열림)

LY Corporation의 'Orchestration 길드'는 단순한 코드 보조를 넘어 AI가 자율적으로 개발 사이클을 주도하는 '에이전틱 코딩(Agentic Coding)'으로의 전환을 제안합니다. 명세 주도 개발(SDD)과 MCP(Model Context Protocol)를 결합하여 AI 에이전트가 기획 문서를 읽고 구현 계획 수립부터 풀 리퀘스트(PR) 작성까지 수행하도록 하는 것이 핵심입니다. 이를 통해 개발자는 단순 반복 업무에서 벗어나 고차원적인 설계와 검토에 집중함으로써 전체적인 생산성을 비약적으로 높일 수 있습니다. **단순 보조를 넘어선 에이전틱 코딩의 정의** * 기존 AI 도구가 코드 자동 완성 수준에 머물렀다면, 에이전틱 코딩은 고수준의 목표를 스스로 분해하고 자율적으로 실행하며 피드백을 통해 조정하는 방식입니다. * AI 에이전트가 전체 코드베이스와 파일 간 관계를 이해하고, 테스트 실패 시 스스로 수정하며 빌드 성공까지 반복하는 '파일럿' 역할을 수행합니다. * Jira와 Confluence 같은 사내 시스템을 MCP로 연결하여 AI가 최신 요구 사항 명세서를 직접 참조할 수 있는 환경을 구축하는 것이 기술적 토대가 됩니다. **1단계: MCP 기반의 구현 계획 수립과 리뷰** * 에이전틱 코딩의 성패는 초기 구현 계획의 정교함에 달려 있으며, 이를 위해 Jira와 Confluence URL에서 정보를 수집하는 커스텀 슬래시 명령어를 활용합니다. * Claude Code의 'Explore Agent' 기능을 병렬로 사용하여 메인 컨텍스트를 유지하면서도 광범위한 코드 분석과 문서 조사를 동시에 수행합니다. * 분석 결과는 `plan.md`와 같은 독립된 파일로 출력하여 사람이 미리 리뷰할 수 있게 함으로써, AI가 엉뚱한 방향으로 구현을 시작하는 리스크를 방지합니다. **2단계: 자율적 구현과 품질 검증 및 PR 작성** * 확정된 구현 계획서를 바탕으로 AI가 코드를 작성하며, 단순 생성을 넘어 테스트 코드 추가, 린트(Lint), 빌드(Build) 과정을 스스로 반복합니다. * 작업 단계를 명시한 커스텀 명령어를 통해 AI가 할 일 목록(To-do list)을 생성하고 누락 없이 작업을 완수하도록 가이드합니다. * 구현 완료 후에는 미리 정의된 템플릿에 따라 배경, 대응 영역, 테스트 관점 등을 포함한 상세한 PR 설명을 자동으로 작성하여 공유합니다. **3단계: AI 셀프 리뷰와 피드백 대응** * 작성된 PR에 대해 AI가 스스로 스크리닝 리뷰를 수행하고, 잠재적인 오류나 개선 사항에 대해 코멘트를 남깁니다. * AI는 자신의 셀프 코멘트뿐만 아니라 다른 팀원이 남긴 리뷰 내용까지 파악하여 수정안을 제시하고 실제 코드에 반영합니다. * 이 과정에서 사람은 AI가 내린 판단의 적절성만 최종 승인함으로써 리뷰 및 수정에 드는 비용을 획기적으로 줄입니다. **에이전틱 코딩 도입의 성과와 과제** * **장점:** 여러 에이전트를 병렬로 실행하여 코드 생성 속도를 높일 수 있으며, 사전 계획 수립 과정을 통해 잠재적 리스크를 조기에 발견할 수 있습니다. * **주의 사항:** AI가 생성한 대량의 코드를 검토해야 하는 리뷰어의 부담이 커질 수 있으므로, '최종 책임은 사람에게 있다'는 인식과 품질 유지 프로세스가 필수적입니다. * **워크숍 결과:** 약 2,500명의 엔지니어가 참여하여 40% 이상이 실무에 적용하거나 활용할 의사를 밝히는 등 긍정적인 확산 효과를 확인했습니다. 에이전틱 코딩을 성공적으로 도입하기 위해서는 명확한 명세서 작성을 선행하고, AI가 작업 계획을 파일 형태로 기록하게 하여 사람과의 접점을 만드는 것이 중요합니다. 기술 부채를 방지하기 위해 AI가 작성한 코드의 품질을 엄격히 관리하는 체계를 병행할 것을 권장합니다.

모델 컨텍스트 프로토콜AIgithub-copilotagentic-coding+4

line·2026년 4월 15일원문

ODW #2: ADK로 싱글/멀티 에이전트를 개발해 사내 시스템과 통합 (새 탭에서 열림)

LY Corporation은 사내 AI 활용의 개인차를 극복하고 업무 생산성을 높이기 위해 'ADK(Agent Development Kit)'를 활용한 싱글 및 멀티 에이전트 개발 워크숍을 진행했습니다. 이 워크숍은 개인 중심의 AI 도구 활용에서 벗어나, 팀 단위로 최적화된 AI 에이전트를 구축하고 MCP(Model Context Protocol)를 통해 사내 시스템과 통합하는 실무 지식을 공유하는 데 중점을 두었습니다. 결과적으로 복잡한 업무를 자동화하는 멀티 에이전트 시스템을 직접 구현함으로써 지식 사일로 현상을 해소하고 조직 차원의 기술 상향 평준화를 목표로 하고 있습니다. **사내 AI 활용의 한계와 워크숍의 필요성** * **지식의 사일로화:** 개인별로 로컬 AI 도구(Cline, Claude Code 등)를 사용하면서 활용 능력에 따른 생산성 격차가 발생하고, 유사한 문제에 대해 각자 프롬프트를 최적화하는 중복 작업이 빈번해졌습니다. * **싱글 에이전트의 한계:** 단일 LLM 기반 에이전트만으로는 복잡한 비즈니스 로직이나 전문적인 대응에 한계가 있으며, 이를 해결할 수 있는 멀티 에이전트 개념에 대한 이해가 부족한 상황이었습니다. * **정보 접근의 어려움:** Jira, Confluence 등 사내 시스템에 파편화된 정보를 검색하고 요약하는 데 많은 시간이 소요되어, 이를 자동화할 수 있는 중앙 집중형 에이전트 호스팅의 필요성이 대두되었습니다. **에이전트 개발 도구: ADK와 MCP** * **ADK (Agent Development Kit):** 에이전트의 동작을 정의하고 멀티 에이전트 시스템을 구현하기 위한 오픈소스 프레임워크입니다. Python 등을 활용해 함수를 정의하면 에이전트가 이를 도구(Tool)로 인식하여 실행할 수 있게 해줍니다. * **MCP (Model Context Protocol):** LLM을 Jira, Confluence와 같은 외부 시스템과 연결하는 표준 프로토콜입니다. 이를 통해 에이전트가 사내 문서나 업무 이력을 능동적으로 탐색하고 활용할 수 있는 환경을 제공합니다. * **컨텍스트 관리:** 너무 많은 도구를 에이전트 하나에 부여하면 정확도가 떨어지므로, 멀티 에이전트 구조를 통해 역할별로 컨텍스트를 분리하여 성능을 최적화합니다. **멀티 에이전트를 활용한 '프로젝트 추적기' 구현** * **순차적 에이전트(Sequential Agent) 구조:** 복잡한 프로젝트 관리 업무를 해결하기 위해 4개의 특화된 에이전트를 순차적으로 연결하는 파이프라인을 구성했습니다. * **단계별 역할 분담:** * 1단계: 진행 중인 작업 분석(Jira 데이터 수집) * 2단계: 할 일(Todo) 목록 분석 및 우선순위 파악 * 3단계: 수집된 정보를 종합하여 마크다운 형식의 리포트 생성 * 4단계: 생성된 리포트를 지정된 언어로 번역 * **실무 적용 효과:** 사용자가 일일이 데이터를 찾고 정리할 필요 없이, 멀티 에이전트 시스템이 사내 시스템에 접속하여 분석부터 번역까지 완료된 종합 보고서를 즉시 제공합니다. 단순히 AI 도구를 도입하는 것을 넘어, 팀의 고유한 도메인 지식과 사내 시스템을 결합한 '팀 전용 에이전트'를 구축하는 것이 중요합니다. ADK와 같은 프레임워크를 활용해 멀티 에이전트 환경을 구축하고 이를 호스팅하여 공유한다면, 개인의 프롬프트 엔지니어링 역량에 의존하지 않고 조직 전체의 업무 효율을 상향 평준화할 수 있습니다.

모델 컨텍스트 프로토콜AI쿠버네티스Python+4

line·2025년 12월 19일원문

사내 AI 리터러시를 향상하기 위한 AI Campus Day를 개최했습니다 (새 탭에서 열림)

LY Corporation은 전 직군의 AI 리터러시를 높이고 실무 적용을 독려하기 위해 사내 실습 행사 'AI Campus Day'를 개최했습니다. 외부 강사 대신 사내 전문가인 'AI 멘토'를 활용하고 실습 중심의 핸즈온 세션을 구성함으로써, 보안 가이드라인과 사내 업무 환경에 최적화된 실질적인 AI 활용 노하우를 성공적으로 전파했습니다. 이번 행사는 단순한 교육을 넘어 축제 형태의 운영 방식을 도입하여 임직원들이 자발적으로 AI 기술을 탐색하고 업무 생산성을 높이는 계기를 마련했습니다. **실무 역량 강화를 위한 수준별 핸즈온 세션** * **직군별 맞춤 트랙 운영:** 'Common', 'Creative', 'Engineering'의 3개 트랙으로 나누어, 기초 프롬프팅부터 MCP(Model Context Protocol) 서버 구축과 같은 심화 주제까지 총 10개의 세션을 제공했습니다. * **단계별 난이도 설계:** 참가자의 AI 활용 수준에 맞춰 3단계 레벨을 설정하여, 비개발 직군부터 엔지니어까지 누구나 자신의 수준에 맞는 학습이 가능하도록 했습니다. * **철저한 실습 지원 체계:** 흐름을 놓치지 않도록 상세한 '세션 가이드'를 제작 배포하고, 세션마다 2~3명의 조교(총 26명)를 배치하여 현장에서 발생하는 기술적 문제를 즉각 해결했습니다. * **Slack 기반의 소통:** 각 세션별 채널을 통해 실습 결과물을 실시간으로 공유하고 질의응답을 진행하여 참여도를 높였습니다. **사내 콘텍스트를 반영한 AI 멘토링** * **내부 전문가 활용:** 외부 강사 대신 사내에서 이미 AI를 적극적으로 활용 중인 동료 10명을 멘토로 선발하여 현장감 있는 지식을 공유했습니다. * **최적화된 도구 활용:** ChatGPT Enterprise, Gemini, Claude Code 등 사내에서 허용된 도구와 보안 수칙을 100% 반영하여, 배운 내용을 즉시 업무에 적용할 수 있는 환경을 구축했습니다. * **체계적인 콘텐츠 검토:** 운영진은 멘토 가이드를 제공하고, '주제 검토 - 최종 자료 리뷰 - 리허설'로 이어지는 다단계 프로세스를 통해 교육 콘텐츠의 완성도를 확보했습니다. **자발적 참여를 유도하는 축제형 운영** * **캠퍼스 테마 도입:** 수강 신청, 등교, 스탬프 랠리 등 대학교 캠퍼스 컨셉을 활용하여 학습에 대한 심리적 장벽을 낮추고 즐거운 분위기를 조성했습니다. * **몰입형 이벤트 부스:** Gemini를 활용한 AI 포토존, 자체 개발 AI 업무 지원 솔루션 체험, AI 에이전트 콘테스트 홍보 등 다채로운 부스를 운영하여 AI의 효용성을 직접 경험하게 했습니다. * **리더십의 전폭적 지지:** 경영진의 축전 영상을 통해 '업무 대신 AI와 함께 노는 하루'라는 메시지를 전달함으로써, 임직원들이 심리적 부담 없이 행사에 몰입할 수 있는 환경을 만들었습니다. 성공적인 사내 AI 전환(AX)을 위해서는 단순한 도구 보급을 넘어, 사내 보안 가이드와 업무 맥락을 정확히 이해하는 내부 전문가 중심의 실습 교육이 필수적입니다. AI Campus Day와 같이 학습을 '숙제'가 아닌 '축제'로 인식하게 만드는 운영 전략은 구성원들의 자발적인 기술 수용도를 높이는 데 매우 효과적인 접근 방식이 될 것입니다.

모델 컨텍스트 프로토콜AI생성형 AIgemini+5

line·2025년 11월 4일원문

AI 제품 개발 중 마주칠 수 있는 보안 위협 사례와 대책 방안 (새 탭에서 열림)

AI 제품 개발은 생산성을 비약적으로 높여주지만, 환각 현상이나 프롬프트 주입과 같은 새로운 형태의 보안 위협을 동반합니다. 이러한 리스크는 단순히 오답을 제공하는 수준을 넘어 악성코드 설치, 원격 코드 실행(RCE), 민감 정보 유출로 이어질 수 있어 기존과는 다른 다각도의 방어 전략이 필요합니다. LY Corporation은 실제 사례 분석을 통해 AI 모델과 외부 도구 간의 접점을 보호하고 보안 검토를 자동화하는 등의 대응 방안을 구축하고 있습니다. ## 슬랍스쿼팅(Slopsquatting)과 패키지 오인 * AI가 존재하지 않는 소프트웨어 패키지 이름을 마치 실제인 것처럼 제안하는 '환각(Hallucination)' 현상을 악용한 공격입니다. * 예를 들어, AI가 `huggingface_hub[cli]` 대신 `huggingface-cli`라는 잘못된 패키지 설치를 권장할 때, 공격자가 미리 해당 이름으로 악성 패키지를 등록해 두면 사용자가 이를 설치하게 됩니다. * 이를 방지하기 위해 AI가 생성한 코드나 설치 지침을 실행하기 전 반드시 공식 문서와 대조하여 검증하는 절차가 필수적입니다. ## 프롬프트 주입을 통한 원격 코드 실행(RCE) * Vanna AI 사례(CVE-2024-5565)와 같이 자연어를 SQL이나 파이썬 코드로 변환하여 직접 실행하는 서비스에서 주로 발생합니다. * 사용자가 입력창에 악의적인 명령을 주입하여 애플리케이션 권한 내에서 임의의 시스템 명령어를 실행하도록 유도할 수 있습니다. * LLM을 전적으로 신뢰하여 코드를 실행하게 두지 말고, 사용자 입력을 엄격히 검증(Sanitize)하며 데이터 생성 용도로만 제한적으로 활용해야 합니다. ## 오피스 AI에서의 간접 프롬프트 주입 * 이메일이나 문서 본문에 숨겨진 악성 지시사항을 AI가 읽고 실행하게 만드는 '간접 주입' 방식의 위협입니다. * 가령, 피싱 사이트로 유도를 하거나 비밀번호 변경을 종용하는 문구가 포함된 이메일을 AI가 요약하는 과정에서 사용자를 속이는 스크립트를 수행하게 될 수 있습니다. * 입력 데이터뿐만 아니라 AI가 내놓는 출력물에 대해서도 가드레일(Guardrails)을 적용하여 이상 징후를 탐지하는 이중 방어 체계가 필요합니다. ## 코딩 에이전트의 권한 남용 및 데이터 노출 * GitHub MCP(Model Context Protocol)와 같이 자동화된 코딩 에이전트가 공개 저장소와 비공개 저장소에 동시에 접근할 때 발생합니다. * 공개 저장소의 이슈나 PR에 포함된 악성 명령어가 에이전트를 통해 실행되면, 에이전트의 권한을 이용해 비공개 저장소에 있는 급여 정보나 개인정보를 외부로 유출할 수 있습니다. * 에이전트가 접근 가능한 데이터 범위를 최소화하고, 작업 단위별로 권한을 분리하는 보안 디자인이 중요합니다. ## 임베딩 인버전(Embedding Inversion)을 통한 정보 복원 * 텍스트 데이터를 수치화한 벡터 임베딩 값으로부터 원본 텍스트를 역으로 추론해내는 공격 기법입니다. * 임베딩 데이터 자체가 유출될 경우, 비식별화되었다고 판단했던 민감한 정보가 다시 복원되어 프라이버시 침해로 이어질 수 있습니다. * 벡터 데이터베이스에 대한 접근 제어를 강화하고 임베딩 데이터의 보안 수준을 원본 데이터와 동일하게 관리해야 합니다. AI 프로덕트의 안전성을 확보하기 위해서는 기획 단계에서의 보안 디자인 리뷰는 물론, 위협 모델링 자동화 도구인 'ConA'나 소스 코드 취약점 분석 자동화 도구인 'LAVA'와 같은 기술적 솔루션을 적극적으로 도입하여 보안 프로세스를 내재화하는 것이 권장됩니다.

모델 컨텍스트 프로토콜AI대규모 언어 모델ai-security+5

line·2025년 8월 12일원문

LY Corporation의 AI 기술의 현재, Tech-Verse 2025 후기 (새 탭에서 열림)

Tech-Verse 2025는 LY Corporation이 LINE과 Yahoo Japan의 통합 이후 선보인 AI 전략의 핵심과 실무적인 기술 성과를 집약적으로 보여준 행사였습니다. 이번 컨퍼런스에서는 단순한 기술 트렌드 나열을 넘어, RAG와 MCP 등 최신 AI 기술을 실제 서비스와 개발 환경에 적용하며 겪은 시행착오와 구체적인 해결 방안이 중점적으로 다뤄졌습니다. 특히 AI가 개발 프로세스 전체에 스며들어 생산성과 품질을 동시에 확보하는 기술적 내공이 강조되었습니다. **AI 기반 개발 생산성 혁신: Ark Developer** * 사내 개발자들을 위해 구축된 'Ark Developer'는 RAG 기반의 코드 어시스턴트로, 코드 자동 완성, 리뷰, 보안 확인, 테스트 코드 작성을 지원합니다. * 사내 문서를 스트리밍 형태로 실시간 참조하여 코드의 맥락에 맞는 정확한 도움을 제공하며, GitHub와 연동되어 PR 생성까지 자동화된 워크플로우를 보여줍니다. * 단순히 코드 베이스를 텍스트 뭉치로 취급하는 대신, 디렉토리 구조를 그래프 형태로 분석(Graph Analysis)하여 연관 코드를 더욱 정밀하게 참조하는 기술적 차별점을 갖췄습니다. * 실제 현업 개발자들 사이에서 기존의 범용 AI 도구보다 체감 성능이 뛰어나다는 평가를 받으며 개발 사이클 전반에 깊숙이 통합되어 활용되고 있습니다. **생성형 AI의 품질 측정과 정교한 평가 체계** * 주관성이 강한 이미지 생성 기술의 품질을 관리하기 위해 분포 기반의 FID(Fréchet Inception Distance), IS(Inception Score)와 같은 전통적 지표를 넘어 다각적인 평가 모델을 도입했습니다. * 미적 기준을 측정하는 Aesthetic Score, LLM 기반의 CLIP-IQA 및 Q-Align, 그리고 비디오-언어 모델을 활용한 VQA(Visual Question Answering) 방식 등 정밀한 정량 평가를 수행합니다. * 이미지 번역 및 인페인팅 서비스에서는 단순한 텍스트 변환을 넘어 원래의 레이아웃과 구조까지 자연스럽게 복원해야 하는 복합적인 과제를 생성형 AI로 해결하고 있습니다. * 생성형 AI 기술의 완성도는 단순히 모델을 구현하는 것에 그치지 않고, '어떻게 정답이 없는 결과를 객관적으로 검증하고 개선할 것인가'에 달려 있음을 시사합니다. **실무형 AI 도입을 위한 통찰** 이번 컨퍼런스는 LLM과 에이전트 기술이 실험실을 벗어나 실제 서비스의 품질을 결정짓는 성숙기에 접어들었음을 보여줍니다. 특히 생성형 AI 결과물에 대한 정량적 평가 지표를 수립하고, 코드 베이스를 그래프 구조로 분석하는 등의 구체적인 접근법은 AI 서비스를 고도화하려는 실무자들에게 매우 유용한 벤치마킹 사례가 될 것입니다. 단순한 기술 도입보다는 우리 조직의 데이터 구조와 서비스 특성에 맞는 '평가와 검증 체계'를 먼저 고민하는 것이 품질 높은 AI 서비스를 만드는 핵심입니다.

모델 컨텍스트 프로토콜AI대규모 언어 모델RAG+5

line·2025년 6월 13일원문

AI와 글쟁이의 동행: 코드 주면 API 레퍼런스 써드려요 (새 탭에서 열림)

기술 문서 부족 문제를 해결하기 위해 엔지니어링 관점에서 접근한 이 글은, 생성형 AI를 활용해 사내 기술 컨텍스트와 스타일 가이드가 반영된 API 레퍼런스를 자동 생성하는 프로젝트 과정을 소개합니다. 일반적인 코딩 어시스턴트의 한계를 극복하기 위해 프롬프트 워크플로를 최적화하고, 특정 IDE에 종속되지 않도록 MCP(Model Context Protocol)를 도입하여 범용성을 확보했습니다. 최종적으로 AI가 생성한 결과물은 높은 품질을 보였으나, 기술 문서의 특성상 정확성을 담보하기 위한 인간의 검토 단계가 필수적임을 강조하며 결론을 맺습니다. ## 기존 AI 도구의 한계와 도큐먼트 엔지니어링의 목표 * 기술 문서는 항상 부족하며, 개발자 교육만으로는 시간과 관심의 부재라는 근본적인 원인을 해결하기 어렵다는 판단하에 자동화 프로세스를 구축했습니다. * GitHub Copilot과 같은 기존 도구는 코드 파악 능력은 뛰어나지만, 사내 전용 기술 용어나 특수한 스타일 가이드, 프로젝트별 컨텍스트를 반영하지 못하는 단점이 있습니다. * '사내 정보를 참고해 스타일 가이드에 맞는 API 주석을 작성하고, 이를 한곳에서 배포하기'를 목표로 테크니컬 라이터의 노하우를 자동화 공정에 이식했습니다. ## 프롬프트 최적화와 단계별 워크플로 구성 * 초기에는 방대한 지시 사항이 담긴 긴 프롬프트를 사용했으나, LLM이 복잡한 지시를 놓치는 문제가 발생하여 실행 단계를 세분화했습니다. * 처리 속도와 정확도 사이의 타협점을 찾기 위해 '프로그래밍 언어 인식', 'API 파악 및 예제 작성', '설명 및 파라미터/응답 값 작성'의 3단계 워크플로로 압축했습니다. * LINE의 고유 식별자인 'MID'를 단순한 약어(Member ID 등)로 오해하지 않고 사내 정의에 맞게 설명하도록 컨텍스트를 주입하여 일반 AI 도구와 차별화된 품질을 구현했습니다. ## 범용성 확보를 위한 MCP(Model Context Protocol) 도입 * 초기 프로토타입은 VS Code 익스텐션으로 제작했으나, IntelliJ 등 다양한 IDE를 사용하는 개발자들의 요구를 수용하기 위해 MCP 기반으로 전환했습니다. * MCP 서버는 클라이언트와의 통신에만 집중하므로, UI 구현에 드는 비용을 줄이고 언어 판별이나 코드 블록 선택 같은 부가 기능을 MCP 호스트(IDE 등)에 위임할 수 있습니다. * 사용자가 AI와 대화하며 파라미터를 입력하는 방식은 현대적인 AI 사용 경험에 부합하며, 특정 도구에 종속되지 않는 범용적인 문서화 솔루션을 제공합니다. ## AI 문서화의 성과와 실질적인 한계 * 자체 평가 결과, 생성된 주석의 88%가 기준을 만족했으며 78%의 사례에서 GitHub Copilot보다 우수한 품질의 설명을 생성하는 성과를 거두었습니다. * 그러나 AI는 확률 기반으로 작동하므로 100%의 정확성을 보장하지 못하며, 단 한 줄의 오류가 문서 전체의 신뢰도를 떨어뜨리는 API 레퍼런스의 특성상 위험 요소가 존재합니다. * 따라서 AI를 '완벽하지 않은 동반자'로 정의하고, AI가 초안을 대량으로 빠르게 생산하되 마지막 단계에서는 반드시 담당 개발자가 내용을 검토하는 '사람 중심의 검증' 프로세스를 권장합니다.

모델 컨텍스트 프로토콜AI대규모 언어 모델생성형 AI+4