MaJu's Note

← 7/8 프론트엔드와 백엔드 배포 구조 📚 시리즈 목차 (시리즈 끝) 서비스는 실행된다고 끝나지 않는다. 신뢰할 수 있는 주소, 안전한 연결, 구분된 환경, 보이는 오류가 있어야 비로소 운영이 시작된다. 핵심 요약 도메인은 사람이 접근하는 이름이고, DNS는 그 이름을 실제 서비스 위치로 연결하는 시스템이다. HTTPS는 트래픽 암호화만이 아니라 인증과 무결성 확인까지 포함하는 운영 기본값이다. 개발, 스테이징, 운영 환경을 분리하지 않으면 인증, API, 에러 추적이 서로 섞여 문제를 키운다. Sentry 같은 오류 추적 도구는 "문제가 있었다"가 아니라 "어느 환경에서 어떤 조건으로 발생했는가"를 남기는 역할을 한다. 1. 도메인과 DNS는 왜 운영의 시작점일까 사용자는 IP 주소보다 도메인을 기억한다. 하지만 운영 관점에서 더 중요한 이유는 도메인이 단순 별명이 아니라, 서비스 경계와 환경 분리를 표현하는 기준이기 때문이다. 예를 들어 아래처럼 나눌 수 있다. example.com : 운영 서비스 staging.example.com : 스테이징 검증 api.example.com : 백엔드 엔드포인트 AWS Route 53 문서는 Route 53을 DNS 웹 서비스로 설명한다. 이 말은 곧, 도메인이 "예쁜 주소"가 아니라 실제 트래픽 경로를 제어하는 운영 계층이라는 뜻이다. 2. HTTPS는 왜 선택이 아니라 기본값일까 HTTP와 HTTPS의 차이는 단순히 자물쇠 아이콘 유무가 아니다. 암호화 브라우저와 서버 사이 데이터를 평문이 아니라 암호화된 채널로 주고받는다. 서버 신뢰 확인 인증서를 통해 사용자가 접속한 서버가 의도한 대상인지 검증한다. 인증 기능과의 결합 OAuth, 세션 쿠키, 결제, 개인정보 입력은 사실상 HTTPS를 전제로 움직인다. 특히 secure cookie와 같은 설정은 HTTPS가 아니면 기대대로 동작하지 않는다. 즉...

← 6/8 빌드 📚 시리즈 목차 8/8 HTTPS → 배포는 서버를 하나 사는 일이 아니라, 요청이 어디를 거쳐 어떤 프로세스에 도달하는지 구조를 만드는 일이다. 핵심 요약 EC2는 애플리케이션을 올릴 수 있는 가상 서버이고, nginx는 요청을 받아 정적 파일 제공과 프록시 역할을 수행하는 웹 서버다. 브라우저 요청은 보통 도메인 -> nginx -> 애플리케이션 서버(WAS) -> 데이터 계층 순서로 흐른다. 프론트엔드와 백엔드는 "코드 종류"보다 "어디서 실행되고 무엇을 반환하는가"로 구분하는 편이 운영에 유리하다. 입문 단계에서는 한 대의 EC2에 올릴 수 있어도, 역할 분리를 이해해야 장애와 병목을 설명할 수 있다. 1. EC2는 무엇이고 왜 자주 등장할까 AWS EC2는 직접 서버를 관리하는 방식의 대표적인 출발점이다. AWS 문서 기준으로 사용자는 인스턴스를 생성하고, 리전을 선택하고, 네트워크와 접근 방식을 정해 애플리케이션을 올린다. 초보자 입장에서 EC2를 이해하는 가장 쉬운 방법은 "내가 실행 환경을 더 많이 책임지는 서버"라고 보는 것이다. 어떤 운영체제를 쓸지 정해야 한다 어떤 포트를 열지 정해야 한다 어떤 프로세스를 띄울지 정해야 한다 재시작, 로그, 업데이트를 직접 관리해야 한다 플랫폼형 배포보다 손이 더 가지만, 구조를 배울 때는 오히려 투명하다. 어떤 레이어가 실제로 존재하는지 잘 보이기 때문이다. 2. 웹 서버와 WAS는 어떻게 다를까 웹 개발 입문에서 자주 나오는 WS 와 WAS 구분은 아직도 유효하다. 용어 자체보다 역할 분리를 이해하는 것이 중요하다. 웹 서버(nginx) 정적 파일을 전달하고, 외부 요청을 받아 적절한 내부 서비스로 넘기는 데 강하다. 리버스 프록시, 캐시, 압축, 라우팅 제어 같은 역할을 맡는다. WAS 또는 애플리케이션 서버 실제 애플리케이션 코드를 실행한다. Node.js...

