Factory Droid의 Spec Plan을 홈 디렉토리에서 꺼내는 방법 (2026년 가이드)

Factory의 설정 문서에는 'Spec mode settings'라는 섹션이 있습니다. 여기에는 단 한 줄의 설명과 정확히 하나의 설정만 포함되어 있습니다.

"Spec Mode에 의해 생성되는 영구 스펙 저장소를 제어합니다."

해당 설정은 specSaveDir이며, 참조 테이블의 행에는 다음과 같이 적혀 있습니다.

"저장된 스펙이 기록되는 디렉토리입니다. ~ 확장을 지원합니다."

기본값은 ~/.factory/specs입니다.

분명히 짚고 넘어갈 가치가 있습니다. 영구 스펙 저장소는 존재하며, 이는 문서화된 기능이고, 기본적으로 사용자별 위치로 설정되어 있습니다. 숨겨진 것도 없고 고장 난 것도 아닙니다. 기본값은 단지 팀 아티팩트에 개인용 도구의 기본값이 적용된 것뿐입니다.

이는 단순한 실수가 아니라 일관된 스타일이기도 합니다. 동일한 설정 참조에서, worktree 플래그로 생성된 git worktree의 상위 디렉토리인 worktreeDirectory는 기본적으로 ~/.factory/worktrees로 설정됩니다. Factory는 자체 스캐폴딩을 홈 디렉토리에 배치하는데, 이는 스캐폴딩으로서는 올바른 직관입니다. 하지만 스펙은 스캐폴딩이 아닙니다.

이로 인해 두 가지 문제가 발생하며, 두 번째 문제가 특히 뼈아픕니다.

계획이 공유되지 않습니다. Spec Mode는 계획이 가장 중요한 작업에 정확히 권장됩니다.

"Spec Mode는 구현 전 조사 및 계획을 위한 모드입니다. 아키텍처 변경, 마이그레이션, 보안에 민감한 작업 또는 Droid가 파일을 편집하기 전에 계획을 검토하려는 모든 작업에 사용하세요."

이러한 작업들은 모두 여러 사람이 여러 주에 걸쳐 진행하는 협업입니다. 4단계를 구현하는 사람은 세션을 실행한 사람과 다른 경우가 많지만, 계획은 그들이 읽을 수 있는 곳에 있지 않습니다.

이 모드가 강제하는 경계 역시 인용할 가치가 있습니다. 왜 그 결과물이 보관할 가치가 있을 만큼 신뢰할 수 있는지 설명해 주기 때문입니다.

"Spec Mode 동안 Droid는 파일을 편집하거나, 설정을 변경하거나, 커밋을 생성하거나, 서비스를 시작하거나, 외부 시스템에 기록해서는 안 됩니다. 파일을 읽고, 리포지토리를 검색하고, 연결된 아티팩트를 검사하고, 명확한 질문을 던질 수만 있습니다."

추론 과정이 작업 완료 후 사라집니다. 스펙은 특정 시점(이 코드베이스, 이 제약 조건, 이 옵션 세트)을 기준으로 작성됩니다. 6개월 후 구현이 머지되면 스펙은 아무도 열어보지 않는 홈 디렉토리의 오래된 파일이 됩니다. 그 안의 결정들(예: 리플레이 비용 때문에 이벤트 소싱 방식을 거부했다거나, 마이그레이션을 피하기 위해 추가 테이블을 수용했다는 등)은 여전히 유효하고 중요하지만, 오래된 계획서 내부의 한 단락 외에는 의사결정으로서 기록된 곳이 어디에도 없습니다.

이 두 번째 문제는 사람들이 나중에, 대개 누군가 퇴사할 때 발견하게 되는 문제입니다. 이는 keeping AI context when someone leaves와 동일한 형태의 문제입니다. 지식은 기록되었지만, 개인적인 공간에 기록되었던 것입니다.

유용한 스펙을 리포지토리에 수동으로 복사하기. 작동은 하며, 처음 한두 번은 그렇게 합니다. 하지만 기억해야 하는 경로에 파일이 있고, 작업명이 아닌 세션명으로 이름이 지정되어 있어 번거롭기 때문에 결국 복사를 중단하게 됩니다.

