설계 전후에 AI에게 '설계 의도'를 출력하도록 했다

AI에게 개발을 맡길 때, 이전에는 다음 흐름으로 진행하고 있었다.

요구사항 → 설계 → 구현

설계 내용에 문제가 없다면 구현 단계로 넘어가는 방식이었다.

다만, 개발이 복잡해지고 여러 태스크를 동시에 돌리게 되자 다음 두 가지가 눈에 띄었다.

• AI의 설계서는 정성껏 작성되지만, 분량만으로는 '어디가 중요하고 어디가 중요하지 않은지' 파악하기 어렵다.
• 자신의 이해와 AI의 이해가 어긋나서 엉뚱한 구현을 하게 된다.

인간으로서 개발의 오너십(ownership)을 가지려면, 단순히 'AI가 구현하게 했다'는 것만으로는 부족하다. 어떤 의도로 이 설계를 했는지를 자신이 파악하고 있어야 한다.

설계 전후에 단계를 하나 추가했다. 다음 중 어느 쪽이었다.

A. 요구사항 → 요건/설계 의도 → 설계 → 구현
B. 요구사항 → 설계 → 설계 의도(요구사항 해석) 출력 → 확인 → 구현

요구사항에서 바로 설계를 내보내게 하는 것이 아니라, '이러한 의도로 개발을 진행하면 좋다'는 요건 정의에 가까운 것을 한 번 출력하게 했다.

실제로 사용한 프롬프트(지시어)는 다음과 같은 짧은 질문이었다. A는 A의 전 단계에서, B는 생성된 결과물에 대해 사용했다.

# 요구사항에서 설계/구현으로 진행할 경우(A)
제 요구사항으로부터 어떤 의도를 추출하셨나요?
# 생성된 결과물에 대해(B)
...

특별한 방식으로 작성하지 않아도, 설계 의도는 충분히 출력되었다.

A와 B에서는 출력되는 의도의 성질이 크게 다르다.

• A: 설계 전에 의도를 출력시키고, 그 의도를 전제로 설계를 하도록 한다. 의도로 AI를 구속한 상태에서 출력을 받기 때문에 제어할 수 있는 상태가 된다.
• B: 이미 존재하는 것에서 의도를 추측한다. 사람이 작성한 코드든, AI가 작성한 코드든, 설계서든, 코드 내 주석이든 동일하며, 나오는 의도는 단지 추측에 불과하다.

이후의 두 가지 예시는 둘 다 AI가 무엇을 근거로 만들려고 했는지 보기 위해 사용했다. B의 의도는 추측임을 전제로 자신의 요구사항과 대조하여 확인하고 있다.

등장인물은 다음과 같다.

• 업무 담당자: RAG를 평가하는 사람이며, 실제로 질문을 하는 사용자이기도 하다. 각 산업의 도메인 지식은 가지고 있지만, 이번 문서의 폴더 구조는 모른다.
• 우리 개발팀: 답변 예시를 작성하는 사람. 도메인 지식은 없지만, 폴더 계층 구조는 대략 파악하고 있다.
• 질문 생성 AI: 우리 개발팀이 개발에 사용하는 AI이다. RAG 안에서 실제로 답변하는 AI와는 별개의 AI이다.

업무 담당자와 개발팀의 관계는 기업 내부에서도, 외주 개발과 발주자 사이에서도 동일하게 성립되는 구도이다.

RAG 평가에서는 실제 사용자로부터의 질문이 특정 토픽에 치우치기 쉽다는 문제가 있었다. 그래서 이번에는 개발팀에서 사전에 질문과 답변 예시를 Excel로 정리하고, '이 질문에 대해 실제로 잘 답변되고 있는지'를 확인하는 방침을 세웠다.

질문 생성 단계에서 어긋남이 발생했다.

• AI는 참조 문서의 내용으로부터 질문을 만들고 있었다.
• RAG는 문서를 참조하면 답할 수 있도록 만들어져 있다. 문서로부터 만든 질문은 당연히 답변될 것이라고 여겨진다.
• 평가로서 의미 있는 질문을 만들기 위해서는, 문서 내용에 끌려가지 않는 어느 정도의 랜덤성이 필요했다.

이 의도가 AI에게 전달되지 않았다. 그래서 '현재 질문 생성의 설계 의도는 어떠한가'를 출력하게 했더니, 인식 차이가 명확해졌다.

그 후, 다음 방침으로 재정리했다.

• 우리 개발팀은 대상 분야의 도메인 지식이 없다.
• 하지만, 문서를 모은 폴더의 계층(폴더 트리)을 보면 어느 분야의 자료인지 어느 정도 파악할 수 있다.
• 업무 담당자는 도메인 지식은 가지고 있지만, 폴더 구조는 모른다. 이 '업무 담당자는 구조를 모른다'라는 차이가 개발팀이 폴더 계층에서 분야를 추측하여 질문을 만드는 의미가 된다.
• 즉, 질문은 문서의 본문이 아니라, 폴더 계층에서 읽어낼 수 있는 분야 정보를 바탕으로 만들어야 한다.

설계서를 그대로 읽고만 있었다면 아마 알아차리지 못했을 차이점이다. 설계 의도를 별도로 출력하게 함으로써 '무엇을 근거로 질문을 만들려고 하는지'가 한눈에 확인되었다.

개인적으로 YouTube나 X의 영상을 다운로드할 수 있는 앱을 만들었다. X 같은 경우 로그인을 하고 연동하지 않으면 다운로드가 거부되어 에러가 나기 때문에, 로그인 기능이 필요했다.

나의 의도: 이미 로그인된, 열려 있는 브라우저에서 로그인 세션 정보를 가져오는 것 -