← 5/8 OAuth와 SSO는 왜 느리게 느껴질까 📚 시리즈 목차 7/8 프론트엔드와 백엔드 배포 구조 → 개발자가 읽기 좋은 코드와 브라우저가 실행하기 좋은 코드는 대체로 같은 형태가 아니다. 핵심 요약 프론트엔드 빌드는 개발용 소스 코드를 브라우저와 서버가 실행 가능한 산출물로 바꾸는 과정이다. 컴파일, 트랜스파일, 번들링, 코드 분할은 서로 다른 단계지만 초보자에게는 한 덩어리처럼 보이기 쉽다. Next.js 문서 기준으로 Turbopack은 기본 번들러이며, 개발 속도와 증분 처리 경험을 개선하는 방향에 초점이 있다. 배포 문제의 상당수는 앱 코드보다 빌드 산출물, 환경 변수 주입, 정적 자산 경로, 런타임 차이에서 발생한다. 1. 빌드는 정확히 무엇을 의미할까 빌드는 "코드를 실행 파일이나 서비스 산출물로 만드는 전체 과정"이라고 보는 편이 가장 실용적이다. 프론트엔드에서는 보통 아래 작업이 함께 묶인다. 최신 문법이나 JSX를 브라우저가 이해할 수 있는 형태로 바꾸기 여러 파일 의존성을 정리하기 필요한 코드만 묶고 불필요한 코드는 줄이기 정적 자산 경로를 정리하기 프로덕션용 최적화를 적용하기 그래서 npm run build 한 줄은 짧지만, 실제로는 애플리케이션 구조를 배포 가능한 상태로 재구성하는 과정이다. 2. 컴파일, 트랜스파일, 번들은 어떻게 다를까 입문자가 가장 헷갈리는 구간이라 구분을 한 번 잡아 두는 것이 좋다. 컴파일 넓은 의미로는 소스 코드를 다른 실행 가능한 형태로 바꾸는 전체 변환을 가리킨다. 프론트엔드 문맥에서는 엄밀한 전통적 컴파일보다 더 넓게 쓰인다. 트랜스파일 자바스크립트 생태계에서는 "비슷한 수준의 언어를 다른 형태로 변환"하는 경우가 많다. 예를 들어 TypeScript를 JavaScript로, JSX를 일반 함수 호출 형태로 바꾸는 작업이 여기에 가깝다. 번들링 여러 파일과 의존성을 실행 단위로 묶는 작업이다. 브라우...

← 4/8 Supabase를 CRUD로만 보면 놓치… 📚 시리즈 목차 6/8 빌드 → 로그인은 한 화면의 문제가 아니라, 여러 시스템이 짧은 시간 안에 신뢰를 교환하는 과정이다. 핵심 요약 OAuth는 권한 위임 규약이고, SSO는 한 번의 인증으로 여러 서비스에 접근하게 만드는 사용자 경험이다. 로그인 지연은 화면 렌더링보다 리다이렉트 -> 인증 확인 -> 토큰 교환 -> 세션 생성 -> 사용자 정보 반영 구간에서 자주 생긴다. 개인용 로그인보다 조직용 SSO는 정책 검사, IdP 연동, 속성 매핑이 추가되어 더 느리게 느껴질 수 있다. 배포 이후 인증 문제는 코드 버그만이 아니라 도메인, redirect URI, 쿠키, 환경 변수 분리 문제로도 나타난다. 1. OAuth와 SSO는 같은 것이 아니다 둘은 같이 등장해서 자주 섞여 보이지만 역할이 다르다. OAuth는 "내 비밀번호를 직접 넘기지 않고도 다른 앱에 제한된 권한을 위임하는 방식"에 가깝다. 예를 들어 어떤 서비스가 Google 계정으로 로그인 버튼을 제공할 때, 실제 비밀번호 검증은 Google 쪽에서 하고 애플리케이션은 결과 토큰만 받는다. SSO는 "한 번 인증한 사용자가 여러 서비스에서 다시 로그인하지 않게 하는 구조"다. 회사 환경에서는 SAML이나 OIDC 기반 SSO가 자주 쓰이고, 개인 서비스보다 조직 정책이 더 많이 개입한다. 즉, OAuth는 권한 위임 프레임이고, SSO는 로그인 경험과 조직 접근 제어를 포함한 상위 흐름으로 이해하는 편이 정확하다. 2. 로그인 버튼을 누른 뒤 실제로 무슨 일이 일어날까 사용자는 버튼 하나만 보지만 내부 흐름은 꽤 길다. 애플리케이션이 사용자를 인증 제공자 로그인 페이지로 리다이렉트한다. 인증 제공자가 사용자를 확인하고 동의 또는 조직 정책 검사를 수행한다. 브라우저가 애플리케이션의 redirect URI로 다시 돌아온다. 애플리케이션이...

