레포와 GBrain 사이에서 프로젝트 지식을 나누는 기준

AI와 함께 개발 프로젝트를 하다 보면 프로젝트 관련 문서를 작성하고 관리해야 할 필요가 생긴다. 대표적으로 제품 동작을 정의하는 문서가 있는데, 이 문서를 보통 스펙 문서라고 부른다. 이 문서를 담아둘 위치로 처음 떠올리는 곳은 코드가 존재하는 프로젝트 폴더(이를 레파지토리, 줄여서 레포라고 부르겠다)이고, 실제로 많은 개발자들이 여기에 스펙 문서를 담아둔다.

그렇다면 만약 GBrain과 같은 장기 기억 저장소를 내 개인 에이전트에 추가한다면, 프로젝트 스펙 문서는 어디로 가는 게 좋을까? GBrain은 세컨드 브레인을 추구하는 만큼 원한다면 나와 관련된 거의 모든 정보를 담아두고 사용할 수 있다. 실제로 GBrain에서 제안하는 권장 폴더 구조를 보면 projects/ 폴더를 만들 수 있고 projects/<slug> 하위 폴더를 만들어서, 여기에 프로젝트와 관련된 문서나 지식을 담거나 연결할 수 있다.[1] 이렇게 보면 레포와 GBrain 둘 다 프로젝트 정보를 둘 수 있으므로, 스펙과 그 주변 지식을 어느 쪽이 맡아야 하는지 모호하다. 어떻게 이 둘을 구분하고 적절하게 문서를 관리하는 게 좋을지에 대한 내 개인적인 견해를 이야기해보고자 한다.

코드와 함께 바뀌어야 하는 정보는 레포에 둔다

간단한 투두 앱을 예시로 생각해 보자. 기존 스펙에는 체크박스를 누르면 완료한 항목을 바로 삭제한다고 적혀 있다. 이를 “완료한 항목은 목록에 남기고 글자에 취소선을 표시한다”로 바꾸면 데이터 구조, 화면, 테스트도 함께 달라져야 한다. 나중에 완료한 항목만 보는 필터를 만들 때도 완료 상태가 존재한다는 전제에서 구현해야 한다.

여기서 중요한 것은 스펙에 적힌 동작, 코드가 구현한 동작, 테스트가 기대하는 결과가 같은 버전을 설명해야 한다는 점이다. 이 가운데 하나만 오래된 상태로 남으면 AI는 서로 충돌하는 지시를 받는다.

각 자료의 역할은 다르다. 스펙은 제품이 원하는 동작을 말하고, 코드는 그 동작을 구현하며, 테스트는 구현이 요구를 지키는지 확인한다. API 계약, 데이터 규칙, 설정 요구, 검수 조건처럼 제품의 동작을 정하는 내용은 스펙 문서에 정의가 되어 있어야 하고, 코드와 함께 최신 상태를 유지해야 한다.

어떤 문서가 코드 변경과 같은 변경 요청에서 고쳐져야 하고, 특정 커밋이나 릴리스와 내용이 일치해야 한다면 그 문서의 원본은 레포에 두는 편이 낫다. 그러면 한 변경에서 스펙 수정과 구현과 검증을 함께 살펴볼 수 있고, 어느 시점에 원하는 동작이 달라졌는지도 같은 이력에서 확인할 수 있다.

문서 작성 지침과 결정 기록 방식도 이런 배치를 뒷받침한다. Google Cloud는 특정 코드에 적용되는 결정 기록을 관련 코드 가까이, 가능하면 같은 버전 관리 시스템에 두라고 설명한다.[2] GitLab도 사용자 경험, UI, API, 작업 방식이 달라지는 기능 문서를 코드와 같은 변경 요청에 넣거나 비슷한 시기에 합치도록 권한다.[3]

문서를 레포에 둔다고 해서 프로젝트마다 흩어진 문서를 한곳에서 찾을 수 없는 것은 아니다. Backstage TechDocs처럼 코드와 함께 저장한 문서를 중앙 화면에서 찾아 읽게 하는 방식도 있다.[4] 저장 위치와 발견하는 화면은 같을 필요가 없다. 현재 프로젝트가 무엇을 해야 하는지 정하는 원본은 레포에 두되, 다른 시스템이 그 위치를 찾아갈 수 있게 만들면 된다.

프로젝트를 찾고 연결하고 회고하는 맥락은 GBrain에 둔다

GBrain에는 레포의 현재 상태를 그대로 옮기기보다 프로젝트를 오랫동안 이해하는 데 필요한 맥락을 남긴다. projects/<slug> 페이지에는 프로젝트의 목적, 레포 위치, 오래 유지되는 제약, 중요한 전환과 마일스톤, 관련된 사람과 다른 프로젝트를 연결할 수 있다. 한동안 프로젝트를 떠났다가 돌아와도 무엇을 만들고 있었고 원본 자료는 어디에 있는지 찾게 해주는 정보다.

