AI 하네스란 무엇인가

ICLR 2026를 계기로 harness(실행 계층)와 scaffold(행동 정의 계층)를 분리하는 좁은 정의가 정리되었지만, 실무 현장에서는 모델을 제외한 모든 것을 통칭하는 포괄적 AI harness 개념이 훨씬 널리 쓰입니다. AI 하네스 wiki에서는 skill, hook, rule 과 같은 포괄적 개념의 하네스에 대해 다룹니다. 본 포스트에서는 하네스와 스캐폴드에 대한 정의에 대해 짧게 정리하였습니다. 1. 하네스 용어 혼란 이 논의는 ICLR...

AI 코딩 에이전트

과거의 AI 코딩 보조 도구가 프롬프트를 입력하고 결과 코드를 복사·붙여넣는 단발성 챗 인터페이스에 가까웠다면, 최근의 AI 코딩 에이전트는 모델을 중심으로 파일 시스템, 터미널, 브라우저, 테스트 러너, 버전 관리 시스템, 외부 API가 결합된 하나의 실행 환경으로 발전하고 있습니다. 이제 AI 코딩 에이전트는 단순히 코드를 생성하는 도구가 아니라, 요구사항을 분석하고 작업을 작은 단위로 나누며, 필요한 파일을 읽고...

settings.json으로 권한과 실행 환경 제어하기

settings.json의 역할 settings.json은 Claude Code의 동작을 JSON으로 제어하는 설정 파일입니다. 주로 다음을 조절합니다. 파일 위치와 우선순위 범위 위치 용도 커밋 여부 우선순위 Managed 서버 관리 설정, MDM/Registry, /etc/claude-code/managed-settings.json 등 조직/관리자가 강제하는 정책 일반적으로 커밋 안 함 가장 높음 CLI 인자 claude --settings ..., --model, --permission-mode 등 현재 세션에만 임시 적용 안 함 Managed 다음 Local...

settings.json으로 권한과 실행 환경 제어하기

VS Code에서 Claude Code 사용하기

VS Code용 Claude Code 확장 프로그램을 설치하고 구성하세요. 인라인 Diff, @-멘션, 계획 검토 및 키보드 단축키를 통해 AI 코딩 지원을 받을 수 있습니다. 이 VS Code 확장 프로그램은 IDE에 직접 통합된 Claude Code의 기본 그래픽 인터페이스를 제공하며, 이는 VS Code에서 Claude Code를 사용하는 권장 방법입니다. 확장 프로그램을 사용하면 Claude의 계획을 수락하기 전에 검토 및 편집하고,...

Claude Code 입문

Claude Code를 활용해 개발 효율을 높이려는 분들을 위한 가이드입니다. Claude Code는 단순한 코드 자동완성을 넘어, 터미널 명령 실행, 파일 편집, 디버깅까지 직접 수행하는 AI 개발 도구입니다. 이 가이드에서는 settings.json을 통해 Claude Code의 권한 범위를 세밀하게 조정하고, 안전하면서도 생산적인 개발 환경을 구축하는 방법을 다룹니다.

참고) Claude Hook Matcher

Claude Hook Matcher 종류 표현 방식 기준 Matcher 종류 예시 의미 주의점 전체 매칭 빈 값, *, matcher 생략 해당 event가 발생할 때마다 실행 자주 실행되는 event에서는 과도하게 넓을 수 있음 정확 매칭 Bash 특정 값과 정확히 일치할 때 실행 tool event에서는 도구 이름과 정확히 일치해야 함 OR 매칭 `Edit|Write` 여러 값 중 하나와 일치하면...

Claude Hook

Claude Hook 은 Claude Code의 특정 lifecycle 지점에서 자동 실행되는 사용자 정의 자동화입니다. 쉽게 말하면, Claude가 작업하는 중간중간에 “반드시 실행되어야 하는 검사나 후처리”를 끼워 넣는 장치입니다. Claude에게 프롬프트로 “위험한 명령은 실행하지 마”, “수정 후 lint를 돌려”, “작업 끝나기 전에 테스트해”라고 지시할 수도 있지만, 프롬프트 지시는 세션이 길어지거나 컨텍스트가 바뀌면 누락될 수 있습니다. 반면 Hook은 Claude의...

Claude Memory