← 3/8 API 📚 시리즈 목차 5/8 OAuth와 SSO는 왜 느리게 느껴질까 → 데이터베이스를 연결했다고 해서 데이터 처리가 끝난 것은 아니다. 진짜 운영 문제는 저장 이전의 정리와 저장 이후의 가공, 그리고 누가 무엇에 접근할 수 있는가에서 시작된다. 핵심 요약 Supabase는 Postgres 기반 데이터 저장뿐 아니라 인증과 여러 운영 기능을 함께 제공하는 관리형 백엔드 계층이다. 하지만 입문자가 가장 먼저 배워야 할 것은 기능 목록보다 데이터 경계다. CRUD는 데이터 흐름의 한가운데일 뿐이며, 그 앞에는 입력 검증과 전처리가 있고 뒤에는 후처리와 권한 통제가 있다. 운영에서 중요한 것은 "저장되느냐"보다 "정확한 형태로 저장되고, 안전하게 읽히며, 목적에 맞게 가공되느냐"다. Supabase를 왜 단순 데이터베이스로만 보면 부족할까 Supabase는 흔히 "쉽게 붙이는 Postgres"로 소개되지만, 실제 학습 포인트는 그보다 넓다. 데이터 저장소를 빠르게 열어 주는 동시에 인증, API 접근, 정책 기반 권한 제어 같은 운영 요소도 함께 다루게 만든다. 이 말은 곧 Supabase를 배우는 일이 SQL 몇 줄을 쓰는 데서 끝나지 않는다는 뜻이다. 어떤 데이터가 어떤 사용자에게 열려야 하는지, 브라우저에서 직접 접근 가능한 범위와 서버에서만 처리해야 하는 범위가 어디까지인지 함께 생각해야 한다. 즉 Supabase는 CRUD 연습 도구이면서 동시에 백엔드 경계를 배우는 도구다. CRUD 앞에는 항상 입력 검증과 전처리가 있다 입문 단계에서는 사용자가 폼에 값을 넣고, 그 값을 바로 데이터베이스에 저장하는 흐름부터 떠올리기 쉽다. 하지만 운영에서는 그 전에 반드시 걸러야 할 단계가 있다. 입력 검증은 값이 존재하는지, 형식이 맞는지, 길이가 적절한지, 허용 범위를 넘지 않는지 확인한다. 전처리는 그 값을 저장에 적합한 형태로 정리하는 단계다. 예를 들어 공...

