AI와 일하는 환경을 인프라로 만들기

AI 협업 환경은 프롬프트 하나가 아니라 의도, 맥락 검색, skill routing, 실행, 검증, memory 승격이 이어지는 반복 루프입니다.

Eugene Yan의 “How to Work and Compound with AI”를 읽고, bluetape4k에서 실제로 쓰는 AI 작업 환경을 다시 정리해 보고 싶어졌다. 지난 글이 “Claude Code와 Codex로 무엇을 했는가”였다면, 이번 글은 “그 작업이 매번 처음부터 다시 흔들리지 않게 무엇을 깔아 두었는가”에 가깝다.

처음에는 프롬프트를 잘 쓰면 충분할 줄 알았다. 하지만 repository가 늘어나고, Kotlin/Spring/Exposed/Ktor 규칙이 쌓이고, GitHub issue와 PR, lessons, CI, release까지 엮이기 시작하자 프롬프트만으로는 부족했다. AI에게도 사람과 비슷한 온보딩 문서, 작업 절차, 검색 가능한 과거 기록, 검증 장치가 필요했다.

bluetape4k에서는 그 역할을 AGENTS.md, CLAUDE.md, skills, qmd, memory, hooks가 나눠 맡는다. 모델은 계속 바뀌지만, 이런 작업 환경은 다음 세션에도 남는다.

AGENTS.md와 CLAUDE.md는 온보딩 문서다

사람에게 새 프로젝트를 맡길 때 README 하나만 던져 주지 않는다. 코드 구조, 브랜치 정책, 테스트 방식, 문서 언어, 하지 말아야 할 선택, 과거 의사결정까지 알려 준다. AI에게도 같은 정보가 필요하다.

bluetape4k workspace의 AGENTS.md는 Codex의 기본 온보딩 문서 역할을 한다. 대화는 한국어로 유지하되 public KDoc, PR, commit message는 영어로 작성한다는 규칙이 있다. develop은 기본 통합 브랜치이고, main은 release-only라는 Git 정책도 있다. Kotlin 코드를 고치기 전에는 영향 범위와 참조를 확인하고, .kt 파일을 수정한 뒤에는 IDE diagnostics, import 정리, deprecation 해결, compile/test를 거치라는 규칙도 들어 있다.

Claude 쪽에는 ~/.claude/CLAUDE.md, commands, skills, hooks가 있다. Codex 쪽에는 ~/.codex/config.toml, skills, MCP, native subagents, repo-local AGENTS.md가 있다. 도구는 다르지만 목적은 같다. 새 세션을 새 동료처럼 온보딩하고, 반복해서 말해야 하는 선호와 금지 사항을 durable configuration으로 승격하는 것이다.

이 문서들은 계층을 가진다. home directory에는 전역 규칙이 있고, bluetape4k workspace root에는 조직 공통 규칙이 있고, 각 repository에는 더 좁은 규칙이 있다. Kotlin library repository와 blog repository가 같은 규칙을 모두 공유할 수는 없다. 그래서 가까운 문서일수록 더 구체적인 판단을 제공한다.

Skills는 반복 작업의 실행 절차다

프롬프트가 “이렇게 생각해 줘”에 가깝다면, skill은 “이 절차로 일해 줘”에 가깝다. 반복 작업을 프롬프트 몇 줄에 맡기면 매번 조금씩 빠진다. skill로 만들면 어떤 자료를 먼저 읽고, 어떤 gate를 통과하고, 어떤 검증을 해야 하는지 더 안정적으로 재사용할 수 있다.

bluetape4k에서는 bluetape4k-workflow가 첫 router 역할을 한다. 작업을 Full Design, Fast Track, Bug Fix, Code Review, Maintenance 같은 lane으로 나누고, 그 작업에 맞는 검증 수준을 고른다.

