지금 일어나고 있는 일을 정확히 짚자
'AI가 코드를 쓴다'는 말은 이제 새롭지 않다. 그런데 최근 두 가지 사례를 나란히 놓으면, 그 말의 무게가 다르게 느껴진다. OpenAI가 공개한 오픈소스 프레임워크 Symphony와, 한 개발자가 NestJS 기반 MSA 모노레포에 적용한 Claude Code .claude 디렉토리 설계 전략이다. 둘 다 'AI가 코드를 생성한다'는 이야기가 아니다. 개발자가 코드 작성에서 손을 떼고, AI를 운영하는 역할로 이동하는 구조를 보여준다.
Symphony: 티켓이 에이전트를 깨운다
Symphony는 이슈 트래커와 연동해 작업 상태 변경을 감지하고, AI 에이전트를 자동으로 실행하는 에이전트 관리 시스템이다. 핵심 개념은 '자율 실행(Implementation Run)'—이슈가 'Ready for Agent' 상태가 되는 순간, 샌드박스가 생성되고 에이전트가 코드 구현, 테스트 작성, 수정까지 처리한다. 개발자가 에이전트를 직접 호출하거나 관리하는 게 아니다. 작업(Task) 단위가 흐름을 만들고, 에이전트가 그 흐름에 올라탄다.
여기서 주목할 건 'Proof of Work'(작업 증명) 개념이다. 에이전트가 작업을 완료하면 CI 실행 결과, 단위 테스트 통과 여부, PR 리뷰 피드백, 코드 복잡도 분석까지 묶어서 제출한다. 그 검증을 통과해야 PR이 생성되거나 자동 병합된다. 에이전트가 '완료했다'고 주장하는 게 아니라, 완료를 증명한다. 이전 글에서 다뤘던 Execution Hallucination 문제를 구조적으로 막으려는 설계다.
Symphony가 'Harness Engineering'—AI가 작업하기 좋은 코드 구조—을 전제 조건으로 내세우는 것도 인상적이다. 독립적으로 실행 가능한 테스트, 기계가 읽을 수 있는 문서, 모듈화된 코드. 이건 단순히 AI 도구 사용법이 아니라 코드베이스 자체를 AI 친화적으로 설계해야 한다는 아키텍처 요구사항이다.
.claude 디렉토리: AI를 시니어로 만드는 설정 파일
dev.to에 공유된 Claude Code .claude 디렉토리 설계 사례는 실무 레벨에서 같은 방향을 가리킨다. 이 개발자가 풀려던 문제는 단순하다. 매번 같은 컨벤션을 AI에게 설명하는 게 비효율적이라는 것. 해결책은 프로젝트 규칙을 .claude 디렉토리에 구조화해서 AI가 항상 그 맥락을 이해한 상태로 시작하게 만드는 것이었다.
구조는 5개 레이어로 나뉜다. Rules(어떻게 코드를 써야 하는지), Agents(누구에게 시킬 것인지), Skills(무엇을 할 것인지), Hooks(자동으로 체크할 것), Docs(참조 문서). 각 레이어의 역할이 명확하게 분리되어 있다.
개인적으로 가장 날카롭다고 생각한 부분은 Read-only 에이전트 분리다. code-reviewer와 planner는 disallowedTools: Edit, Write로 설정해 코드를 읽고 분석만 하고, 절대 수정하지 않는다. 리뷰하면서 코드를 바꿔버리는 실수를 구조적으로 막는다. 만능 에이전트 하나보다 역할이 제한된 에이전트 여러 개가 더 안전하다는 원칙을 설정 파일 레벨에서 구현한 것이다.
Skills 체인도 주목할 만하다. /aidlc(기획 티켓 → 구현 계획) → /implement(Entity → DTO → Service → Usecase → Controller 순서 구현) → /bdd-cycle(Acceptance Criteria → Cucumber E2E 테스트 자동 변환)의 3단계 체인이 기획부터 테스트까지 사이클을 완성한다. 그리고 Claude Code로 일주일짜리 ETL 플러그인 개발 작업을 1시간으로 줄인 또 다른 사례(dev.to)는 이 접근법의 생산성 임팩트를 수치로 보여준다.
테크 리드가 지금 바로 가져갈 수 있는 설계 원칙 3가지
두 사례를 묶으면 AI-First 워크플로우 설계 원칙이 보인다.
첫째, 규칙은 구체적인 코드 예시와 함께 버전 관리하라. Symphony의 WORKFLOW.md와 .claude/rules/ 모두 에이전트의 행동 규칙을 소스 코드와 함께 관리한다. "좋은 코드를 써"가 아니라 "Entity에 comment 필수, Before/After 예시 포함"처럼 Before/After 패턴을 구체적으로 명시해야 효과가 있다. 이 파일들은 팀의 코딩 컨벤션 문서이면서 동시에 AI 운영 설명서다.
둘째, 에이전트 권한을 역할 단위로 쪼개라. 만능 에이전트는 위험하다. 리뷰어는 읽기 전용, 플래너는 계획만, 구현자만 편집 권한을 갖는 구조가 품질 사고를 줄인다. Hooks로 DROP TABLE이나 force push main 같은 위험한 명령을 사전 차단하는 안전장치도 필수다. 특히 MCP로 프로덕션 DB에 연결된 환경에서는 선택이 아니라 필수다.
셋째, 코드베이스를 AI 친화적으로 재설계하라. Symphony가 요구하는 Harness Engineering은 사실 좋은 소프트웨어 설계의 다른 이름이다. 독립 실행 가능한 테스트, 모듈화된 코드, 읽기 쉬운 문서. AI를 위한 설계가 결국 사람을 위한 설계와 같다는 것—이게 역설적이지만 핵심이다.
전망: '관리자'가 된 개발자의 새 역량
솔직히 말하면, 지금 당장 Symphony를 팀에 풀가동하는 건 현실적이지 않다. Elixir/BEAM 스택을 다룰 수 있는 팀이 많지 않고, Harness Engineering으로 기존 코드베이스를 재설계하는 비용도 만만치 않다. .claude 디렉토리 설계는 오늘 당장 시작할 수 있지만, 초기 설계 투자 없이 대충 만들면 오히려 일관성 없는 AI 출력이 쌓이는 역효과가 난다.
하지만 방향은 분명하다. 개발자의 핵심 역량이 '코드를 잘 짜는 것'에서 'AI가 잘 짤 수 있게 판을 짜는 것'으로 이동하고 있다. ETL 플러그인 사례의 저자가 정확히 짚었다. Claude Code를 효과적으로 쓰려면 좋은 개발 프로세스를 알고, AI가 학습하기 쉬운 모듈을 설계하고, 제대로 된 테스트를 작성하고, 명확한 마크다운을 쓸 줄 알아야 한다. 이걸 가장 잘 할 수 있는 사람이 지금은 소프트웨어 엔지니어다.
AI가 코딩 노동을 흡수하는 속도보다, AI를 운영하는 역할로 전환하는 속도가 중요해지고 있다. 팀 리빌딩을 계획하고 있다면, 지금 물어야 할 질문은 하나다. "우리 팀원들이 AI에게 일을 잘 시킬 수 있는가?"