Memory: 세션을 넘어 축적되는 프로젝트 학습 기록 Memory는 Claude가 세션을 넘어 프로젝트별 학습 내용을 기억하는 공간입니다. CLAUDE.md가 사람이 작성한 규칙이라면, Memory는 작업 중 반복해서 배운 사실과 디버깅 패턴을 축적하는 용도입니다. 즉, CLAUDE.md는 “앞으로 항상 이렇게 일하라”는 명시적 운영 규칙이고, Memory는 “이 프로젝트를 다루다 보니 이런 문제가 반복되더라”는 경험 기반 노트에 가깝습니다. Memory에 남기기 좋은 내용:...

Claude Subagents

Claude Subagents: 별도 컨텍스트를 가진 전문 작업자 Claude Subagents 는 별도 컨텍스트에서 동작하는 전문 에이전트입니다. 많은 파일을 읽고 분석해도 중간 과정이 메인 대화에 쌓이지 않고, 최종 요약만 돌아옵니다. subagent 파일 위치 모든 프로젝트에서 재사용할 개인 Subagent는 ~/.claude/agents/에 둘 수 있습니다. 같은 이름의 Subagent가 여러 위치에 있으면 더 높은 우선순위의 위치가 적용됩니다. Subagent 파일은 크게 두...

Claude Skills

Claude Skill은 특정 작업 유형에 대한 지식과 절차를 담는 재사용 단위입니다. 디렉터리 이름이 직접 호출 이름이 되며, description은 Claude가 자동으로 사용할지 판단하는 핵심 단서입니다. Skill에 넣기 좋은 내용은 다음과 같습니다. LLM이 자동으로 스킬을 이용하지 않고 사용자가 수동으로만 실행해야 하는 작업은 disable-model-invocation: true를 formatter(— — 사이) 부분에 추가합니다. 예를 들어 배포, 커밋, 외부 전송처럼 부작용이 큰...

Claude Rules (Claude.md)

Claude.md : 세션 전체의 기본 작업 기준 AI 코딩 에이전트는 매번 새로운 요청을 받을 때마다 프로젝트의 전체 맥락을 처음부터 완벽히 기억하지 못합니다. 그래서 프로젝트마다 반복적으로 지켜야 하는 기준을 별도의 규칙 파일에 적어 두고, 세션이 시작될 때 자동으로 읽게 만드는 장치가 필요합니다. Claude Code에서 이 역할을 하는 대표 파일이 CLAUDE.md입니다. CLAUDE.md는 단순한 메모장이 아니라, 에이전트가 코드를...

AI 코딩 에이전트의 주요 구성요소

여기서 말하는 Rules, Skills, Subagents, Memory, Hooks는 주로 Claude Code/Claude 기반 코딩 에이전트 환경에서 정리된 개념 체계에 가깝습니다. Cursor, Codex, Gemini CLI, Windsurf 같은 다른 AI 코딩 도구들도 비슷한 기능을 제공하지만, 명칭과 저장 위치, 호출 방식은 도구마다 다를 수 있습니다. 따라서 이 표는 모든 코딩 에이전트의 공통 표준이라기보다, Claude를 기준으로 AI 코딩 에이전트의 구성요소를 이해하기...

AI 하네스

AI 하네스

ICLR 2026를 계기로 harness(실행 계층)와 scaffold(행동 정의 계층)를 분리하는 좁은 정의가 정리되었지만, 실무 현장에서는 모델을 제외한 모든 것을 통칭하는 포괄적(넓은) AI 하네스 개념이 훨씬 널리 쓰입니다. AI 하네스 wiki에서는 skill, hook, rule 과 같은 포괄적 개념의 하네스에 대해 다룹니다. 본 포스트에서는 하네스와 스캐폴드에 대한 정의에 대해 짧게 정리하였습니다. 1. 하네스 용어 혼란 이 논의는 ICLR...

AI 코딩 에이전트 wiki

과거의 AI 코딩 보조 도구가 프롬프트를 입력하고 결과 코드를 복사,붙여넣는 단발성 챗 인터페이스에 가까웠다면, 최근의 “AI 코딩 에이전트” 는 모델을 중심으로 파일 시스템, 터미널, 브라우저, 테스트 러너, 버전 관리 시스템, 외부 API가 결합된 하나의 실행 환경으로 발전하고 있습니다. 이제 AI 코딩 에이전트는 단순히 코드를 생성하는 도구가 아니라, 요구사항을 분석하고 작업을 작은 단위로 나누며, 필요한 파일을...