← 2/8 Docker는 왜 환경 통제의 출발점일까 📚 시리즈 목차 4/8 Supabase를 CRUD로만 보면 놓치… → 기능을 빨리 붙이는 능력은 점점 쉬워지고 있다. 대신 무엇을 직접 만들고, 무엇을 외부 API에 맡기고, 어떤 도구 계층으로 통제할지 판단하는 능력이 더 중요해졌다. 핵심 요약 API는 기능 연결의 기본 단위이고, MCP는 도구 접근을 더 구조화해 주는 중간 계층으로 이해할 수 있다. 바이브 코딩은 속도를 크게 올려 주지만, 속도가 곧 운영 가능성을 보장하지는 않는다. 외부 기능을 붙일수록 인증, 비용, 실패 처리, 권한, 데이터 경계가 더 중요해진다. 좋은 개발은 "빨리 연결한다"에서 끝나지 않고, "무엇을 누구에게 맡기고 무엇은 내가 검증할지"까지 정한다. API는 왜 웹 개발의 기본 연결 단위인가 현대 웹 서비스는 대부분 모든 기능을 직접 구현하지 않는다. 결제, 인증, 지도, 이메일, 검색, AI 모델 호출처럼 많은 기능이 외부 서비스와의 연결 위에서 돌아간다. 이 연결의 가장 보편적인 형식이 API다. API는 단순히 데이터를 주고받는 통로가 아니라 책임 분리의 경계이기도 하다. 내 애플리케이션은 어떤 입력을 보낼지, 어떤 응답을 기대할지, 실패했을 때 어떻게 처리할지를 정한다. 외부 서비스는 그 계약 안에서 기능을 제공한다. 즉 API를 쓴다는 것은 기능을 빌리는 동시에, 경계를 명시적으로 받아들이는 일이다. MCP는 어떤 문제를 줄이려는가 도구와 외부 시스템이 많아질수록 단순 API 호출만으로는 관리가 어려워질 수 있다. 어떤 도구를 언제 써야 하는지, 어떤 권한으로 접근하는지, 입력과 출력 형식을 어떻게 통일할지 같은 문제가 생긴다. 이때 MCP는 도구 접근을 좀 더 구조화하는 층으로 이해할 수 있다. 모델이나 에이전트가 사용할 도구를 일정한 인터페이스와 제약 아래에 두면, 개별 연결을 제멋대로 붙이는 것보다 통제선이 선명해진다. 특히 여러 도구를 고르...

← 1/8 로컬에서는 되는데 운영에서는 왜 깨질까 📚 시리즈 목차 3/8 API → Docker의 핵심은 편하게 배포하는 도구라는 데 있지 않다. 더 중요한 역할은 "이 앱이 어떤 조건에서 돌아가는가"를 코드와 함께 묶어 두는 데 있다. 핵심 요약 Docker는 애플리케이션이 실행되기 위한 환경을 이미지로 고정하고, 그 이미지를 컨테이너로 실행하게 해 준다. 입문자 관점에서 Docker의 가장 큰 장점은 배포 자동화보다 "로컬과 운영 차이를 줄인다"는 데 있다. 이미지, 컨테이너, 네트워크, 볼륨을 구분해서 이해해야 Docker를 단순 명령어 모음이 아니라 운영 도구로 볼 수 있다. Docker가 모든 문제를 해결하지는 않지만, 적어도 "내 컴퓨터에서는 됐는데"라는 변명을 줄이는 출발점은 된다. Docker는 무엇을 고정하려고 등장했는가 앞선 글에서 본 것처럼 로컬과 운영은 실행 조건이 다르다. OS, 런타임 버전, 설치된 패키지, 시스템 라이브러리, 파일 경로, 시작 명령이 조금만 달라도 결과가 달라질 수 있다. Docker는 이 차이를 줄이기 위해 등장했다. 애플리케이션이 필요로 하는 실행 조건을 이미지라는 형태로 묶고, 그 이미지를 어디서든 비슷한 방식으로 실행하자는 것이다. 즉 Docker는 "코드"만 옮기는 것이 아니라 "코드가 기대하는 실행 환경"까지 함께 옮기게 해 준다. 이 점 때문에 Docker는 배포 도구이기 전에 재현 도구다. 이미지와 컨테이너는 왜 구분해서 이해해야 할까 Docker를 배울 때 가장 먼저 헷갈리는 것이 이미지와 컨테이너다. 둘은 비슷해 보이지만 역할이 다르다. 이미지는 실행에 필요한 파일 시스템과 설정을 묶은 정적인 청사진이다. 어떤 베이스 이미지를 썼는지, 어떤 패키지를 설치했는지, 어떤 명령으로 시작할지를 포함한다. 반면 컨테이너는 그 이미지를 실제로 실행한 살아 있는 인스턴스다. 이 구분이...