아래에는 더 좁은 skill들이 있다. bluetape4k-design은 새 module, 큰 API 변경, multi-layer 변경처럼 설계가 필요한 작업을 맡는다. bluetape4k-patterns는 Kotlin 구현과 final checklist를 다룬다. ecc-kotlin-exposed, ecc-springboot-kotlin, ecc-kotlin-testing, kotlin-coroutines-skill은 Exposed, Spring Boot, testing, coroutine 같은 도메인별 판단을 분리한다. review-delta, review-pr, code-review, bugfix-workflow는 변경 검토와 후속 수정을 위한 절차다.

“README도 맞춰 줘”, “Exposed deprecated import를 조심해 줘”, “affected module test로 증명해 줘” 같은 지시를 매번 새로 쓰면 빠지기 쉽다. 관련 skill이 checklist를 가져오면 반복 지시가 줄고, 검증 기준도 더 명확해진다.

qmd는 오래된 결정을 찾는 검색 계층이다

AI 세션은 쉽게 기억을 잃는다. 반대로 저장소에는 문서, lessons, issue, PR, 계획서, 실험 기록이 계속 쌓인다. qmd는 이 둘을 연결하는 검색 계층으로 쓴다.

bluetape4k에서는 prior decisions, lessons, specs, plans, historical context를 찾을 때 qmd를 먼저 쓴다. workspace 문서는 bluetape4k-docs collection에서 찾고, 개인 또는 cross-project 지식은 wiki collection에서 찾는다.

정확한 code symbol이나 파일명은 여전히 rg가 빠르다. 하지만 “예전에 왜 이 결정을 했지?”, “비슷한 모듈을 어디에서 만들었지?”, “이런 실패를 겪은 적이 있나?” 같은 질문은 qmd가 더 잘 맞는다. qmd를 통하면 먼저 관련 문서를 좁히고, 그 다음 실제 코드와 PR 기록으로 내려갈 수 있다.

이 차이가 중요하다. AI에게 저장소를 한 번에 다 읽히는 것은 비싸고 불안정하다. 반대로 검색 계층을 두면 필요한 맥락을 먼저 찾고, 작업에 필요한 범위만 읽게 할 수 있다.

Memory는 세션 밖에 있어야 한다

Claude와 Codex 모두 세션 안의 기억만 믿으면 불안정하다. 그래서 bluetape4k에서는 memory를 여러 층으로 둔다.

짧은 작업 상태는 .omx/state, .omx/notepad.md, .omx/plans 같은 runtime artifact에 남는다. 더 오래 가야 하는 설계 결정은 docs/superpowers/specs, docs/superpowers/plans에 둔다. 작업에서 배운 교훈은 docs/lessons에 남긴다.

lesson은 길 필요가 없다. 어떤 맥락에서 무엇을 결정했고, 결과가 어땠고, 어떤 검증을 했고, 다음 agent가 무엇을 다르게 해야 하는지만 있으면 충분하다. 이 기록이 있어야 다음 AI 세션이 같은 결정을 다시 추론하지 않는다.

중요한 것은 “저장” 자체가 아니라 “다음 작업에서 다시 읽히는가”다. lesson이 아무 skill에도 반영되지 않고, 검색에도 걸리지 않고, 다음 작업에서 읽히지 않는다면 그냥 오래된 메모일 뿐이다. 반복되는 교훈은 skill, AGENTS.md, hook, test로 승격해야 한다.

Hooks는 자주 하는 실수를 먼저 잡는다

AI에게 “조심해”라고 말하는 것만으로는 부족하다. 사람도 CI, pre-commit, lint가 필요하다. AI도 마찬가지다. 반복적으로 중요한 규칙은 hook으로 옮긴다.

Claude 환경에는 sensitive file 차단, destructive git guard, Kotlin checker, Gradle test guard, README sync reminder, keyword detector 같은 hooks가 있다. Codex 환경도 hooks와 native subagents, skill routing으로 비슷한 역할을 한다.

