AI 협업 적용 (Claude Code 실무)¶

왜 AI와 협업하는지, 위키가 곧 사고의 외부화라는 전제, 에이전트 운영 철학 같은 전사 공통 원칙은 ai-collaboration에 있다. 이 페이지는 그 원칙을 개발 직무에 적용한 실무 — 하네스, 서브에이전트, 코드리뷰 자동화, 스킬 작성 — 만 다룬다.

핵심은 하나다. AI가 우리 프로젝트의 반복 구현 패턴과 구조 규칙을 안정적으로 따르게 만들려고 하네스를 깐다. 위키가 RAG 대체물이 아니라 사고의 외부화이듯, 하네스도 결국 "사람의 컨벤션을 기계가 강제할 수 있는 계약으로 옮겨 놓는" 작업이다.

1. 하네스 구조 (BE/FE 대칭)¶

하네스는 docs(규칙·철학) / skills(실행 절차) / workflows(오케스트레이션) / hooks(검증·제약) 네 층으로 나눈다. 읽는 목적이 다르기 때문이다 — docs는 "왜, 어떻게 설계됐나"를, skills는 "이 작업을 이 순서로"를 답한다.

프론트엔드 .ai/ 예시:

.ai/
  hooks/      ai-check.sh(레이어 위반+tsc+lint 통합 검증) · guardrails.yaml(pre/post write 규칙, 수정금지 경로)
  skills/     create-crud-flow.md · create-post-mutation.md · handle-api-error.md
  workflows/  crud_requested.yaml(CRUD 전체 생성 표준 흐름)
AGENTS.md     진입점 — 어떤 skill/workflow를 쓸지 안내

- hook = 가드레일: 작성 중 제약(guardrails.yaml: API 호출을 features에 못 두게, 수정금지 경로)과 작업 후 검증(ai-check.sh)을 자동 실행 → engineering-principles의 레이어 규칙을 사람이 아니라 스크립트가 지킨다. - skill 선정 기준: 반복률 높고·구조 고정적·실수 포인트 많고·패턴화 쉬운 것부터. CRUD가 1순위인 이유가 이 네 조건을 모두 만족하기 때문. 도입 후보(영역별): - API/Query: create-post/put/patch-mutation(CRUD 세분화), create-pagination-query - UI: create-modal-flow, connect-editor-flow(Tiptap 연결 반복 제거), create-upload-flow, create-form-flow(react-hook-form+zod+mutation 표준화), create-optimistic-update-flow - 테스트: write-playwright-test - skill 템플릿은 create-crud-flow.md 기준으로 통일. workflow는 큰 흐름만(CRUD 전체 도입), 세부 처리(에러)는 skill 참조로 둔다. - 길게 보면 skill을 설명이 아니라 계약(contract)으로 굳히려 한다(input: {domain: quiz} → output: [dto.ts, repository.ts]). 엔드포인트만 주면 전 레이어를 생성하는, 더 강한 형태다. 운영 방침은 실제 작업에 계속 써 가며 다듬고 차단 강도를 조금씩 올리는 것.

백엔드 하네스의 DB·API skill 규칙(FK는 걸되 삭제 연쇄는 앱 오케스트레이터, Role prefix, 조회/명령 아키텍처 분리)은 engineering-principles·backend-architecture와 같은 내용을 공유한다.

2. 서브에이전트 (Claude Code `/agents`)¶

역할 분리형 에이전트를 두어 컨텍스트 오염 없이 작업한다(예: 설계 도움용 architect — 10년차 아키텍트 + 교육 도메인 전문가 system prompt).

운영 결정(work log에서): - 권한 최소화: 필요한 최소 도구만, read-only 제외하고 해제하는 Claude 권장 따름. - 모델: 보조 작업은 Sonnet. - 메모리·범위: project 범위로 만들되 버전관리 부담 때문에 우선 user 메모리로 유지, 공유 필요 시 통합 메모리로 따로 승격. 에이전트 system prompt엔 d-edu 프로젝트 지식까지 주입.

3. 코드리뷰 자동화 (개발 프로세스)¶

오픈챌린지 MVP를 마무리하고 드로잉 개발에 들어가는 시점에 코드 검증 프로세스를 다시 짜고 있다. 방침은 세션 편향이 없는 깨끗한 에이전트로 리뷰하되, 정확한 유저플로우 컨텍스트를 함께 넣어 주는 것이다 — 맥락 없는 리뷰는 얕게 끝난다. 배포·테스트 게이트와의 연결은 version-control에 있다.

4. 스킬·가이드라인 검증 루프¶

새로 쓴 skill이나 AGENTS 문서는 깨끗한 에이전트에게 다섯 관점으로 리뷰시키고 고치기를 반복한다. ① 실제 구조와 충돌하는지, ② AI가 안정적으로 생성할 수 있는지(모호하거나 너무 추상적이지 않은지), ③ 유지보수가 되는지, ④ guardrail·ai-check로 자동 검증이 가능한지, ⑤ 사람 개발자가 보기에 과설계거나 빠진 규칙이 없는지. 목표는 AI도 일관되게 생성하고 사람도 유지보수하기 좋은 구조다.

5. 위키 파이프라인 연동¶

Slack/GitHub ↔ Claude Code, raw→wiki 반영, MCP 연결 등 협업 파이프라인 아키텍처는 infra §3. raw 반영·봇 연동 검증 과정에서 나온 인시던트는 incidents.