(시리즈 시작) 📚 시리즈 목차 2/8 Docker는 왜 환경 통제의 출발점일까 → 웹 개발 입문자가 가장 먼저 마주치는 운영의 벽은 코드가 아니라 환경 차이다. 로컬에서의 성공은 통제된 실험이고, 운영은 통제되지 않은 현실이다. 핵심 요약 로컬 환경은 개발자가 알고 있는 조건 위에서 움직이지만, 운영 환경은 사용자·서버·네트워크·보안 정책이 함께 얽힌다. 같은 코드라도 운영에서는 환경 변수, 데이터 상태, 파일 시스템, 외부 API, 배포 방식 차이 때문에 다르게 동작할 수 있다. "로컬에서 된다"는 말은 출발점일 뿐이며, 운영 준비란 코드보다 경계를 이해하는 일에 가깝다. 이후 글에서 다룰 Docker, API/MCP, Supabase, 빌드, 배포, HTTPS는 모두 이 환경 차이를 줄이기 위한 장치들이다. 로컬 성공과 운영 성공은 무엇이 다른가 로컬 개발은 대개 한 사람이 통제 가능한 작은 실험실에서 이뤄진다. 사용하는 Node 버전도 알고 있고, .env 파일도 직접 만들었고, 데이터베이스도 비어 있거나 단순한 샘플 데이터만 들어 있다. 문제가 생기면 터미널을 보고 바로 고칠 수 있다. 반면 운영 환경은 다르다. 서버는 별도 머신에 있고, 실행 계정과 권한이 나뉘며, 접속하는 사용자는 여러 명이다. 요청은 네트워크를 거치고, 외부 API는 지연되거나 실패할 수 있고, 데이터는 이미 예외 상황을 품고 있다. 즉 운영은 "코드가 맞는가"만 묻지 않고 "이 코드가 실제 조건에서도 버티는가"를 묻는다. 그래서 로컬 성공은 구현 확인이고, 운영 성공은 시스템 적합성 확인이라고 보는 편이 정확하다. 가장 먼저 갈라지는 것은 실행 환경이다 운영에서 흔히 터지는 첫 번째 차이는 실행 환경이다. 로컬에서는 npm install 후 바로 돌았지만, 운영 서버는 다른 Node 버전을 쓰고 있을 수 있다. 로컬은 macOS인데 운영은 Linux일 수 있고, 로컬 파일 경로는 대소...

📚 하네스 엔지니어링 전체 지도 — 7개 시리즈 29편 에이전트 하네스를 입문부터 부록까지 단계별로 읽는 안내입니다. 1. 입문·기초 ① 하네스 엔지니어링 (6편) — 컨텍스트·메모리·도구·라우팅·평가, 에이전트를 둘러싼 모든 것 ② 하네스 엔지니어링 기초 (4편) — 모델보다 중요한 실행 환경과 에이전트 루프 2. 구현 ③ OpenAI·Claude 구현 (3편) — Responses API와 CLAUDE.md를 운영 표면으로 3. 운영 ④ 평가·운영·메모리 (4편) — handoff·권한·메모리 소유권으로 장시간 운영 안정화 ⑤ AI 운영 경제학 (4편) — 비용·라우팅·캐싱·컨텍스트 운영 결정 4. 전략 ⑥ 패턴·전략·사례 (4편) — 반복 가능한 구조·설계 결정·ACI·실전 사례 5. 부록 ⑦ 부록 컴패니언 (4편) — 용어집·출처 검증·워크시트·멀티에이전트 Q&A 이 시리즈는 "좋은 모델을 붙이면 좋은 에이전트가 된다"는 기대에서 한 걸음 더 나아가, 실제로는 지시 파일, 도구 표면, 권한, 검증, handoff, 메모리 같은 작업 환경이 에이전트 품질을 어떻게 갈라놓는지 설명하기 위해 만들었다. 총 19편이며, 입문자부터 운영 설계 담당자까지 각자 필요한 지점부터 들어올 수 있게 5개 트랙으로 나누었다. 영문판 안내: Harness Engineering Series Guide — Where Should You Start If You Want to Design and Run AI Agents Properly? 이 시리즈는 누구를 위한 것인가 이 시리즈는 아래 독자에게 맞춘다. AI 에이전트를 처음 도입하지만 프롬프트 너머의 구조가 궁금한 사람 OpenAI와 Claude를 "모델 성능"이 아니라 "운영 표면"으로 비교하고 싶은 사람 장시간 작업, 권한 관리, 평가 루프, 메모리 소유권까지 포함해 실무형 하네스를 설계하려는 사람 AGENTS.md , CL...

