코드베이스에 헌법을 부여하세요

사람들의 머릿속에만 존재하는 아키텍처는 에이전트(Agents) 시대에 살아남을 수 없습니다.

제 커리어의 대부분 동안, 코드베이스의 실제 규칙들은 문서화되어 있지 않았습니다.

사람들은 그것들을 알고 있었습니다.

시니어 엔지니어들은 어떤 레이어(Layer)가 어떤 레이어와 통신할 수 있는지 알고 있었습니다. 어떤 의존성(Dependencies)이 금지되어 있는지, 어떤 스키마(Schemas)가 사실상 고정되어 있는지, 그리고 어떤 지름길이 6개월 후에 문제를 일으킬지를 알고 있었습니다. 신입 엔지니어들은 전통적인 방식으로 그 규칙들을 배웠습니다. 하나를 어기고, 리뷰 과정에서 지적을 받고, 설명을 들은 뒤, 결국 다시는 그러지 말아야겠다는 것을 기억하는 방식 말입니다.

완벽하지는 않았지만, 대체로 잘 작동했습니다.

코딩 에이전트(Coding agents)와 본격적으로 작업하기 전까지 제가 완전히 깨닫지 못했던 점은, 그 모델이 부족주의적 지식(Tribal knowledge)에 얼마나 의존하고 있는가 하는 점이었습니다. 인간은 시간이 지나면서 맥락(Context)을 축적합니다. 에이전트는 그렇지 않습니다.

에이전트들은 3년 전에 잘못되었던 마이그레이션(Migration)을 기억하지 못합니다. 팀이 의존성 사이클(Dependency cycle)을 해결하기 위해 몇 주를 보낼 때 그들은 그 자리에 없었습니다. 특정 경계(Boundary)가 왜 존재하는지도 모릅니다.

그들은 오직 볼 수 있는 것만 압니다.

즉, 규칙이 문서로 작성되어 있지 않다면, 에이전트의 관점에서는 그 규칙이 존재하지 않는다는 뜻입니다.

저는 에이전트들이 내부 레이어를 외부 레이어에 직접 연결하는 것을 보았습니다. 우리가 의도적으로 피했던 의존성을 도입하거나, 팀원 모두가 확정되었다고 간주한 컨트랙트(Contracts)를 확장하는 것도 보았습니다. 코드는 종종 제대로 작동했는데, 바로 그 점이 위험했습니다.

문제는 정확성(Correctness)이 아니었습니다.

문제는 아키텍처 드리프트(Architectural drift)였습니다.

그때 무언가 깨달음이 왔습니다.

에이전트가 코드를 작성하기 시작하면, 아키텍처는 더 이상 민간 전승(Folklore)으로 남아있을 수 없습니다.

그것은 법(Law)이 되어야 합니다.

관례(Convention)가 아닙니다. 제안(Suggestion)도 아닙니다. 금요일 오후 6시에 리뷰어가 떠올리는 무언가도 아닙니다.

법이어야 합니다.

문서화되어 있고, 명시적이며, 강제할 수 있어야 합니다.

그것이 제가 헌법(Constitution)이라고 말하는 의미입니다.

헌법은 문서화(Documentation)가 아닙니다

제가 저지른 첫 번째 실수는 헌법을 또 다른 문서화 파일처럼 취급한 것이었습니다.

그것은 문서화가 아닙니다.

문서화 (Documentation)는 시스템이 현재 어떻게 작동하는지를 설명합니다. 헌법 (Constitution)은 시스템이 무엇이 될 수 있는지를 정의합니다. 이 둘은 비슷하게 들릴 수 있지만, 매우 다른 목적을 수행합니다.

패키지 이름은 변경됩니다. 디렉터리는 이동합니다. 프레임워크는 교체됩니다. 구현 (Implementations)은 나타났다 사라지기를 반복합니다.

이 중 그 어떤 것도 헌법에 포함되어서는 안 됩니다.

헌법에는 대규모 리팩터링 (Refactor) 후에도 살아남아야 하는 것들, 즉 법률, 불변량 (Invariants), 그리고 시스템의 형태를 정의하는 경계 (Boundaries)만을 포함해야 합니다.

유용한 테스트 방법은 간단합니다. 만약 어떤 문장이 다음 분기에 거짓이 될 수 있고 아무도 신경 쓰지 않는다면, 그것은 아마도 헌법에 포함되어서는 안 되는 것입니다.

그것은 문서화입니다.

법이 아닙니다.

제가 본 최고의 헌법들은 세 가지 속성을 공유합니다. 그것들은 짧고, 제한적이며, 변경 속도가 느립니다.

짧은 이유는 아무도 50페이지짜리 헌법을 읽지 않기 때문입니다.

제한적인 이유는 아무것도 금지하지 않는 법은 아무것도 보호하지 못하기 때문입니다.

변경 속도가 느린 이유는 사람들이 법을 신뢰할 수 있을 때에만 법이 신뢰를 형성하기 때문입니다.

내 헌법에 포함된 것들

저는 구조를 미리 설계하지 않았습니다.