실제로 구현된 것: '로그인' 버튼을 누르면, 로그인이 되어 있지 않은 새로운 브라우저가 열리고, 그곳에서 다시 로그인 작업을 해야 하는 구현

의도와 다른 구현이 되었기 때문에, 수정하기 전에 "현재 설계 의도는 어떻게 되나요?"라고 출력하게 하여 AI의 해석과 나의 의도의 차이를 확인한 후에 수정을 진행했다.

신규 기능 개발에서는 설계 전후에 반드시 설계 의도를 확인하는 것을 (나만의 운영 규칙으로 삼고 있다).

설계 의도 출력을 거치니 품질이 올라간다고 느끼지만, 이는 이번 환경에서의 체감일 뿐 비교 검증을 거친 결과는 아니다.

AI 코딩에서는 기존의 기술 부채에 더해 새로운 부채가 언급되고 있다.

기술 부채: 설계상의 타협이나 저품질 코드 때문에 미래 수정 비용이 증가하는 상태(@IT, Zenn) -
이해 부채: 코드는 작동하지만, 왜 그렇게 작동하는지 사람이 설명할 수 없는 상태. AI 생성 코드를 충분히 이해하지 못한 채 가져오면 유지보수나 수정 비용이 축적된다(Zenn, @IT) -
인지 부채: AI에게 사고를 너무 의존하여 시스템 전체 설계를 파악하는 능력이 떨어지는 상태(@IT). SO Technologies의 기사에서는 개인이나 팀이 가지고 있어야 할 코드에 대한 이해가 사라져 가는 것을 설명하고 있다. -
의도 부채(意図的負債): 시스템을 어떻게 발전시킬지에 대한 근거, 목표, 제약이 사라져 가는 상태. AI는 '무엇을 만들지'는 출력하지만 '왜 그렇게 만들었는지'는 출력하지 않기 때문에 코드 생성량에 비례하여 쌓인다고 한다. 완화책으로는 중요한 아키텍처상의 결정(ADR)이나 목적을 포착하는 BDD가 언급되고 있다(SO Technologies)

Addy Osmani는 이해 부채를 시스템 내에 존재하는 코드의 양과 사람이 실제로 이해하고 있는 양 사이에서 벌어지는 차이로 설명한다. 코드는 깔끔해 보이고 테스트도 통과하며 개발 속도의 지표도 좋아 보여서, 기술 부채와 달리 알아차리기 어렵다는 특징이 있다.

• 설계서를 끝까지 읽을 수 없는 상태는 이해 부채가 쌓이기 시작하는 입구라고 파악했다.
• 설계 의도 출력은 구현 전에 사람이 의도를 확인하는 수단이며, 이해 부채 및 의도 부채에 대한 예방책으로 위치 지어졌다.
• 설계 의도를 ADR에 남기는 것은 의도 부채 대책으로 제시된 수단과 겹친다.

위의 연결고리는 나 자신의 해석이다. 참고 기사가 설계 의도를 AI에게 출력시키는 방법을 권장하는 것은 아니다.

구현 후 결과 출력은 아직 실시하지 않았다. 향후 검토 사항이다.

생각하고 있는 것: 설계 의도와 구현 결과를 대조하면, 의도대로 구현되었는지 판단할 수 있다 -
검토하고 있는 방법: 구현 후의 결과를 처리 흐름이 파악되는 형태로 HTML로 출력하게 한다. 마크다운보다 슬라이드에 가까운 표현을 할 수 있어 보기 좋게 나올 것이라고 생각한다 -
현재 상태: 가설이며 미검증

설계 의도와 구현 결과의 차이점을 확인하는 운영이 가능하다면, 이해 부채 및 기술 부채를 남기지 않는 것과 연결된다고 생각한다.

이 글은 자신의 인식을 기록하는 메모가 주 목적이지만, 이 장은 마찬가지로 설계 의도를 남기지 않고 진행해 버린 사람에게도 조언이 될 수 있도록 작성했다. 축 1의 출력을 ADR 등에 남겨두었다면, 이런 상황은 일어나기 어려울 것이다.

설계 의도를 출력하지 않은 채 AI와의 대화로 구현을 진행해버렸다. 나중에 "왜 이 설계를 했는지", "여기는 다른 형태로 하는 것이 좋지 않을까"라고 다시 생각하게 된다.

내가 기억하는 당시의 AI와의 대화-
ADR(아키텍처 결정 기록): 나는 당시의 판단과 이유를 ADR에 많이 남기기 때문에, 나중에 "왜 이 설계를 했는지"를 확인할 수 있다.

이것들을 현재 구현과 비교해 보면, "당시 설계와 실제로는 차이가 있다", "여기에 맞추는 것이 좋겠다" 같은 점을 발견할 수 있고, 리팩토링으로 이어질 수 있다.

코드로부터 설계 의도를 역산하는 것도 가능하지만, 거기서 나오는 의도는 추측이다. 당시의 판단 그 자체가 아니라 AI가 나중에 붙인 이유일 수도 있다. ADR이나 기억과 대조하여 사용하는 것이 안전하다.

새 기능 개발 시, 설계 전후에 '설계 의도'(요구사항 해석)를 출력하도록 한다.
출력된 의도를 읽고 자신의 인식과 차이가 없는지 확인한다.
(향후 검토) 구현 후 결과를 출력하게 하여, 설계 의도와의 차이점을 확인한다.
판단 근거는 ADR에 남긴다.
설계 의도를 출력하지 않은 과거의 구현을 재검토할 때는, 기억과 ADR을 단서로 삼는다. 역산한 의도는 추측으로 간주한다.