프로젝트끼리 비교하며 설계를 배우는 법

원칙이 다른 프로젝트를 함께 운영한 이유

올해 25개 파일럿 프로젝트를 진행했다. 모델이 바뀔 때마다 같은 지시를 받아들이는 방식이 달라져서, 이전 모델에 맞춰 둔 프롬프트와 하네스 설정을 다시 조정해야 했다. 작업 요령은 그렇게 그때그때 고치면 된다. 그와 별개로 다음 프로젝트에도 가져갈 수 있는 판단 기준을 쌓고 싶었다.

그래서 프로젝트마다 다른 개발 원칙을 선언하고, 모델과 도구가 바뀌어도 그 원칙은 유지하면서 결과의 차이를 관찰했다. 빠르게 구현한 뒤 구조를 다듬는 프로젝트, 상세한 명세와 규칙을 먼저 세우는 프로젝트, 높은 품질 기준을 통과해야 머지하는 프로젝트를 함께 개발하는 식이다.

차이가 쌓이자 한 프로젝트에서 막힌 문제를 다른 프로젝트와 비교하며 풀 수 있었다. 이 글은 그 방법을 교차 설계 리뷰로 정리한다. 문제를 먼저 해결한 프로젝트를 참조 기준으로 삼고, 현재 프로젝트와의 차이에서 개선 가설을 찾아 현재 조건에서 검증한 뒤, 그 판단을 기록하는 절차다.

개발 원칙을 비교 가능한 정책으로

프로젝트의 컨셉은 개발자의 취향에 머물면 비교하기 어렵다. 무엇을 우선하고, 어떤 방식으로 결정하며, 그 대가로 어떤 비용을 관찰할지 적어야 한다.

이 셋은 서로 배타적인 아키텍처 유형이 아니다. A도 보안 기준을 지켜야 하고 C도 빠르게 실험할 수 있다. 다른 점은 선택이 충돌할 때 무엇을 먼저 고르느냐다. 그래서 모든 프로젝트에 필요한 최소 기준을 먼저 정하고 그 위에서 우선순위를 달리한다.

정책에는 관찰할 질문도 붙인다. A에서는 빠른 첫 구현이 이후 재작업을 얼마나 만들었는지, B에서는 명세가 변경 범위를 예측하는 데 도움이 됐는지, C에서는 검증 때문에 늦어진 시간에 비해 어떤 결함을 일찍 발견했는지 살펴볼 수 있다. 앞으로 비교할 항목의 예시일 뿐, 세 정책의 성과를 수치로 검증했다는 뜻은 아니다.

질문은 "어느 프로젝트가 가장 잘 만들어졌는가"보다 구체적이어야 한다. 어떤 조건에서 이 정책의 이득이 비용보다 컸는가. 그래야 다른 프로젝트에 적용할 때도 판단 기준이 남는다.

참조 프로젝트를 리뷰 기준으로 쓰기

프로젝트를 비교하는 방식은 리뷰를 요청할 때 특히 유용했다. 보안 검증을 마친 프로젝트 A가 있다면 다음처럼 요청할 수 있다.

프로젝트 A 기준으로 지금 프로젝트의 보안 영역을 리뷰해 줘.

이미 내가 잘 아는 구조와 용어를 기준으로 결과가 나오면, 긴 설명 없이도 차이를 이해하고 다음 지시를 내리기 쉽다. 참조 프로젝트에는 원칙을 구현한 코드와 테스트, 예외 처리 방식이 함께 들어 있기 때문이다.

다만 "A 기준"의 범위는 명시해야 한다. A가 검증을 받았다고 해서 현재 프로젝트까지 안전하다는 보장은 없다. 다루는 데이터, 사용자 권한, 배포 환경이 다르면 필요한 검증도 달라진다. 에이전트가 참조 프로젝트를 기억한다고 가정하지 말고 비교할 코드와 문서에 접근할 수 있게 열어 둔다.

실제 요청은 다음과 같이 좁힐 수 있다.

참조 프로젝트: A의 지정 커밋과 보안 리뷰 기록
검토 대상: 현재 프로젝트의 인증·인가 경계

1. A의 권한 검증 위치, 거절 조건, 관련 테스트를 확인해 줘.
2. 현재 프로젝트의 대응 코드와 비교하고 파일 경로를 근거로 제시해 줘.
3. 사용자 역할과 데이터 접근 방식이 달라 직접 적용할 수 없는 부분을 구분해 줘.
4. 적용 가능한 개선마다 변경 이유와 검증 방법을 제안해 줘.
5. 확인할 수 없는 항목은 추정으로 채우지 말고 남겨 줘.

프로젝트 전체를 참조하되, 리뷰할 경계와 근거의 범위를 지정한다.

