폴더 이름은 프로젝트의 정체성이 아닙니다
폴더 경로는 하나의 경로(route)입니다. 도구에게 프로젝트가 현재 어디에 있는지 알려주는 역할을 합니다. 프로젝트의 정체성(identity)은 이와 다릅니다.
정체성은 다음과 같은 일반적인 변화 속에서도 유지되어야 합니다:
- 디렉토리 이름 변경
- 머신 간 프로젝트 이동
- 새로운 경로로 레포지토리 클론
- 동일한 프로젝트의 여러 체크아웃 사용
만약 정체성이 경로에 의존한다면, 이러한 작업들은 위험해집니다. 경로는 작동할지 모르지만, 프로젝트가 동일하다는 것을 증명하지 못합니다. 이는 상태(state)를 저장하기 위한 키(key)로서 부적절하게 만듭니다.
저는 이 문제를 해결하기 위해 APC와 APX를 활용한 분리형 설계를 사용합니다.
APC는 프로젝트 계약(contract)을 담당하며, 레포지토리 내에 존재합니다. APX는 런타임 상태(runtime state)를 담당하며, 레포지토리 외부에 존재합니다.
APC는 안정적인 앵커(anchor)를 만들기 위해 특정 파일들을 사용합니다:
- AGENTS.md: 루트 계약용
- .apc/project.json: 프로젝트 메타데이터용
- .apc/agents/*.md: 에이전트 정의용
- .apc/mcps.json: MCP 힌트용
.apc/project.json 파일은 매우 작습니다. 여기에는 이름과 안정적인 ID가 포함되어 있습니다. 이는 대규모 설정 파일이 아니라 하나의 마커(marker) 역할을 합니다.
APX는 이 파일을 사용하여 라이브 체크아웃을 영구적인 기록과 연결합니다. 경로는 APX가 프로젝트를 찾는 것을 돕고, 메타데이터는 APX가 프로젝트를 찾은 후 이를 안정적으로 유지하도록 돕습니다.
이 설계는 레포지토리를 깔끔하게 유지합니다. 세션 로그나 메시지 기록과 같은 런타임 데이터는 APX 저장소에 머무릅니다. 따라서 git 히스토리를 어지럽히지 않습니다.
경로에 의존하면 다음과 같은 문제에 직면하게 됩니다:
- 경로 변경
- 상태 깨짐
- 도구의 잘못된 추측
- 개발 대신 이름 디버깅에 시간 낭비
안정적인 정체성은 이러한 노이즈를 제거합니다. 코드 리뷰를 더 쉽게 만들어 줍니다. 디프(diff)에서 우연히 발생한 런타임 출력 대신 프로젝트의 실제 사실을 확인할 수 있습니다.
경계는 간단합니다:
- AGENTS.md: 프로젝트가 기대하는 것
- .apc/project.json: 프로젝트의 본질
- ~/.apx/: 작업 중에 발생한 일
프로젝트에는 하나의 안정적인 앵커가 필요합니다. 폴더 경로는 너무 가변적이고, 런타임은 너무 노이즈가 많습니다. 레포지토리 계약과 메타데이터 파일의 조합이 가장 적절한 규모입니다.
Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca
Optional learning community: https://t.me/GyaanSetuAi