Prime Editing 원리

Prime Editing 원리은 DNA를 완전히 끊지 않고, Cas 단백질과 역전사효소를 결합한 편집기를 이용해 원하는 염기 변화를 기록하듯 삽입하는 기술입니다. 기존 CRISPR-Cas9 방식이 DNA 이중가닥 절단 뒤 세포의 복구 반응을 이용했다면, 프라임 편집은 더 작은 절단과 RNA 설계 정보를 이용해 비교적 정밀하게 유전 정보를 고칩니다. Prime Editing 작동 순 1. 표적 인식 및 단일 가닥 절단...

Prime Editing

Gene Editing

Auth 설정

Bifrost Gateway의 Auth 설정은 Dashboard, Admin API, Inference API 접근을 보호하기 위한 기본 인증 기능입니다. 운영 환경에서는 Dashboard와 Admin API가 외부에 노출될 수 있으므로, 반드시 인증 설정을 켜는 것이 좋습니다. Auth가 보호하는 범위 구분 인증 적용 방식 Dashboard 로그인 세션 기반 Bearer Token 사용 Admin API 인증 활성화 시 Basic Auth 또는 Bearer Token 필요...

마이그레이션 함정

등급별 Fallback구현

Multi-provider chain

OpenAI/Anthropic 마이그레이션

자동 Fallback 원리

Base URL만 바꾸기

Drop-in & Fallbacks

Cofig Store

LLM 호출하기

Provider 등록하기

Web UI

Web UI 는 Gateway가 어떤 Provider를 사용할지, 어떤 key를 어떤 모델에 연결할지, 요청 로그와 사용량을 어떻게 볼지, Virtual Key와 budget을 어떻게 관리할지 다루는 운영 콘솔입니다. Web UI 기능 의미 운영 관점 Visual provider setup 코드 없이 Provider와 API key를 등록 OpenAI, Anthropic 등 Provider 연결을 빠르게 검증 Real-time configuration 변경 사항을 즉시 반영 config 파일...

HTTP Gateway 설치

Bifrost Gateway는 OpenAI 호환 HTTP API를 제공하는 별도 프로세스입니다. FastAPI, LangGraph, Batch Worker 같은 애플리케이션은 Provider API를 직접 호출하는 대신 Bifrost Gateway의 endpoint를 호출합니다. Gateway 설치 방법은 크게 두 가지입니다. 방식 공식 Quickstart 명령 추천 용도 NPX Binary npx -y @maximhq/bifrost 로컬 실습, 빠른 검증, 소규모 내부 사용 Docker docker run -p 8080:8080 maximhq/bifrost 컨테이너...

Quickstart

이 Chapter에서는 Bifrost HTTP Gateway를 로컬에서 실행하고, Web UI를 통해 Provider를 등록한 뒤, OpenAI 호환 API로 첫 요청을 보내는 전체 흐름을 실습합니다. 이후 Config Store를 통해 설정을 영속화하고, 개발 환경과 운영 환경에서 설정을 어떻게 분리할지 정리합니다. 공식문서

Bifrost OSS vs Enterprise

1. Enterprise는 OSS 보다 상위 서비스 제공 Bifrost Enterprise는 별도의 완전히 다른 제품이라기보다, Bifrost OSS 위에 조직 규모 운영에 필요한 고가용성, 보안, 거버넌스, 컴플라이언스, 배포 옵션을 추가한 상위 집합으로 이해하시면 됩니다. 즉 OSS에서 학습하는 Provider 통합, OpenAI-compatible API, fallback, load balancing, virtual keys, semantic caching, observability, MCP, plugin 개념은 Enterprise에서도 동일하게 중요합니다. Enterprise는 이 기반...

Bifrost 아키텍쳐

학습 목표 핵심 개념 1. 전체 요청 흐름: Gateway는 단순 전달자가 아니라 요청 처리 파이프라인 Bifrost의 핵심 아키텍처는 “클라이언트 요청을 Provider API로 그대로 중계하는 프록시”가 아니라, 요청을 표준 내부 형식으로 바꾸고, 정책을 적용하고, Provider에 전달한 뒤, 응답을 다시 가공하는 파이프라인입니다. 공식 Request Flow 문서는 요청 처리를 다음 단계로 나누어 설명합니다. 단계 역할 운영 관점에서 보는...