리뷰 결과는 "A와 다르다"에서 끝나면 안 된다. 왜 그 차이가 현재 프로젝트에서 문제인지 설명할 수 있어야 한다. 차이가 합리적인 요구사항에서 나왔다면 유지하는 것이 맞다.

교차 설계 리뷰 절차

이 경험을 반복 가능한 작업으로 만들려면 비교에서 검증까지 연결해야 한다.

1. 문제를 좁힌다. "전체 품질을 높인다" 대신 순환 참조, 권한 검증 누락, 특정 작업의 지연처럼 관찰 가능한 문제를 고른다.
2. 참조 프로젝트를 고른다. 해당 문제를 해결한 근거가 있고, 관련 요구사항이 비교 가능한 프로젝트를 선택한다. 참조할 커밋이나 문서 버전도 남긴다.
3. 차이에서 가설을 만든다. 코드·계약·검증 절차를 비교하고 어떤 차이가 문제에 영향을 줄 수 있는지 설명한다. 관찰한 사실과 추정은 구분한다.
4. 적용 조건을 확인한다. 규모, 데이터, 실행 환경, 책임 경계가 달라도 같은 원칙이 유효한지 검토한다.
5. 작게 적용하고 검증한다. 가설에 필요한 범위만 변경한다. 처음의 문제가 개선됐는지와 기존 계약이 유지되는지를 확인한다.
6. 판단을 기록한다. 참조 근거, 채택하거나 거절한 이유, 검증 결과, 다시 검토할 조건을 남긴다.

예를 들어 린트 성능이 문제였다면 같은 실행 환경과 검사 범위에서 변경 전후를 비교해야 한다. 검사를 빼서 빨라진 것인지, 필요한 검사를 유지하며 개선한 것인지도 구분한다. 순환 참조를 끊었다면 관련 동작과 모듈 계약이 유지되는지 함께 확인한다.

이렇게 남긴 기록은 다음 리뷰의 출발점이 된다. "A가 좋다"는 평가 대신 "이 조건에서는 이 규칙을 적용했고, 이 검증으로 결과를 확인했다"는 근거를 전달할 수 있다.

OCLS 루프와의 연결

reopt architecture의 OCLS 루프에 연결하면, 교차 설계 리뷰는 SHARPEN에서 얻은 피드백을 다른 프로젝트의 설계 판단에 사용하는 방법이다.

모듈 계약은 비교할 경계를 분명하게 하고, 평가와 가드레일은 개선을 확인할 기준을 제공한다. 의사결정 추적성은 그 기준을 왜 가져왔는지 남기는 데 쓰인다.

한 프로젝트의 개선이 다른 프로젝트에 그대로 정답이 되지는 않는다. 참조 프로젝트에서 발견한 규칙을 현재 프로젝트의 책임과 계약에 대어 보고 적용한 결과를 다시 평가하면서 학습이 이어진다.

비교의 한계

여러 프로젝트를 같은 시기에 개발하면 서로 다른 시점의 모델과 도구를 비교하는 문제를 줄일 수 있다. 하지만 동시에 개발한다고 변수까지 통제되지는 않는다. 모델과 하네스 설정이 같은지 확인해야 한다. 같더라도 컨텍스트와 작업 난이도에 따라 결과가 달라질 수 있다.

프로젝트의 도메인, 규모, 성숙도와 내가 쏟은 시간도 다르다. 이 방법은 엄밀한 통제 실험이라기보다 설계 가설을 찾고 검증하는 실무 방식에 가깝다. 비교 기록에 이런 차이를 남겨야 우연한 성공을 보편적인 규칙으로 받아들이는 일을 줄일 수 있다.

학습을 위해 프로젝트 수부터 늘릴 필요도 없다. 이미 운영하는 두 프로젝트에서 같은 종류의 변경을 비교하는 것으로 시작할 수 있다. 유지비가 학습의 이득보다 커지면 비교 범위를 줄이는 편이 낫다.

다음 프로젝트에 가져갈 것

프롬프트와 하네스 설정은 모델이 바뀔 때마다 다시 맞춰야 했다. 교차 설계 리뷰로 남긴 기록은 성격이 다르다. 어떤 조건에서 어떤 규칙을 적용했고, 무엇으로 결과를 확인했으며, 어떤 경우에 적용을 거절했는지는 모델과 도구가 바뀐 뒤에도 다시 검토하고 활용할 수 있다.

그래서 다음 프로젝트에 가져갈 것은 잘된 프로젝트의 코드 모양보다 그 판단의 근거다. 원칙이 다른 프로젝트 사이에서 드러난 테스트, 보안, 기능 추가 속도, UX의 차이가 다음 설계 질문을 만들고, 그 질문을 검증한 기록이 다시 다음 리뷰의 참조 기준이 된다.