풀 리퀘스트(PR) 본문에 계획 붙여넣기. 검토 가능하고 영구적인 곳에 남기 때문에 더 나은 방법입니다. 하지만 PR 설명은 단일 diff로 범위가 제한되므로, 4개의 PR에 걸쳐 있는 스펙은 4개의 설명으로 파편화되어 각각 다른 부분에 중요한 내용을 놓치게 됩니다.

티켓에 계획 넣기. 일장일단이 있습니다. 이제 계획이 팀에 공개되고 종료되는 작업 항목과 연결됩니다. 하지만 닫힌 티켓은 테이블이 존재하는 이유를 찾기 위해 검색하는 곳이 아닙니다.

스펙을 AGENTS.md 섹션으로 변환하기. 이는 두 가지 종류의 콘텐츠를 혼동하는 것입니다. AGENTS.md는 매 세션마다 읽는 상시 지침을 담고 있으며, 스펙은 일회성 계획입니다. 이 둘을 병합하면 지난 3월에 끝난 작업을 설명하는 항상 로드되는 긴 파일이 생성됩니다.

기본값을 그대로 두고 세션 트랜스크립트에 의존하기. 가장 취약한 옵션입니다. Droid의 자체 문서에서도 하위 에이전트 및 세션 동작이 세션에 의해 제한된다고 설명하고 있으며, 트랜스크립트는 문서라기보다는 로그에 가깝기 때문입니다. Spec Mode의 핵심은 트랜스크립트보다 더 나은 결과물을 만들어내는 데 있습니다.

모든 스펙을 영구적으로 커밋하기. 과도한 교정입니다. 아무 생각 없이 저장소를 리포지토리로 지정하면, 이미 변경된 구현을 제안하는 수십 개의 오래된 계획 파일이 생겨나 실제 문서와 독자의 주의를 끌기 위해 경쟁하게 되고, 에이전트의 주의를 끌기 위해 실제 지침 파일과 경쟁하게 됩니다.

이 여섯 가지 패턴의 공통점은 사람들이 스펙을 개인용 임시 파일이나 영구 문서 중 하나로 취급한다는 점인데, 스펙은 둘 다 아닙니다. 스펙은 몇 가지 영구적인 사실을 담고 있는 임시 아티팩트입니다. 해결책은 이 두 가지 측면을 모두 처리해야 합니다.

세 단계로 진행됩니다. 첫 번째는 한 줄의 변경이고, 두 번째는 무엇을 커밋할지 결정하는 것이며, 세 번째는 이를 고착화하는 방법입니다.

1단계: specSaveDir을 프로젝트로 지정하기

프로젝트의 Factory 설정에서 specSaveDir을 홈 디렉토리 기본값 대신 리포지토리 내부의 디렉토리로 설정하세요. Factory는 사용자 수준의 ~/.factory/settings.json과 프로젝트의 .factory/ 폴더에서 설정을 읽으므로, 이 설정은 프로젝트 파일에 넣어야 합니다. 스펙 위치는 로컬 장비가 아닌 프로젝트의 속성이기 때문입니다.

설정을 신뢰하기 전에 첫 실행 시 경로가 예상대로 확인되는지 확인하세요. 이 설정에 대한 문서화된 참고 사항은 ~ 확장을 지원한다는 것이므로, 가정하기보다는 선택한 경로 스타일에 따른 동작을 확인하는 것이 좋습니다.

이 파일을 수정하는 동안 알아두면 좋은 두 가지 관련 설정이 있습니다. 첫 번째는 sessionDefaultSettings.interactionMode로, 문서화된 역할은 다음과 같습니다.

"새 세션이 Auto 모드 또는 Spec Mode 중 어느 것으로 시작할지 설정합니다."

계획 수립을 기본 태세로 삼고자 하는 리포지토리에서는 이를 spec으로 설정하는 것이 유용합니다. 두 번째는 specModeModel로, 참조 문서에서는 세션이 Spec Mode로 시작할 때 사용되는 모델을 오버라이드하는 것으로 설명합니다. 계획 수립과 구현은 서로 다른 모델이 유리하므로 설정할 가치가 있습니다. 또한 .droid.yaml은 이전 구성 방식으로 문서화되어 있으므로 .factory/ 파일을 사용하세요.

2단계: 커밋할 것과 무시할 것 결정하기

이제 스펙이 리포지토리에 저장되므로 신중하게 결정해야 합니다. '모두 커밋'이라는 기본 답변은 위에서 언급한 과도한 교정이기 때문입니다.