Bifrost 개요

핵심 개념 Bifrost는 AI Gateway입니다 Bifrost는 애플리케이션과 LLM Provider 사이에 위치하는 고성능 AI Gateway입니다. 공식 문서에서는 Bifrost를 “20+ providers를 단일 OpenAI-compatible API로 통합하는 고성능 AI gateway”라고 설명합니다. 핵심은 애플리케이션 코드가 OpenAI, Anthropic, Bedrock, Vertex AI, Azure OpenAI 등 여러 Provider의 차이를 직접 처리하지 않도록 만드는 것입니다. Python 백엔드 입장에서는 LLM 호출 지점을 Provider별 SDK 호출...

AI Gateway의 필요성

AI Gateway는 왜 필요한가요? LLM 애플리케이션이 실험 단계일 때는 SDK 하나와 API Key 하나만으로도 충분해 보입니다. 하지만 실운영에서는 다음 문제가 빠르게 나타납니다. AI Gateway는 애플리케이션과 Provider 사이에 위치하여 인증, 라우팅, fallback, 비용 추적, 로그, 정책 적용을 중앙화합니다. Rate Limit 문제 LLM Provider는 계정, 프로젝트, API Key, 모델 단위로 요청 수와 토큰 사용량을 제한합니다. 단일 API...

Bifrost 시작

이 Chapter에서는 AI Gateway가 필요한 이유를 먼저 이해한 뒤, Bifrost가 어떤 문제를 해결하는지 확인합니다. ‘Bifrost 아키텍쳐’ 절의 경우 한번에 이해하기는 힘들지만 Bifrost의 기본적인 구조를 이해하는데 도움이 됩니다.

Bifrost wiki

해당 wiki는 Bifrost OSS를 self-hosted 환경에서 이해하고, 설치하고, 실제 운영 가능한 형태로 활용하기 위한 단계별 학습 문서입니다. Bifrost는 여러 LLM Provider를 하나의 Gateway 계층에서 통합적으로 다루고, 요청 흐름을 제어하며, 장애 대응·비용 관리·캐싱·관측성·거버넌스까지 함께 고려할 수 있게 해주는 인프라 성격의 도구입니다. 따라서 이 가이드는 단순히 “Bifrost를 실행해보는 방법”에 그치지 않고, AI 애플리케이션을 안정적으로 운영하기 위해 LLM...

init_chat_model

init_chat_model로 시작하기 LangChain을 처음 쓰다 보면 프로바이더마다 다른 클래스를 import하는 일이 생깁니다. 모델을 바꿀 때마다 import 문도, 클래스 이름도, 파라미터 구조도 달라집니다. init_chat_model은 이 불편함을 해소하기 위해 도입된 통합 팩토리 함수입니다. 💡 LangChain v1 공식 권장 방식 LangChain 공식 문서는 init_chat_model을 “The easiest way to get started with a standalone model” 로 소개하며, v1부터 표준...

채팅 시작하기

OpenSearch wiki

이 wiki는 OpenSearch 공식 문서를 기준으로, OpenSearch를 이용해 RAG 시스템을 설계하고 Python으로 구현하는 방법을 단계적으로 학습하기 위한 기술 문서입니다. 학습 순서 Part 페이지 묶음 핵심 목적 Part 1 OpenSearch 전체 구조와 RAG에서의 역할 OpenSearch를 검색 엔진, 분석 엔진, 벡터 DB로 이해 Part 2 설치와 개발 환경 구성 로컬 Docker와 Python client 연결 Part 3 OpenSearch...

LangChain • LangGraph wiki

이 위키는 LangChain과 LangGraph를 기반으로 LLM 애플리케이션과 에이전트 시스템을 단계적으로 학습하기 위한 정리 공간입니다. LLM을 단순히 호출하는 수준을 넘어, 프롬프트 구성, 출력 파싱, 메모리, 스트리밍, 도구 호출, RAG, 상태 관리, 조건 분기, 병렬 실행, Human-in-the-loop, 멀티에이전트 구조까지 실전 개발에 필요한 개념들을 하나씩 연결해 나가는 것을 목표로 합니다. LangChain은 LLM 애플리케이션을 구성하는 기본 구성 요소를 이해하는...