← E3 내 업무 하네스 워크시트 📚 시리즈 목차 (부록 시리즈 끝) 멀티에이전트 이야기가 나오면 많은 사람이 subagent와 agent team을 거의 같은 뜻으로 쓴다. 하지만 둘은 운영 철학도, 비용 구조도, 필요한 통제 표면도 다르다. 이 글은 "언제는 위임이면 충분하고, 언제는 역할이 분리된 팀 구조가 필요한가"를 Q&A 형식으로 정리한 appendix finale다. 핵심 요약 subagent는 보통 본 에이전트가 경계가 있는 하위 작업을 위임하는 구조 다. agent team은 보통 역할이 분리된 여러 에이전트가 더 지속적인 협업 루프를 이루는 구조 다. 복잡해 보인다고 무조건 team이 필요한 것은 아니다. 많은 경우는 잘 설계된 delegation이면 충분하다. 팀 구조는 역할 분리의 가치가 coordination 비용보다 클 때만 정당화된다. 멀티에이전트 설계의 핵심 질문은 "몇 명이 필요한가"가 아니라 어디서 실패 도메인을 분리해야 하는가 다. 1. 왜 이 구분이 중요한가 docs/blog_series_하네스엔지니어링_총괄_design.md 는 E4를 "delegation vs persistent teams, Q&A형 정리"로 정의한다. 이 표현이 핵심을 잘 잡고 있다. 실무에서 자주 생기는 오해는 이렇다. subagent를 쓰면 곧 멀티에이전트 팀이라고 생각한다 역할을 나누기만 하면 자동으로 품질이 좋아질 것이라 기대한다 orchestration 비용, handoff 비용, 검증 비용을 과소평가한다 이 구분을 먼저 하지 않으면, 시스템은 쉽게 화려해지고 어렵게 운영된다. 2. 가장 짧은 정의 구조 짧은 정의 subagent 본 에이전트가 제한된 하위 작업을 맡기기 위해 잠시 띄우는 위임 단위 agent team 여러 역할이 비교적 지속적으로 협업하며 상태와 책임을 나누는 팀 구조 ...

← E2 출처 지도와 검증법 📚 시리즈 목차 E4 Subagent와 Agent Teams 구분하기 → 많은 팀이 "이 업무는 AI로 자동화할 수 있을까"부터 묻는다. 하지만 하네스 관점에서 더 좋은 질문은 다르다. 이 업무를 지시, 문맥, 도구, 검증, handoff로 쪼개면 어디까지는 에이전트에게 맡기고 어디부터는 사람이 잡아야 하는가. 이 글은 그 질문에 답하기 위한 card-style workbook이다. 핵심 요약 반복 업무를 에이전트에게 넘기기 전에 먼저 해야 할 일은 업무를 하네스 단위로 분해하는 것 이다. 좋은 후보 업무는 "자주 반복되고, 입력과 출력이 비교적 안정적이며, 실패를 빨리 감지할 수 있는 일"이다. 워크시트는 업무 정의 -> 입력/출력 -> 지시 표면 -> 도구 표면 -> 검증 표면 -> handoff 표면 -> 승인 경계 순서로 채우는 편이 안정적이다. 자동화 범위를 넓히는 것보다 실패 반경을 좁히는 카드 를 먼저 채우는 편이 실전에서 오래 간다. 이 부록의 목적은 멋진 프롬프트 작성이 아니라, 업무를 운영 가능한 하네스로 번역하는 연습 이다. 1. 왜 워크시트가 필요한가 docs/blog_series_하네스엔지니어링_총괄_design.md 는 E3를 "실습 워크시트, 적용 카드"로 정의한다. 이 정의가 중요한 이유는, 하네스 엔지니어링을 읽는 것과 직접 설계하는 것은 전혀 다른 단계이기 때문이다. 실무에서는 보통 이런 순서로 실패한다. 업무를 너무 크게 잡는다 지시와 도구를 한꺼번에 섞는다 검증이 없는 상태로 바로 실행한다 긴 작업의 재개 경로를 남기지 않는다 사람이 승인해야 할 경계를 뒤늦게 붙인다 워크시트는 이 다섯 실패를 줄이기 위한 장치다. 2. 먼저 고를 것: 어떤 업무가 하네스 후보인가 모든 업무가 좋은 에이전트 후보는 아니다. 먼저 아래 기준으로 골라야 한다. ...