대부분의 내용은 리뷰 (Reviews) 과정에서 동일한 아키텍처 (Architecture) 규칙을 반복해서 설명하면서 만들어졌습니다. 열 번째 설명을 한 뒤에, 저는 설명을 멈추고 쓰기 시작했습니다.

첫 번째 섹션에는 몇 가지 원칙이 포함되어 있습니다. 아주 적습니다. 기껏해야 다섯 개나 여섯 개 정도입니다.

예를 들면 다음과 같습니다:

• 의존성 방향 (Dependency direction)은 단방향이다
• 계약 (Contracts)은 구현 (Implementations)보다 먼저 정의된다
• 내부 레이어 (Inner layers)는 외부 레이어 (Outer layers)를 알아서는 안 된다

이것들은 구현 세부 사항 (Implementation details)이 아닙니다.

이것들은 근본적인 가정 (Foundational assumptions)입니다.

만약 이 중 하나라도 바뀐다면, 당신은 아키텍처를 수정하는 것이 아니라 재정의 (Redefining)하고 있는 것입니다.

두 번째 섹션은 레이어 (Layers)와 그 레이어에 허용된 의존성 (Dependencies)을 정의합니다. 한 가지 규칙이 놀라울 정도로 중요하다는 것이 밝혀졌습니다:

레이어 멤버십 (Layer membership)은 디렉터리가 아니라 역할 (Role)에 의해 결정된다.

디렉터리는 항상 변경됩니다. 역할은 그렇지 않습니다.

네트워크 리스너 (Network listener)를 여는 모듈은 누군가 내일 그것을 옮기더라도 여전히 엔트리 포인트 (Entry point)입니다. 도메인 모델 (Domain model)은 그것이 어느 폴더에 있든 상관없이 여전히 도메인 모델입니다.

아키텍처를 디렉터리에 결합하는 것은 그것을 취약하게 만듭니다.

아키텍처를 책임 (Responsibilities)에 결합하는 것은 그것을 내구성 있게 만듭니다.

모든 법률에는 이유가 따릅니다.

이것은 제가 예상했던 것보다 더 중요하다는 것이 밝혀졌습니다. 근거 (Rationale)가 없는 규칙은 결국 그것이 왜 존재하는지 이해하지 못하는 누군가에 의해 삭제됩니다. 규칙은 행동을 가르칩니다. 근거는 판단력을 가르칩니다.

당신은 둘 다 필요합니다.

실제로 작동하게 만드는 부분

위의 모든 것들이 도움이 됩니다.

하지만 그 중 어느 것도 충분하지는 않습니다.

에이전트 (Agents)와 함께 일하며 배운 가장 큰 교훈은, 다양한 형태로 계속해서 다시 배우게 되는 것입니다:

지침 (Instructions)은 가이드라인입니다. 강제 (Enforcement)가 현실입니다.

시스템이 이미 확인했습니다.

그것이 바로 해답(unlock)입니다.

헌법은 자율성 (autonomy)을 제한하는 것이 아닙니다.

자율성을 가능하게 만드는 것입니다.

중요한 경계 (boundaries)가 보장되면, 나머지 모든 것을 안전하게 위임할 수 있기 때문입니다.

온보딩 (onboarding)에서도 동일한 일이 일어납니다.

새로운 엔지니어들은 더 이상 수개월간의 암묵적 지식 (tribal knowledge)을 습득할 필요가 없습니다. 에이전트 (agents)는 더 이상 끝없는 프롬프트 엔지니어링 (prompt engineering)을 필요로 하지 않습니다. 모두가 동일한 법률 세트에서 시작하며, 기계가 이를 평등하게 강제 (enforce)합니다.

지식은 더 이상 근속 연수에 의해 독점되지 않습니다.

시작하는 방법

50개의 법을 쓰는 것부터 시작하지 마세요.

주의를 기울이는 것부터 시작하세요.

당신이 다음과 같이 말하는 것을 들을 때마다:

"우리는 ... 때문에 그렇게 하지 않습니다."

당신은 아마도 법률의 후보를 발견한 것입니다.

에이전트가 당신을 불편하게 만드는 변경을 수행할 때마다, 왜 그런지 스스로에게 물어보세요. 대부분의 경우, 당신의 머릿속에는 존재하지만 다른 곳에는 존재하지 않는 경계를 발견한 것입니다.

위반했을 때 진정으로 타격이 큰 몇 가지 규칙부터 시작하세요:

• 의존성 방향 (Dependency direction)
• 비밀 정보 처리 (Secret handling)
• 핵심 계약 (Critical contracts)
• 경계 소유권 (Boundary ownership)

규칙을 작성하세요.

이유를 작성하세요.

그런 다음, 이를 무시하는 것이 불가능하게 만드는 체크 (check)를 추가하세요.

왜냐하면 그것이 사람들이 보통 건너뛰는 부분이기 때문입니다.

강제 (enforcement)가 없는 법은 제안에 불과합니다.

강제가 없는 헌법은 문서화 (documentation)에 불과합니다.

그리고 오직 사람들의 머릿속에만 존재하는 아키텍처 (architecture)는 에이전트 시대에서 살아남지 못합니다.

코드베이스에 헌법을 부여하세요.

그다음, 그 헌법에 힘 (teeth)을 실어주세요.