프로젝트에서 얻은 판단 가운데 다른 작업에서도 다시 쓸 만한 내용도 GBrain에 남길 수 있다. 투두 앱 사용자가 완료 기록을 나중에 다시 보고 싶어 한다면, “사용자가 이력을 다시 살펴볼 가능성이 있는 제품에서는 완료를 삭제가 아니라 상태 전환으로 모델링하는 편이 낫다”는 교훈을 얻을 수 있다. 이 판단은 습관 관리 앱이나 작업 기록 도구를 만들 때도 검토할 수 있다.

이때 투두 앱의 요구를 개인의 보편적인 선호로 곧바로 확정해서는 안 된다. 특정 제품에서 한 번 필요했던 동작인지, 여러 프로젝트에서 반복해서 확인한 선호인지 구분해 남겨야 한다. 현재 투두 앱에서 완료 항목을 어떻게 보여줄지는 레포의 스펙이 정하고, 그 경험에서 추출한 조건부 판단은 GBrain의 지식이 된다.

여러 프로젝트의 관계를 연결하는 시스템은 이런 기억을 다시 사용하는 데 도움이 된다. Nalanda 연구는 여러 저장소의 작업 항목, 변경 파일, 사람의 관계를 연결해 관련 작업과 경험자를 찾는 플랫폼을 다뤘다.[5] 다른 연구는 한 작업에서 골라 쓴 개발 지식을 비슷한 새 작업과 연결하면 반복해서 같은 답을 찾는 일을 줄일 수 있다고 설명한다.[6] 두 연구가 저장 위치를 직접 정해 주는 것은 아니지만, 중앙의 지식 시스템이 프로젝트 사이의 관계와 다시 쓸 교훈을 찾는 데 강점이 있다는 점은 보여준다.

같은 정보의 원본을 두 곳에 만들지 않는다

주의해야 할 점은, 레포와 GBrain에 같은 프로젝트 스펙을 각각 원본처럼 저장하면 다음 변경부터 두 기록에 차이가 생길 확률이 높아진다. 투두 앱의 레포 스펙은 완료 항목을 남기도록 바뀌었는데, GBrain에는 “체크하면 항목을 삭제한다”는 이전 스펙이 남을 수 있다는 이야기다.

이후 사용자가 완료한 항목만 보는 필터를 원한다고 하자. AI는 현재 레포의 스펙을 읽고 보존된 완료 상태를 기준으로 필터를 구현하고 테스트해야 한다. 하지만 GBrain의 오래된 스펙까지 같은 권위를 가진 자료로 받으면 삭제 동작을 되살리거나, 완료 항목이 존재하지 않는다는 전제로 데이터를 다시 설계할 수 있다. 같은 스펙을 두 번 저장해 기억이 강해진 것이 아니라 서로 충돌하는 원본이 생긴 것이다.

문제는 같은 내용을 두 곳에서 언급하는 것 자체가 아니다. GBrain에는 프로젝트를 찾기 위한 짧은 요약을 둘 수 있다. 다만 그 요약이 현재 스펙을 대신하지 않는다는 점과 원본 위치를 분명히 해야 한다. 최신 요구나 구현 상태가 필요할 때는 링크를 따라 레포를 다시 읽는다.

레포에는 원본을, GBrain에는 큰 방향성과 교훈을 둔다

정보	원본 위치	이유
현재 제품 동작	레포	코드 버전과 함께 바뀐다.
API 계약과 검수 조건	레포	구현과 테스트가 직접 의존한다.
프로젝트에만 적용되는 설계 결정	레포	해당 코드의 변경 이력과 연결된다.
프로젝트 목적과 레포 위치	GBrain	프로젝트를 다시 찾고 이해하는 데 쓰인다.
중요한 전환과 마일스톤	GBrain	프로젝트의 장기적인 흐름을 보여준다.
여러 프로젝트에서 쓸 선호와 교훈	GBrain	프로젝트 경계를 넘어 다시 쓸 수 있다.
현재 스펙의 짧은 요약	GBrain에 둘 수 있음	원본이 아니라는 표시와 레포 링크가 필요하다.

예를 들어 GBrain의 투두 앱 페이지에는 프로젝트 목적, 레포 주소, 현재 스펙의 경로, “완료 항목 삭제에서 상태 보존으로 전환했다”는 주요 변화, 관련 지식으로 가는 링크를 둘 수 있다. “완료 항목은 목록에 남고 취소선으로 표시되어야 한다”처럼 현재 제품이 지켜야 할 상세 요구는 레포의 스펙에 남긴다.