← E1 용어집과 치트시트 📚 시리즈 목차 E3 업무 하네스 워크시트 → 하네스 엔지니어링 같은 빠르게 변하는 주제는 "좋은 설명"보다 "좋은 출처 경계"가 먼저다. 책 메모, 공식 문서, 블로그 활용 노트, 공개 사례, 우리 저장소 사례를 한 줄에 섞어 쓰면 글은 그럴듯해져도 검증 가능성이 무너진다. 이 글은 무엇을 사실 근거로 두고, 무엇을 해석 레이어로만 써야 하는지 정리하는 companion appendix다. 핵심 요약 하네스 글에서 가장 먼저 구분할 것은 주장의 종류 와 출처의 계층 이다. 기능, 정책, 날짜, 제품 구조처럼 바뀔 수 있는 내용은 1차 자료로 다시 확인해야 한다. sources/ 의 활용 노트는 출발점이지 최종 증거가 아니다. 공개 사례는 "그 회사가 직접 밝힌 범위" 안에서만 구조적 주장에 사용해야 한다. 좋은 팩트체크는 자료를 많이 붙이는 일이 아니라, 어떤 문장을 어떤 등급의 출처로 뒷받침하는지 명확히 남기는 일 이다. 1. 왜 출처 지도가 필요한가 docs/blog_series_하네스엔지니어링_총괄_design.md 는 이 시리즈의 팩트체크 프로토콜을 이미 짧게 정리해 두고 있다. 책의 장별 논지는 패러프레이즈만 사용 제품 기능과 문서 경로는 발행 시점에 공식 문서로 재검증 특정 회사 사례는 그 회사가 공개한 구조와 수치로만 사용 커뮤니티 인용은 구조적 주장보다 트렌드 관찰에 한정 이 네 줄을 실제 작성 워크플로로 펼치면, 결국 필요한 것은 "출처 지도를 먼저 그리는 습관"이다. 2. 출처를 네 층으로 나누면 판단이 쉬워진다 층 1. 1차 자료 공식 문서 제품 제공자가 직접 공개한 기능 설명 공식 블로그, 공식 발표, 공식 사양 원저자 또는 원기관이 공개한 연구/사례 용도: 기능 존재 여부 정책, 권한, API 구조 날짜, 버전, 공식 용어 회사 사례의 사실 관계 층 ...

← 이전 읽을거리: D4 실전 사례 📚 시리즈 목차 E2 출처 지도와 검증법 → 하네스 엔지니어링 글을 읽다 보면 개념은 알겠는데 용어가 서로 겹쳐 보일 때가 많다. AGENTS.md 와 CLAUDE.md 는 어떻게 다르고, handoff와 memory는 어디서 갈리며, MCP와 tool은 같은 말이 아닌데 무엇이 다른가. 이 글은 시리즈 전반에 등장한 핵심 용어를 실무 정의와 빠른 판단표로 다시 정리한 companion appendix다. 핵심 요약 용어를 외우는 목적은 정의 암기가 아니라 운영 경계 구분 이다. 비슷해 보이는 단어도 "누가 읽는가", "언제 적용되는가", "무엇을 통제하는가"로 구분하면 헷갈림이 줄어든다. 좋은 하네스는 긴 설명보다 짧은 지시 표면, 좁은 도구 표면, 명시적 검증 표면, 복원 가능한 상태 표면 으로 정리된다. handoff는 장기 작업 복원용이고, memory는 반복 재사용용이라는 구분이 특히 중요하다. 아래 치트시트만 기억해도 시리즈 A부터 E까지 대부분의 글을 더 빠르게 읽을 수 있다. 1. 먼저 큰 지도부터: 하네스는 어떤 층으로 나뉘는가 시리즈 전체에서 반복해서 등장한 개념은 사실 몇 개의 층으로 묶인다. 층 핵심 질문 대표 예 지시 표면 에이전트는 어떤 규칙으로 시작하는가 AGENTS.md , CLAUDE.md , system instruction 문맥 표면 지금 무엇을 읽고 무엇을 생략하는가 사용자 요청, 참조 문서, tool result 도구 표면 무엇을 실행할 수 있는가 shell, file read/write, web, MCP 검증 표면 결과가 틀렸을 때 무엇이 먼저 잡는가 test, hook, eval, review 지속성 표면 세션이 끝난 뒤 무엇이 남는가 handoff, sessions, docs, long-term memory 운영 표면 ...