AI 협업 원칙 (하네스 엔지니어링)¶

우리는 AI를 "코드를 대신 쳐주는 도구"로만 보지 않는다. AI가 안정적으로 우리 방식대로 일하게 하려면 그만한 환경을 깔아줘야 하는데, 그 환경 전체를 하네스(harness)라 부른다. 이 페이지는 그 하네스를 어떻게 설계하고 운영하는지에 대한 회사 공통 기준이다 — 개발·기획·디자인·마케팅 각 hub는 여기를 출발점으로 삼고 자기 영역에 맞는 적용만 덧붙인다.

한 가지 먼저 짚고 갈 것이 있다. 위키와 하네스의 본질은 검색(RAG)을 대체하는 게 아니라 우리 사고를 밖으로 꺼내 글로 박제하는 것이다. 머릿속 판단을 문서로 외부화해 두면 AI가 그걸 컨텍스트로 삼아 다음 작업을 우리답게 해낸다.

왜 하네스를 두는가¶

프로젝트가 커지면 똑같은 구현 패턴과 구조 규칙이 계속 반복된다. 이걸 매번 사람이 설명하는 대신 하네스에 박아두면, AI가 안정적으로 그 규칙을 따른다. 다만 목표가 "AI가 편하게"에 머물면 안 된다. 같은 구조가 사람 개발자에게도 유지보수하기 좋아야 한다 — 둘은 보통 같은 방향을 가리킨다.

하네스의 네 계층¶

하네스는 성격이 다른 네 종류의 글로 이뤄진다. 핵심은 읽는 목적이 다르면 파일도 분리한다는 것이다. 규칙·철학을 이해하려고 읽는 글(docs)과, 손을 움직이려고 읽는 글(skills)을 한 곳에 섞으면 둘 다 흐려진다.

계층	역할	위치(예)
docs / AGENTS.md / CLAUDE.md	규칙·아키텍처·철학 — 읽는 목적은 "이해"	`mvp-front/AGENTS.md`, `CLAUDE.md`
skills	단계별 작업 패턴 — 읽는 목적은 "실행 절차"	`.ai/skills/*.md`, `.claude/skills/`
workflows	여러 skill을 순서대로 엮는 오케스트레이터	`.ai/workflows/*.yaml`
hooks	작성 중 제약(guardrail) + 작업 후 검증	`.ai/hooks/ai-check.sh`, `guardrails.yaml`

같은 사실을 docs와 skills 양쪽에 중복으로 적지 않는다. 규칙은 docs에, 절차는 skills에 — 한 곳에만 둔다.

skill을 어떻게 설계하나¶

반복되는 작업은 skill 단위로 잘라낸다. 예를 들어 프론트엔드에는 create-crud-flow, create-post/put/patch-mutation, connect-editor-flow, create-form-flow, write-playwright-test 같은 skill이 있다. CRUD skill은 endpoint·request·response만 넣으면 repository, query hook, mutation, query key, invalidateQueries, 로딩·에러 상태까지 일관된 형태로 찍어낸다. 이때 PATCH(부분 수정)와 PUT(전체 교체)의 차이를 명시해 둬서 AI가 헷갈리지 않게 한다.

손으로 일일이 확인하기 어려운 규칙은 hooks가 자동으로 잡는다 — 레이어 경계 위반 차단, tsc·lint, 건드리면 안 되는 경로(shared/ui 직접 수정이나 entities 바깥 API 생성 등) 차단, query key 누락이나 mutation 후 invalidate 누락 검사 같은 것들이다.

도입은 한꺼번에 하지 않고 단계적으로 한다. 먼저 docs·AGENTS·rules로 규칙을 세우고, 그다음 skills·workflow·ai-check로 절차와 검증을 붙이고, 마지막에 retrieval 자동화·test retry·reviewer agent까지 올린다.

DB·API 설계에서 하네스가 강제하는 것¶

AI가 코드를 짤 때 가장 흔들리기 쉬운 게 데이터·API 설계라, 여기에 명확한 가드를 박아뒀다.

DB 쪽에선 정합성을 DB 제약에 맡기지 않고 소스코드를 단일 원천으로 삼는다. JPA Entity는 BaseEntity를 상속하고 Auto ID를 쓰며, Flyway 마이그레이션은 한 스크립트에 한 관심사만 담고, Enum은 varchar로, 외래키 제약은 쓰지 않는다.

API 쪽에선 권한을 URL prefix로 가른다 — 역할별(student·teacher·parents)로 나누고, 공통은 common, 비회원 공개는 조건부 인증을 두는 public이다. 조회는 계층형(Controller→Service→Repository)으로, 명령은 포트/어댑터(Controller→Service→Domain←Port←Adapter)로 흐른다. 더 깊은 규칙은 engineering-principles에 있다.

Claude Code 에이전트 운영¶

서브에이전트는 /agents 명령으로 만들거나 .claude/agents에 md를 직접 넣어 추가한다. 권한은 최소로 — read-only를 기본으로 두고, 모델·메모리 범위도 처음엔 개인(user) 수준으로 유지하다가 정말 공유가 필요해지면 공유 메모리로 합친다. 에이전트 가이드라인 초안과 프롬프트는 폐기하지 않고 원본에 계속 쌓아간다.

LLM이 위키를 쓰는 흐름¶

다시 강조하면, 위키는 검색 인덱스가 아니라 사고를 밖으로 꺼내 누적하는 아티팩트다. 그래서 흐름이 단순하다. 작업이나 논의에서 얻은 판단을 해당 페이지에 정리해 담고, 같은 사실이 두 곳에 생기지 않도록 링크로 한 곳에 모으고, 그러면 LLM이 그 위키를 컨텍스트로 다음 작업을 해낸다. 페이지 형식·메타데이터·반입·점검 같은 위키 운영 규칙 자체는 wiki-spec이 단일 기준이라 여기서 되풀이하지 않는다.

논의가 위키로 흐르게 하는 길¶

논의가 채팅에서 증발하지 않고 위키 산출물로 이어지도록 진입점을 둘로 정했다 — Slack은 원본(raw)으로, GitHub Issue는 위키로 흐른다. 이 흐름을 떠받치는 자동화(Slack Bolt + Cloudflare Workers + claude-code-action)와 산출물이 어디로 가는지에 대한 결정은 위키 운영계 ADR로 관리하며, 인덱스는 decisions에 있다.