유용한 구분 기준은 수명(lifespan)입니다.

진행 중인 작업에 대한 스펙은 커밋해야 합니다. 이는 공유된 계획이며, 두 번째 PR의 리뷰어에게 필요하기 때문입니다. 배포가 완료된 작업에 대한 스펙은 목적을 다한 것이므로, 이를 그대로 두면 누군가 더 이상 시스템을 설명하지 못하는 계획을 읽게 만들 뿐입니다.

Factory는 장비별 설정을 위한 메커니즘을 제공합니다. 임의의 .factory/ 폴더에서 settings.json과 함께 settings.local.json을 생성할 수 있으며, 문서화된 동작은 다음과 같습니다.

"로컬 오버라이드는 동일한 수준의 해당 settings.json 위에 병합되며 동일한 계층 구조 우선순위를 따릅니다. 장비별 개인 설정을 버전 관리에서 제외하려면 settings.local.json을 .gitignore에 추가하세요."

사용자 정의 설정에는 이를 사용하고, 공유 스펙 경로를 유지하는 공유 settings.json을 유지하세요.

3단계: 계획을 아카이브하기 전에 의사결정 추출하기

이 단계가 결과를 바꾸는 단계이며, 스펙당 약 2분 정도 소요됩니다.

스펙의 작업이 머지되면 계획을 마지막으로 한 번 더 읽고 내년에도 여전히 유효할 문장들을 추출하세요. 구현 단계가 아닙니다. 그것들은 이제 코드에 있습니다. 고려된 사항, 거부된 사항, 그리고 그 이유와 같은 의사결정들입니다. 스펙에는 일반적으로 순차적인 설명을 담은 20개의 단락 사이에 이러한 내용이 서너 개 정도 묻혀 있습니다.

이 서너 개의 문장이 해당 문서의 지속적인 가치 전부입니다. 이를 계획 파일이 아닌 다른 곳에 기록해 두면, 아무것도 잃지 않고 계획 파일을 아카이브하거나 삭제할 수 있습니다. 이 단계를 건너뛰면 그 안에 무엇이 들어있는지 두려워 오래된 스펙을 영원히 보관하게 되며, 이는 사람들이 AI에게 re-explain context to AI를 반복하게 만드는 전형적인 정보 사재기 문제입니다.

MemoryLake는 추출된 의사결정이 보관되는 곳입니다. 리포지토리 외부 및 특정 에이전트 외부에 위치하며, MCP 또는 API를 통해 프로젝트의 의사결정에 대한 질문에 답변합니다. 따라서 계획 파일이 사라진 후에도 어떤 도구에서든 질문하는 누구에게나 스펙의 추론 결과를 제공할 수 있습니다. 스펙은 Factory가 기록하는 프로젝트 디렉토리에 그대로 유지되며, 공유 레이어는 보관할 가치가 있는 네 문장을 보유합니다.

1단계: API 키 생성하기

키를 생성하고 약 30초 만에 첫 번째 요청을 보내보세요. 위의 3단계를 진행하기 전에 이 작업을 수행하여 계획을 읽으면서 각 의사결정을 저장할 공간을 마련해 두세요.

2단계: 첫 번째 메모리 업로드하기

홈 디렉토리에 여전히 남아 있는 스펙을 포함하여 기존 스펙을 검토하고, 선택된 사항, 거부된 사항, 그 이유와 함께 실제 의사결정을 각각 기록하세요. 지원 문서와 파일도 같은 위치에 저장됩니다. turning project docs into AI memory에서 재작성 없이 대량으로 이를 수행하는 방법을 다룹니다.

3단계: AI 및 에이전트 연결하기

Droid, Claude, Codex 및 기타 에이전트에 MCP 또는 API를 통한 액세스 권한을 부여하세요. 다음 Spec Mode 세션은 이전 5개 세션에서 결정된 사항을 이미 알고 시작하므로, 이는 단순한 계획 수립과 재계획 수립의 차이를 만들어냅니다.

첫 번째 변화는 계획이 영향을 받는 사람들에 의해 검토 가능하다는 점입니다. 계획은 리포지토리의 브랜치, diff에 존재합니다. 4단계를 구현하는 사람은 누구에게도 파일을 요청하지 않고 이를 읽을 수 있습니다.