hook의 목적은 모델을 못 믿어서가 아니라, 흔한 실수를 일찍 발견하는 것이다. destructive command, 잘못된 branch naming, sensitive file 접근, workflow 변경 누락, 테스트 미실행 같은 문제는 빨리 막을수록 비용이 작다. CI에서 늦게 알게 되는 것보다 작업 중간에 바로 멈추는 편이 낫다.

Delegation은 검증과 함께 가야 한다

Codex native subagents나 OMX team mode를 쓰면 여러 작업을 병렬로 맡길 수 있다. 하지만 병렬성이 품질을 보장하지는 않는다. 오히려 병목은 구현 속도에서 “각 agent가 어떤 파일과 책임을 소유하는가”, “결과를 어떻게 검증하는가”, “충돌을 어디에 보고하는가”로 옮겨 간다.

그래서 bluetape4k에서는 “완료”를 설명으로 판단하지 않는다. 작은 변경이면 targeted test나 build check면 충분하다. Kotlin 코드를 고쳤다면 IDE diagnostics, import 정리, deprecation 확인, affected module test가 기본이다. public API가 바뀌면 KDoc과 README도 같이 본다. GitHub workflow가 바뀌면 nightly workflow 영향도 확인한다.

이 규칙이 있어야 delegation이 가능하다. 여러 agent가 동시에 움직여도, 최종 판단은 검증 결과와 변경 범위에 기댈 수 있어야 한다.

Codex와 Claude는 같은 환경을 다른 방식으로 읽는다

실제로는 Codex와 Claude가 완전히 같은 방식으로 일하지 않는다. Codex는 AGENTS.md, skills, MCP/context-mode, qmd, native subagents로 repository context를 읽는다. Claude는 CLAUDE.md, commands, skills, hooks, project history에서 비슷한 정보를 읽는다.

그래서 durable guidance는 한쪽에만 머물면 안 된다. Codex 쪽에서 발견한 반복 규칙이 Claude 작업에도 필요하다면 repository 문서나 shared skill로 옮겨야 한다. 반대로 Claude가 반복해서 잡아낸 문제도 Codex가 읽을 수 있는 문서나 skill로 승격해야 한다.

결국 핵심 문장은 단순하다.

이 repository의 workflow를 따르고, 영향 범위를 확인하고, 검증으로 증명하고, 다음 agent가 읽을 짧은 lesson을 남겨라.

환경도 리팩터링해야 한다

AI 작업 환경도 codebase처럼 낡는다. skills가 겹치고, hooks가 잘못된 경고를 내고, 긴 AGENTS.md와 CLAUDE.md가 정작 중요한 규칙을 묻어 버릴 수 있다. 그래서 환경 자체도 주기적으로 정리해야 한다.

내 기준은 단순하다. 같은 수정을 두 번 했다면 rule이나 skill 후보로 본다. 같은 실패를 세 번 봤다면 hook이나 test 후보로 본다. 더 이상 쓰지 않는 절차는 삭제한다. 일회성 메모리는 남기지 말고, 반복 가능한 결정만 durable artifact로 승격한다.

결론

AI와 오래 일하면서 얻은 교훈은 모델보다 환경이 더 오래 누적된다는 점이다. 모델은 계속 바뀐다. 하지만 잘 정리된 저장소, 명확한 AGENTS.md와 CLAUDE.md, 반복 작업을 담은 skills, qmd로 검색 가능한 지식, 검증을 강제하는 hooks, 짧게 남긴 lessons는 다음 세션에도 남는다.

AI 협업의 핵심은 “더 좋은 프롬프트”보다 “더 좋은 작업 환경”에 가깝다. AI를 한 번 쓰는 도구로 보면 결과는 세션마다 흔들린다. AI를 새 동료처럼 온보딩하고, 작업 절차를 코드처럼 관리하고, 검증 방법과 기억을 인프라에 누적하면 결과도 점점 안정된다.