AI와 채팅하기에서 그것을 설계하기까지

Source: Dev.to

왜 나는 코드 프롬프트를 중단하고 AI를 시스템으로 다루기 시작했는가

우리 모두 그런 경험이 있다.

AI 코딩 어시스턴트에게 간단한 컴포넌트를 만들어 달라고 요청한다.
코드는 즉시 생성된다. 깔끔해 보인다. 오류 없이 실행된다.

하지만 자세히 살펴보면:

• 우리가 사용하지 않는 새로운 아이콘 라이브러리를 도입했다.
• 프로젝트의 엄격한 폴더 구조를 무시했다.
• 디자인 시스템의 스페이싱 스케일을 사용하지 않고 20px 패딩을 하드코딩했다.

그 뒤로 보통은 앞뒤로 오가는 작업이 이어진다: 모델을 살짝 조정하고, 출력을 리팩터링하고, 아키텍처 드리프트를 수정한다.

어느 순간 문제는 코드 품질이 아니라 컨텍스트임이 명확해졌다.

AI는 팀에 막 합류한 매우 유능한 주니어 개발자와 같다: 구문은 이해하지만 로컬 컨벤션, 제약조건, 의도는 모른다. 이를 해결하려는 대부분의 시도는 “더 좋은 프롬프트”에 초점을 맞춘다. 나에게 더 효과적이었던 것은 구조적 전환이었다: AI와의 상호작용을 시스템 설계 문제로 다루는 것이었다.

AI “운영 체제” 구축

AI를 대화형 도구로 사용하는 대신, 나는 그것을 프로그래밍 가능한 엔진으로 다루기 시작했다. 저장소 안에 AI가 다양한 작업에서 어떻게 동작할지를 관리하는 파일 기반 구조를 점진적으로 도입했다. AI가 스스로 지능적이 되려는 것이 아니라, 명시적으로 컨텍스트를 로드한다. 일부 프로토콜은 언제나 사용 가능하고, 다른 프로토콜은 명확한 가치가 있을 때만 로드된다—주로 @plan이나 @deep-think를 통해. 시간이 지나면서 이것은 일관된 작업 모델로 진화했다.

1. 스위치보드: 단일 진입점

대형 시스템 프롬프트는 규모가 커지면 잘 확장되지 않는다; 규칙이 쌓일수록 행동을 이해하기 어려워진다. 더 많은 지시를 추가하기보다, 나는 copilot-instructions.md—툴링에서 제공하는 관례 파일—를 라우팅 레이어로 재활용했다. 기능적으로 이것은 스위치보드 역할을 한다: 규칙을 포함하기보다 규칙을 가리킨다.

예시 라우팅 로직

If the user types `@plan`, load the Architecture Guidelines.
If they type `@ui-perfect`, load the Design System rules.
If they type `@test`, load the QA protocols.

작은 프롬프트는 가볍게 유지되고, 복잡한 작업은 추가 컨텍스트를 명시적으로 로드한다. 이 분리는 예측 불가능한 행동을 크게 줄였다.

2. 의사결정 단계로서의 깊은 사고

AI에게 직접 해결책을 묻는 경우 흔하거나 일반적인 패턴이 나오기 쉽다. 트레이드오프가 필요한 작업에서는 전용 단계인 @deep-think를 사용한다.

이 모드에서 모델은 다음을 수행해야 한다:

1. 시스템 수준 관점에서 문제를 검토한다.
2. 여러 접근 방식을 제안한다.
3. 위험과 제약을 명시한다.

그 사고 과정을 구조화하기 위해 나는 간단한 신호등 루브릭을 사용한다:

• 🔴 BLOCKER — 제약과 충돌하거나 명확한 위험을 초래
• 🟡 WARNING — 실행 가능하지만 눈에 띄는 트레이드오프 존재
• 🟢 OPTIMAL — 정렬되고, 유지보수 가능하며, 시스템과 일치

라벨 자체가 중요한 것이 아니라 구현 전에 결정을 정당화해야 한다는 요구가 핵심이다. 이 단계의 중요한 부분은 **“구현 전에 검색”**이다: 모델이 기존 코드베이스에서 패턴, 유틸리티, 선행 작업을 스캔하여 중복과 분산을 지속적으로 줄인다.

3. 선택적 레이어로서의 거버넌스

규모가 크거나 장기적인 기능에 대해서는 때때로 명시적인 거버넌스 파일을 도입한다:

• 아키텍처 경계
• 코드 스타일 제약
• 알려진 안티패턴

이 파일들은 주로 AI 행동을 고정시키기 위해 존재하며, 인간을 위한 문서는 아니다. 의도적으로 옵트인 방식이며, 작은 작업이나 탐색적 작업에서는 완전히 생략한다. 목표는 절차적 부담이 아니라 측정 가능한 레버리지를 확보하는 것이다.

4. 계획과 실행 분리

또 다른 유용한 조정은 설계와 구현을 분리한 것이다. AI에게 동시에 계획하고 구축하도록 요구하기보다, 과정을 나눴다.

@plan

이 단계는 PLAN.md 문서를 생성한다. 내용은:

• 영향을 받는 파일
• 고수준 데이터 흐름
• 모듈 경계와 계약
• 테스트 고려사항

코드는 생성되지 않는다. 계획은 독립적으로 검토·조정될 수 있다.

@build

계획이 승인된 후에만 @build를 실행한다. 이때 AI는 계획을 사양으로 간주하고 직접 구현한다. 이 분리는 의도치 않은 구조적 변화를 크게 줄였다.

5. UI 정확도 다루기

시각적 정확도는 가이드가 없으면 AI 출력이 신뢰하기 어려운 영역이다. UI 세부 사항이 중요한 경우 전용 @ui-perfect 단계를 사용한다. 흐름은 간단하다:

1. 분석 디자인에서 레이아웃과 간격을 파악한다.
2. 매핑 측정값을 디자인 시스템 토큰에 연결한다.
3. 정규화 후에만 구현한다.

이 단계는 보편적인 것은 아니지만, 정밀도가 요구될 때 분석과 구현을 분리하면 더 일관된 결과를 얻을 수 있다.

6. 전형적인 흐름

표준 기능 워크플로는 이제 다음과 같다:

1. @plan 실행
2. PLAN.md 검토 및 다듬기
3. @build 실행
4. 동작 검증
5. 시각적 정밀도가 필요하면 @ui-perfect 실행
6. @extract-concerns 실행
7. @test 실행

프로세스 자체는 복잡하지 않다; 바뀐 것은 예측 가능성이다.

결과

이 접근법이 판단의 필요성을 없애지는 않았다. 바뀐 것은 그 판단이 적용되는 위치다. 출력을 사후에 수정하는 대신, 출력이 생성되는 컨텍스트를 사전에 정의하는 데 노력을 투자한다.

이는 일반적인 처방이 아니라, 나에게서 자연스럽게 떠오른 작업 방식이며, AI 출력을 프로덕션 기대치에 맞추는 데 도움이 된 방법이다.