두 번째는 Spec Mode가 더 나은 입력을 받는다는 점입니다. Droid는 계획을 제안하기 전에 리포지토리를 조사하므로, 최근 몇 개의 계획과 과거 의사결정의 쿼리 가능한 기록이 포함된 리포지토리는 둘 다 없는 리포지토리보다 더 많은 정보를 제공합니다.

세 번째는 스펙이 계속 쌓이지 않는다는 점입니다. 지속적인 가치가 있는 콘텐츠를 추출하고 나면 배포된 계획을 자유롭게 삭제할 수 있으며, 진행 중인 계획 디렉토리는 사람들이 읽을 수 있을 만큼 작게 유지됩니다.

네 번째는 계획이 노트북보다 오래 살아남는다는 점입니다. 홈 디렉토리 경로는 장비별로 다르며, 이는 Claude Code forgetting things across machines의 이면에 있는 비대칭성과 동일합니다. 동일한 해결책이 적용됩니다. 공유할 대상을 단일 장비가 아닌 리포지토리나 공유 서비스가 보관하는 곳에 두는 것입니다.

다섯 번째는 인수인계가 짧아진다는 점입니다. sharing context between sessions이 해결하려는 문제의 절반은 다른 누구도 볼 수 없는 문서에서 이미 신중하게 한 번 내려진 결정을 누군가가 다시 도출하는 상황을 방지하는 것입니다.

사용자 설정이 아닌 프로젝트 설정에서 specSaveDir을 설정하세요. 스펙이 저장되는 위치는 프로젝트의 속성입니다. 사용자 수준 설정은 다음에 열 리포지토리에서는 유효하지 않은 경로를 가리킬 수 있습니다.

첫 실행 시 경로를 확인하세요. 이 설정에 대한 문서화된 참고 사항은 ~ 확장과 관련이 있습니다. 이를 신뢰하기 전에 실제로 어떤 경로가 생성되는지 확인하세요.

진행 중인 스펙은 커밋하고, 배포된 스펙은 폐기하세요. 머지된 작업에 대한 계획은 이미 변경된 시스템에 대한 설명일 뿐입니다.

아카이브하기 전에 의사결정을 추출하세요. 스펙당 서너 문장이면 충분합니다. 이것이 핵심 작업이며, 이를 통해 안전하게 삭제할 수 있게 됩니다.

지침 파일에 스펙을 포함하지 마세요. AGENTS.md는 매 세션마다 로드됩니다. 완료된 계획은 매 세션에 포함될 필요가 없습니다.

장비별 개인 설정에는 settings.local.json을 사용하세요. 이는 동일한 수준의 공유 파일 위에 병합되며 gitignore되도록 설계되어 있어, 공유 스펙 경로를 공유 상태로 유지할 수 있습니다.

리포지토리의 기본값을 Spec Mode로 설정하는 것을 고려해 보세요. 상호작용 모드를 spec으로 설정하면 계획 수립이 필요한 작업에서 이를 기본 태세로 만들 수 있습니다.

.droid.yaml에서 마이그레이션하세요. 이는 이전 구성 방식으로 문서화되어 있으며, 현재는 .factory/ 파일이 표준입니다.

Factory는 단일 설정인 specSaveDir에 의해 제어되는 영구 스펙 저장소를 문서화하고 있으며, 이는 기본적으로 홈 폴더의 디렉토리로 설정되어 있습니다. Spec Mode 자체는 리포지토리를 조사하고 사람의 승인을 받기 위해 멈추는 읽기 전용 계획 수립 모드로, 아키텍처 변경, 마이그레이션 및 보안에 민감한 작업에 권장됩니다. 이 두 가지 사실을 종합해 보면, 기본 설정은 팀의 가장 신중하게 추론된 문서를 팀원들이 볼 수 없는 유일한 장소에 기록하고 있는 셈입니다.

경로를 변경하는 것은 한 줄이면 충분합니다. 실제로 효과를 보는 부분은 그 이후의 습관입니다. 진행 중인 작업을 설명하는 계획은 커밋하고, 이미 배포된 작업을 설명하는 계획은 폐기하며, 폐기하기 전에 내년에도 여전히 중요할 서너 개의 의사결정을 추출하는 것입니다. 그렇게 하면 Spec Mode는 서류상에 명시된 그대로의 모습, 즉 단 하나의 노트북이 아닌 팀 전체가 유지하는 훌륭한 의사결정을 생산하는 기계가 될 것입니다.