AI 하네스 – 미니앱 제작에 적용한 방법

AI 하네스는 AI 모델을 둘러싸고 도구와 컨텍스트를 관리하는 소프트웨어 층을 가리키는 말입니다. 모델이 “무엇을 할지”를 추론한다면, 하네스는 그 추론이 실제 작업으로 이어지도록 도구를 건네고 모델이 볼 내용을 골라 줍니다.

이 글은 두 부분으로 되어 있습니다. 앞에서는 AI 하네스가 무엇으로 이루어지는지 정리하고, 뒤에서는 앱인토스 미니앱을 만들 때 그 위에 무엇을 얹어 쓰는지를 코드와 함께 보여 드립니다.

AI 하네스란 무엇인가

AI 모델은 글자를 받아 글자를 내놓습니다. 파일을 열거나 명령을 실행하는 건 모델이 아니라 모델을 감싼 프로그램이 합니다. Claude Code 공식 문서는 이 관계를 이렇게 설명합니다. 에이전트의 동작은 추론하는 모델과 행동하는 도구로 이루어지고, 모델을 둘러싸고 도구를 제공하며 모델이 볼 컨텍스트를 관리하는 층을 에이전트 하네스라고 부른다는 것입니다.

하네스가 맡는 일을 제 나름대로 다섯 가지로 나눠 보면 이렇습니다. 오른쪽 칸은 이 글의 프로젝트에서 그 자리를 무엇이 채우는지입니다.

하네스는 두 겹이다

표를 보면 층이 둘로 나뉩니다.

이 글에서 “하네스를 만든다”고 할 때 가리키는 건 두 번째입니다. 실행 루프를 새로 짜는 게 아니라, 이미 있는 하네스 위에 내 프로젝트의 규칙과 검사를 얹는 일이에요. 이 글의 나머지는 전부 이 두 번째 층 이야기입니다.

프롬프트를 잘 쓰는 것과는 무엇이 다를까요.

미니앱 제작에 얹은 AI 하네스

제가 쓰는 AI 하네스는 앱 번호를 받아서 일하는 스크립트입니다. 아래 그림이 앱 하나를 작업할 때의 흐름이에요.

네 가지 지점을 차례로 보겠습니다.

1. 시작할 때 읽을 것을 정해 준다

AI가 폴더를 통째로 훑으면 지금 작업과 상관없는 내용까지 읽어 들입니다. 그만큼 AI가 한 번에 다룰 수 있는 분량을 낭비하게 돼요. 그래서 작업은 항상 context 명령으로 시작합니다. 앱 번호를 넣으면 그 앱의 현재 상태와 함께, 다음에 읽을 파일 목록을 돌려줘요.

아래는 실제 출력의 끝부분입니다. 파일 이름 두 곳만 가렸어요.

  "status": {
    "errors": [],
    "warnings": [
      "스마트발송은 공식 정책 근거로 not_applicable 처리됐습니다. 알림 설정·동의 요청·발송 코드가 없어야 합니다."
    ],
    "standard": []
  },
  "readNext": [
    "appintoss/plans/approved/(이 앱의 계획서).md",
    "appintoss/(이 앱의 폴더)/src/App.tsx"
  ]

이 앱의 경우 readNext에 든 건 계획서와 앱의 중심 파일 둘뿐입니다. 규칙 파일에는 “항상 context로 시작하고 readNext에 있는 파일만 읽는다”고 적어 뒀어요. 앱 이름이나 광고 설정 같은 값은 출력에 이미 들어 있어서, 그걸 확인하려고 설정 파일을 다시 열 필요도 없습니다.

목록을 만드는 코드는 길지 않습니다.

    readNext: [
      ...(plan ? [path.relative(root, plan.file)] : []),
      ...(data.spec ? [`${project.relativeDir}/src/App.tsx`] : [`${project.relativeDir}/app.spec.json`, `${project.relativeDir}/src/App.tsx`]),
    ]

2. 규칙을 문장 대신 검사로 바꾼다

규칙을 문서에 적어 두는 것과, 그 규칙이 지켜졌는지 확인하는 것은 별개의 일입니다. 그래서 자주 나오는 규칙은 check 명령이 코드를 직접 들여다보게 했습니다.

