임베디드에서 AI Agents: 컨텍스트 엔지니어링을 익히며
AI 에이전트는 Yocto 레시피를 잘 썼지만 센서 데이터를 조용히 깨뜨리고 SPI 레지스터를 잘못 설정했다. 이걸 고친 건 내가 에이전트에게 건넨 컨텍스트였다.
On this page
Claude Code에게 Yocto 레시피를 맡겼더니 첫 시도에 바로 돌아가는 레시피를 내놓았다. inherit도 맞고 SRC_URI도 제대로였고, systemd 서비스 파일도 올바른 경로에 들어갔다. 2주 뒤, 같은 도구로 같은 종류의 세션을 열어 i.MX8M Plus용 IMU 센서 드라이버의 DMA 콜백을 짜 달라고 했다. 코드는 에러 없이 컴파일됐다. 그런데 부하를 주자 센서 데이터가 간헐적으로 깨지기 시작했고, 30초 만에 커널이 통째로 멈췄다.
모델도 같고 엔지니어도 같았다. 달랐던 건 컨텍스트였다. Yocto 레시피를 짤 때는 CLAUDE.md에 빌드 시스템이 meson이라는 것(cmake가 아니다), 레이어 구조, 표준 레시피 패턴을 다 적어 두었다. DMA 핸들러 때는 “센서 데이터 경로의 DMA 콜백을 짜라”는 한 줄이 전부였다. 에이전트로서는 이 플랫폼의 캐시 동기화 요구사항이나 공유 버퍼 락킹 규칙을 알 길이 없었다.
에이전트가 무리 없이 해내는 작업과 위험한 코드를 내놓는 작업 사이의 거리, 이 글은 그 이야기다. 첫 번째 포스트에서는 스펙 기반 TDD로 피드백 루프를 고쳤다. 이번에는 에이전트 쪽을 고친 기록이다. 병목은 모델이 아니라 컨텍스트였다.
이 글의 작업도 Claude Code로 했다. CLAUDE.md, 범위 지정 규칙, 서브에이전트 리뷰어는 Claude Code의 기능이다. 하지만 컨텍스트를 계층으로 나눈다는 원칙은 어떤 에이전트 코딩 도구에서도 그대로 통한다.
에이전트가 잘하는 것
정답이 소프트웨어 관례로 정해지고 하드웨어 동작에 좌우되지 않는 작업에서, AI 에이전트는 정말 생산적이다. Yocto 레시피, CMakeLists, systemd 유닛 파일, pytest 스캐폴드, CI/CD 파이프라인 같은 것들이다. 에이전트는 학습 데이터에서 .bb 레시피를 수천 개 보았고, 레시피들 사이의 차이는 프로젝트 파일에 글로 적어 줄 수 있는 텍스트다. Jacob Beningo는 Claude Code로 센서 드라이버 작업에서 4시간에서 20시간을 아꼈다고 보고했다. 깔끔한 하드웨어 추상화 계층이 있어야 한다는 단서를 달고서다. 빌드 시스템 작업이나 테스트 스캐폴딩에서는 혼자 하는 개발이 작은 팀으로 일하는 것처럼 느껴질 정도다.
에이전트가 틀리는 것
실패는 모든 계층에서 나왔다. 레지스터 계층에서는 이런 일이 있었다. 에이전트가 우리 ICM-42688-P IMU의 CTRL_REG1 주소로 0x11을 썼다. 맞는 주소는 0x4E다. SPI는 레지스터 주소가 틀려도 에러를 내지 않는다. 그 위치에 있는 값을 읽어 올 뿐인데, 하필 거기가 0을 돌려주는 예약 레지스터였다. 로직 분석기를 붙잡고 40분을 헤맨 뒤에야 레지스터 맵을 덤프해서 주소가 틀린 걸 찾았다. CLAUDE.md에 한 줄만 있었어도 막았을 일이다.
커널 계층으로 내려가면 이 격차는 훨씬 위험해진다. i.MX8M Plus 센서 드라이버의 DMA 완료 콜백이 교과서 같은 예다. 에이전트는 이런 코드를 내놓는다.
/* 에이전트 출력: DMA 완료 콜백 */
static void sensor_dma_complete(void *arg)
{
struct sensor_dev *sdev = arg;
memcpy(sdev->latest, sdev->dma_buf, SAMPLE_SIZE);
complete(&sdev->data_ready);
}
컴파일은 된다. 트래픽이 가벼우면 벤치에서도 잘 돈다. 하지만 부하가 꾸준히 걸리면 데이터가 간헐적으로 깨진다. 컨텍스트가 없으면 에이전트가 알아챌 수 없는 문제가 두 가지 있다.
/* 하드웨어가 실제로 필요로 하는 것 */
static void sensor_dma_complete(void *arg)
{
struct sensor_dev *sdev = arg;
/* SDMA가 RAM에 직접 쓰지만 CPU L1/L2에 여전히 stale 데이터가 있음.
이 호출 없이는 캐시 라인이 아직 evict되지 않았을 때
memcpy가 쓰레기를 읽음. */
dma_sync_single_for_cpu(sdev->dev, sdev->dma_addr,
SAMPLE_SIZE, DMA_FROM_DEVICE);
spin_lock(&sdev->lock); /* process-context reader의 spin_lock_bh()와 쌍 */
memcpy(sdev->latest, sdev->dma_buf, SAMPLE_SIZE);
spin_unlock(&sdev->lock);
complete(&sdev->data_ready);
}
dma_sync_single_for_cpu가 빠졌다는 건, DMA 엔진이 RAM에 직접 쓴 뒤에도 CPU가 오래된 캐시 라인을 읽는다는 뜻이다. Cortex-A53를 쓰는 i.MX8M Plus에서는 부하에 따라 캐시 eviction이 비결정적으로 일어나서, 손상이 메모리 압력에 따라 나타났다 사라졌다 한다. spin_lock이 빠지면 콜백(tasklet/softirq 컨텍스트)과 sdev->latest를 읽는 프로세스 스레드 사이에 레이스가 생긴다. 게다가 프로세스 컨텍스트 쪽은 평범한 spin_lock으로는 안 되고 spin_lock_bh가 필요하다. 그렇지 않으면 락을 쥔 채로 softirq가 들어올 때 데드락에 빠진다. 도입부에서 커널이 멈춘 것이 바로 이 데드락이었다.
모델은 학습 데이터에서 Linux DMA API를 보았다. 하지만 내 플랫폼의 캐시 토폴로지, 내 드라이버의 락킹 규칙, 이 콜백이 sleeping lock이 치명적인 softirq 컨텍스트에서 돈다는 사실은 보지 못했다. Chalmers/University of Gothenburg 연구(2026년 1월)는 4개 회사의 시니어 소프트웨어 엔지니어 10명을 조사했다. 이들은 비결정성과 인증 격차를 임베디드에서 AI 에이전트 도입을 가로막는 가장 큰 장벽으로 꼽았다. 한 엔지니어의 말이 이 상황을 잘 요약한다. “10년 전 컴파일러는 체크인할 수 있어도, LLM은 못 한다.”
격차는 부하가 걸릴 때, 규모가 커질 때, 하드웨어 동작이 학습 데이터가 암시하던 것과 어긋날 때 드러난다. 그 격차를 메우는 데 필요했던 건 컨텍스트였다.
컨텍스트 엔지니어링: 동작하는 세 계층
여러 번 고쳐 쓴 끝에 나는 컨텍스트 세 계층에 이르렀다. 뒤쪽 계층일수록 더 미묘한 실패를 잡는다.
계층 1: 하드웨어 명세로서의 CLAUDE.md
하나만 바꾼다면 효과가 가장 큰 것이 이것이다. 프로젝트 루트에 놓인 마크다운 파일 하나가 모든 Claude Code 세션에 걸쳐 살아남는다. 30분을 들여 적어 두면 그 뒤의 모든 작업에서 그 시간을 돌려받는다.
ETH Zurich 연구(2026년 2월)는 실세계 작업 138개를 테스트했다. LLM이 생성한 컨텍스트 파일은 오히려 성공률을 3% 낮추고 비용을 20% 늘렸다. 사람이 쓴 컨텍스트 파일은 성공률을 4% 올렸지만 비용도 19% 함께 올렸다. 에이전트가 지시를 너무 곧이곧대로 따르기 때문이다. 내가 여기서 얻은 교훈은, 에이전트가 저장소만 보고는 추론할 수 없는 것만 넣으라는 것이다. 뻔한 프로젝트 구조 설명은 토큰 낭비다. 코드에서 찾아낼 수 없는 하드웨어 제약이 가장 값지다.
그래서 내 CLAUDE.md는 추론할 수 없는 제약에 집중한다.
- 하드웨어 플랫폼: SoC 모델(i.MX8M Plus), 타겟 보드(RPi CM4), 주요 주변장치와 그 레지스터 특이사항
- 레지스터 맵: 에이전트가 전에 틀렸던 핵심 SPI/I2C 레지스터 주소
- DMA 규칙: 캐시 라인 정렬(Cortex-A53에서 64바이트), 필수 sync 호출, 버퍼 할당 제약
- 빌드 시스템: cmake 아니고 meson, 어느 meta-layer가 어느 레시피를 소유하는지, Docker 빌드 패턴
모든 항목은 그게 없어서 에이전트가 특정한 실수를 저질렀기 때문에 들어가 있다. 실제로 효과를 본 방식은 “학습된 수정” 섹션이다. 각 줄이 구체적인 실패 하나로 거슬러 올라간다.
## Learned Corrections
- 2026-01-15: IMU CTRL_REG1은 ICM-42688-P에서 0x4E, 0x11 아님
- 2026-01-18: DMA 버퍼는 Cortex-A53에서 64바이트 정렬 필수
- 2026-02-03: ICM-42688-P는 SPI 모드 3 (CPOL=1, CPHA=1)
각 줄은 에이전트가 한 번 낸 버그다. 파일은 쓰다 보면 저절로 자란다. 내 경험으로는 도구 체인과 워크플로 수정이 하드웨어 수정보다 대략 3대 1로 많다. 가장 자주 터지는 실패는 학습 데이터가 다루지 못하는 빌드 환경과 배포 경로 쪽이다.
더 큰 프로젝트라면 Claude Code가 지원하는 경로 기반 규칙 파일(.claude/rules/*.md)을 쓸 수 있다. 일치하는 파일을 편집할 때만 불러오는 방식이다. 커널 관련 제약은 드라이버 코드를 건드릴 때만 로드되고, Yocto 관례는 .bb 파일을 다룰 때 로드된다. 규칙 파일 하나하나는 작고 한 가지에 집중한다. 에이전트는 지금 작업에 필요한 컨텍스트만 받는다.
계층 2: 리뷰를 위한 특화 서브에이전트
범용 에이전트 하나로 임베디드 코드를 리뷰하면, 한꺼번에 너무 많은 것을 붙들려고 한다. 코드 스타일, 동시성 안전, 레지스터 정확성, 변경 영향 분석, 코딩 표준까지. 컨텍스트 창이 차면 에이전트는 하나씩 놓치기 시작한다.
그래서 리뷰를 특화 서브에이전트로 나눴다. 각자 집중된 시스템 프롬프트를 갖고, 필요한 도구에만 접근한다. 내 BSP 워크플로에는 특화 리뷰어 5개와 결과를 모으는 감독자(supervisor) 하나가 있다. 설계에서 중요했던 결정은 조건부 호출과 중복 인스턴스다.
모든 리뷰어가 모든 변경에 도는 건 아니다. 레지스터 계약 리뷰어는 SPI/I2C 코드나 디바이스 트리 파일이 바뀔 때만 실행된다. 동시성 리뷰어는 커널 드라이버 코드가 바뀔 때만 돈다. 테스트만 바뀌었다면 둘 다 건너뛰고 테스트 커버리지 리뷰어만 실행한다. 실행 여부는 각 에이전트가 시작할 때 간단한 파일 glob 검사로 정한다. 이렇게 하면 대부분의 커밋에서 리뷰 시간이 절반으로 줄고, 리뷰할 이유가 없는 코드를 분석하다 생기는 오탐도 막을 수 있다.
동시성 리뷰어와 레지스터 계약 리뷰어는 같은 프롬프트로 인스턴스를 2개씩 병렬로 돌리되, 컨텍스트는 서로 독립이다. 두 인스턴스가 같은 이슈를 짚으면 확신이 높다. 하나만 짚으면 사람 리뷰로 넘긴다. 한 번의 LLM 패스로는 놓치지만 같은 모델이 두 번째 실행에서는 잡을 수 있는 확률적 맹점이 있는데, 이 방식은 그 문제를 다룬다. 비용은 크지 않다(하나 대신 병렬 API 호출 두 개). 대신 가장 위험한 버그가 나오는 두 범주에서 신뢰도가 크게 오른다. 감독자는 모든 결과의 중복을 없애고 심각도 순으로 정렬한다. 같은 이슈에 플래그가 2개 이상이면 확신이 높아 자동 수정 대상이 되고, 1개면 사람 리뷰로 간다. 재실행 라운드는 두지 않는다. 2-인스턴스 설계가 이미 변동을 잡아내고, 라운드를 더 돌려 봐야 지연만 늘어난다.
Google/MIT 스케일링 연구(2025년 12월, 설정 180개)는 고정된 토큰 예산 아래에서 에이전트 3개에서 4개가 상한이라는 것을 발견했다. 조율 없이 도는 독립 에이전트는 에러를 17.2배로 키운다. 중앙집중 감독자 구조는 에러를 4.4배로 묶어 둔다. 테스트한 모든 패턴 가운데 가장 나은 결과였다. 에이전트 수를 늘리는 편이 토론 라운드를 늘리는 것보다 효과적이었고, 독립 분석 뒤에 중앙에서 모으는 방식이 에이전트끼리의 토론보다 나았다.
가장 많은 버그를 잡는 리뷰어는 동시성 리뷰어와 레지스터 계약 리뷰어다.
동시성 리뷰어의 프롬프트는 이렇게 시작한다. “코드 품질, 스타일, 성능은 리뷰하지 않는다. 오직 하나만 답한다: 이 코드가 동시 실행 환경에서 깨질 수 있는가?” spinlock 컨텍스트 위반, IRQ/softirq에서의 sleep, 락 순서, 메모리 배리어, DMA 동기화 규칙을 확인한다. 앞에서 본 DMA 콜백 버그를 이 리뷰어는 첫 패스에서 잡는다. 빠진 캐시 동기화와 보호되지 않은 memcpy를 단계별 인터리빙 시나리오와 함께 짚어 낸다. 범용 리뷰어는 둘 다 놓친다.
레지스터 계약 리뷰어는 SPI/I2C 레지스터 주소, 비트 필드 마스크, 초기화 시퀀스가 데이터시트와 맞는지 검증한다. 리뷰어는 모든 레지스터 접근 매크로를 grep해서 주소를 뽑아낸 다음, docs/hardware/의 레지스터 맵과 대조한다.
나머지 리뷰어 셋(부작용/변경 영향, 코딩 표준, 테스트 커버리지)은 단일 인스턴스로 이 둘과 나란히 돈다. 위험이 낮은 관심사라서 한 번의 패스로 충분하다.
정적 분석 결과를 각 리뷰어 프롬프트에 넣어 주면 효과가 더 커진다. 리뷰 패스 전에 cppcheck와 clang-tidy를 돌리고, 출력을 JSON으로 바꿔 각 리뷰어 프롬프트에 넣는다. 정적 분석 결과와 LLM 리뷰를 합치면 어느 한쪽만 쓸 때보다 더 많이 잡는다.
계층 3: 컴파일러-인-더-루프 피드백
마지막 계층은 에이전트의 출력과 실제 도구 체인의 결과 사이에서 루프를 닫는다. 에이전트가 낸 코드를 타겟용으로 크로스 컴파일하고, 정적 분석을 돌리고, 플래시와 RAM 사용량을 확인하고, 에러를 구조화된 데이터로 돌려준다. 그러면 에이전트는 짐작하는 대신 실제 컴파일러와 정적 분석 출력을 놓고 반복한다.
스펙 기반 테스팅 파이프라인 전체는 첫 번째 포스트에 적었다. spec.md에 인수 기준을 쓰고, pytest + labgrid를 단일 명령 스크립트로 감싸고, 구조화된 JSON을 돌려받는 방식이다. 빌드 피드백 루프는 같은 원칙을 파이프라인의 더 앞단, 코드가 타겟에 닿기 전에 적용한다. 에이전트는 컴파일러 경고를 스크롤하는 대신 {"check": "cppcheck", "severity": "error", "message": "Buffer access out of bounds"}를 읽고, 커널 로그 대신 {"test": "dma_cache_sync", "outcome": "failed", "reason": "data mismatch after 10000 transfers"}를 읽는다.
세 계층은 서로 보완한다. CLAUDE.md는 이미 알려진 나쁜 패턴으로 코드가 만들어지는 것을 막는다. 서브에이전트는 메인 에이전트가 놓칠 도메인 특화 이슈를 잡는다. 빌드 피드백 루프는 실제 환경에 대고 시험해서 나머지를 잡는다.
달라진 것
컨텍스트 엔지니어링 전에는 에이전트의 코드가 컴파일은 되어도 런타임에서 죽었다. 잘못된 레지스터 주소, 빠진 캐시 동기화, 보호되지 않은 공유 상태 같은 조용한 실패가 진단할 때마다 30분 넘게 걸렸다. 로그에는 근본 원인을 가리키는 것이 하나도 없었기 때문이다.
세 계층을 깔고 나서는 대부분의 모듈이 첫 번째나 두 번째 반복에서 인수 테스트를 통과한다. 남은 재작업은 코드가 깨져서라기보다 스펙이 덜 다듬어져서 생긴다.
안 되는 것
이 방식은 프로덕션 임베디드 드라이버에서 중요한 것의 대략 절반을 덮는다. 나머지는 사람의 몫으로 남는다.
하드웨어 디버깅이 그렇다. 칩 셀렉트 극성이 뒤집혀서 SPI 버스가 멈췄을 때, 컨텍스트 파일은 아무 도움이 되지 않는다. 필요한 건 오실로스코프와 로직 분석기, 그리고 CPOL 비트가 반전됐다는 걸 알아차리기 전까지 프로브를 들여다보는 20분이다. 에이전트가 소프트웨어 장애 주입 스크립트(stress-ng, 강제 모듈 언로드/재로드)는 짜 주지만, 물리적인 장애에는 물리적인 장비가 필요하다.
컨텍스트 저하도 있다. 긴 세션(2시간 이상)을 돌리면 CLAUDE.md가 로드되어 있어도 에이전트가 앞쪽의 제약을 놓친다. 그럴 때는 /clear(Claude Code의 컨텍스트 리셋 명령)를 주저 없이 써서 새로 시작하는 것이 해법이다.
스펙 품질도 남는다. 스펙이 부실하면 다 소용없다. 이 이야기는 첫 번째 포스트에 적었다.
다시 시작한다면
다시 시작한다면 나는 20줄짜리 CLAUDE.md부터 쓰겠다. 타겟 하드웨어, 빌드 시스템, “절대 하지 마” 규칙 3개면 된다. 에이전트가 실수할 때마다 항목을 하나씩 더한다. 그다음에 동시성 리뷰어 서브에이전트를 하나 붙인다. 그다음에는 크로스 컴파일하고 에러를 JSON으로 돌려주는 bash 스크립트로 피드백 루프 하나를 닫는다. 스펙 기반 테스팅 설정 전체는 TDD 포스트에 있다.
더 좋은 모델은 좋은 컨텍스트로 할 수 있는 일의 상한을 끌어올릴 것이다. 그래도 컨텍스트가 필요하다는 사실까지 없애지는 못한다고 나는 생각한다.
이 시리즈의 마지막 포스트에는 프로젝트 구조 전체를 한자리에 모아 두었다. 폴더 구조, 스펙, 4계층 테스트, 리뷰 에이전트, end-to-end 피드백 루프다.
댓글
댓글 불러오는 중...