날짜 규칙이 좋은 예입니다. 자바스크립트에서 흔히 쓰는 날짜 추출 방식은 세계 표준시 기준이라, 한국 시간으로 자정부터 오전 9시 전까지는 어제 날짜가 나옵니다.

  for (const file of sourceFiles) {
    if (UTC_DAY_EXTRACTION.test(file.code)) {
      errors.push(`src/${file.name}:${locate(file.code, UTC_DAY_EXTRACTION)} extracts a day from toISOString(), which is UTC: KST 00:00-08:59 yields yesterday. Use getKSTDateString() from src/lib/dateUtils.ts`);
    }

소스 파일을 하나씩 돌면서 문제의 패턴을 찾고, 있으면 오류 목록에 넣습니다. 눈여겨볼 건 오류 메시지예요. 어느 파일 몇 번째 줄인지, 왜 문제인지, 대신 무엇을 써야 하는지가 한 줄에 다 들어 있습니다. 모든 검사가 줄 번호까지 짚어 주는 건 아니고, 이 날짜 검사와 화면 높이 검사가 그렇게 합니다.

3. 검증을 거쳤는지 지문으로 확인한다

출시 전에는 검증을 맡은 AI 에이전트 셋이 앱을 봅니다. 이름과 설명이 약속한 것이 화면에 실제로 있는지, 앱을 띄웠을 때 모든 화면이 동작하는지, 검수에서 반려될 만한 것이 남아 있지 않은지를 각각 확인해요.

문제는 “검증을 받았다”는 사실이 금방 낡는다는 점입니다. 검증 뒤에 코드를 고치면 그 검증은 더 이상 지금 코드에 대한 것이 아니니까요. 그래서 판정을 기록할 때 소스의 지문을 같이 남깁니다.

function sourceFingerprint(project) {
  const files = fingerprintFilePaths(project);
  const hash = crypto.createHash('sha256');
  for (const file of files) {
    hash.update(path.relative(project.dir, file));
    hash.update(fs.readFileSync(file));
  }
  return hash.digest('hex').slice(0, 16);
}

지문 대상으로 정해 둔 파일을 정해진 순서로 읽어 16자리 값 하나로 줄입니다. 대상은 화면 코드와 앱 설정 파일 같은 것들이고, 이 가운데 한 글자라도 바뀌면 값이 달라져요. 검사할 때는 기록에 적힌 지문과 지금 지문을 비교하고, 다르면 어떤 파일이 바뀌었는지까지 알려 줍니다.

여기에 장치가 하나 더 있습니다. 다른 지적을 고치느라 지문이 달라졌을 뿐 그 검증이 본 부분은 그대로라면, 다시 돌리지 않고 기록을 넘길 수 있어요. 대신 왜 범위 밖인지 이유를 반드시 적어야 하고, 원래 판정 시각과 바뀐 파일 목록이 기록에 남습니다. 검증을 다시 돌리는 데도 비용이 드니, 필요한 것만 다시 하게 한 겁니다.

4. 만드는 동안은 경고, 출시할 때는 차단

같은 검사라도 언제 하느냐에 따라 무게를 다르게 뒀습니다.

  // 릴리스에서만 막는다. 개발 중에는 경고로만 보인다.
  for (const message of auditProblems(project)) {
    if (release) result.errors.push(message);
    else result.warnings.push(message);
  }

만드는 중에는 감사 기록이 없어도 경고만 뜹니다. check --release로 돌릴 때는 같은 문제가 오류가 되고, 하나라도 남아 있으면 통과하지 못합니다. 광고 설정처럼 빠진 항목도 평소에는 대부분 할 일 목록으로만 보이다가 출시 검사에서 오류로 바뀌어요. 원본 주석은 이런 항목을 “고장 난 코드가 아니라 품질 작업”이라고 구분합니다.

번들을 만드는 build 명령은 맨 마지막에 이 출시 검사를 직접 돌립니다. 그래서 검사를 건너뛴 채로 빌드를 끝낼 수 없어요.

규칙 파일은 목차로 쓴다

스크립트만큼 신경 쓴 것이 규칙 파일입니다. AI가 세션을 시작할 때마다 읽는 파일인데, 여기에 아는 것을 다 적으면 매번 그만큼을 읽고 시작하게 됩니다. 그래서 이 파일은 목차 역할만 하게 했어요.

파일에는 꼭 지킬 규칙 몇 줄과 “이런 게 필요하면 이 문서를 열어라”는 표가 있습니다. 제작 절차, 화면 설계 기준, 공식 문서 주소 같은 건 각자 다른 문서에 있고, 작업에 필요할 때만 엽니다. 분량이 큰 참고 문서는 통째로 열지 말고 검색해서 필요한 구간만 읽으라고 적어 뒀어요.

처음 만든다면 이 순서로

AI 하네스를 새로 만든다면 저는 이 순서를 권합니다.

검사를 늘릴 때는 오류 메시지에 공을 들이는 게 좋습니다. 어디가 왜 틀렸고 무엇으로 바꿔야 하는지를 메시지에 담아 두면, 고칠 때 다른 문서를 다시 찾아볼 필요가 없습니다.

이 AI 하네스로 만든 앱들의 이야기는 프로젝트 진행 방식과 환율 계산기 글에 있습니다.

글에 나온 규칙 파일과 에이전트는 Claude Code에서 쓰는 방식이고, 공식 안내는 Claude Code 공식 문서에 있습니다.

이 글은 직접 만들고 운영하며 남긴 기록입니다. 적힌 수치는 작성 시점의 제 계정 기준이며, 같은 결과나 수익을 보장하지 않습니다.