타임아웃으로 누락되기 전에 OpenCode의 원격 지침 파일을 로컬에 미러링하는 방법 (2026년 가이드)

OpenCode는 AGENTS.md 파일과 opencode.json 또는 글로벌 설정에 지정한 목록에서 커스텀 지침을 읽습니다. 이 목록은 일반 경로, glob, URL을 허용하며, 문서화된 동작은 "모든 지침 파일이 AGENTS.md 파일과 결합된다"는 것입니다.

여기서 핵심 단어는 '결합'입니다. 시작할 때 병합된 하나의 지침 본문이 생성되며, 대화 중에는 어떤 항목이 기여했는지 표시되지 않습니다. 정상적으로 도달한 파일과 타임아웃된 파일은 겉보기에 동일한 세션을 생성합니다. 에이전트는 지침을 따르고 있지만, 단지 모든 지침을 따르고 있지 않을 뿐입니다.

이를 로컬 항목의 동작 방식과 비교해 보세요. 목록의 경로는 디스크에서 확인되거나 확인되지 않으며, 디스크 조회는 5초나 걸리지 않습니다. glob은 파일과 일치하거나 아무것도 일치하지 않습니다. 이러한 실패는 일관적입니다. 오늘 잘못되었다면 내일도 잘못된 것이므로, 한 번 발견해서 한 번에 해결할 수 있는 종류의 실패입니다.

반면 원격 항목은 간헐적으로 실패합니다. 사무실 책상에서는 작동하지만 기차 안에서는 작동하지 않습니다. 본인에게는 작동하지만 더 느린 프록시 뒤에 있는 동료에게는 작동하지 않습니다. 지침의 간헐적 누락은 이 문제의 가장 최악의 형태입니다. 에이전트가 규칙을 무시할 때 사람들이 하는 행동은 규칙이 도달했는지 확인하는 것이 아니라 규칙을 다시 강조하는 것이기 때문입니다. 이는 에이전트가 지침 파일의 규칙을 건너뛰는 것처럼 보이는 대부분의 사례 뒤에 숨겨진 동일한 함정입니다.

동일한 목록에는 조용히 발생하는 두 번째 문제가 있습니다. OpenCode 자체 예시에는 instructions 필드에 .md로 끝나는 .cursor/rules glob이 포함되어 있습니다. Cursor의 프로젝트 규칙은 다른 확장자를 사용하므로, 그렇게 작성된 glob은 Cursor 규칙으로 가득 찬 폴더에서 아무것도 일치시키지 못합니다. 그리고 아무것도 일치하지 않는 것은 오류로 처리되지 않습니다. 한 도구의 문서에서 작동하는 예시를 다른 도구의 설정으로 복사하는 것은, 겉보기에는 채워져 있지만 실제로는 거의 기여하지 않는 목록을 만드는 지름길입니다.

모든 프로젝트가 동일한 URL을 가리키도록 하고 이를 중앙 집중식이라고 부르기. 중앙 집중식은 맞습니다. 하지만 이제 회사 내 모든 세션의 시작 경로에 네트워크 의존성이 생기게 됩니다.

타임아웃 늘리기. 이를 위한 문서화된 옵션은 없습니다. 5초는 튜닝할 수 있는 기본값이 아니라 고정된 동작으로 명시되어 있습니다.

대체용으로 두 번째 URL 추가하기. 두 개의 원격 항목은 장애 조치(failover)가 아니라 타임아웃 기회가 두 번 생기는 것뿐입니다. 문서화된 동작 중 하나를 시도한 후 다른 하나를 시도하는 기능은 없습니다.

가져오기 실패 시 경고가 발생할 것이라 가정하기. 원격 지침 파일이 제시간에 도착하지 않을 때 심각한 오류가 발생하거나 세션이 차단된다는 설명은 문서 어디에도 없습니다. 아무런 표시 없이 조용히 넘어갈 것에 대비해야 합니다.

공유 규칙을 모든 프로젝트의 AGENTS.md에 복제하기. 이는 신뢰할 수 있는 옵션이며 원격 기능이 피하고자 했던 바로 그 방식입니다. 작동은 하지만, 한 달 안에 복사본들이 서로 달라지게 됩니다.

파일 참조 구문이 해결해 줄 것이라 가정하기. 해결해 주지 못합니다. 문서에는 명시적으로 "opencode는 AGENTS.md에서 파일 참조를 자동으로 파싱하지 않습니다"라고 되어 있습니다. 지침 파일 내부에 경로를 작성한다고 해서 해당 파일이 불러와지지는 않습니다. instructions 필드가 지원되는 유일한 경로입니다.

목표는 모든 세션의 핵심 경로에 네트워크 호출을 두지 않으면서 공유 규칙의 신뢰할 수 있는 단일 버전을 유지하는 것입니다. 즉, OpenCode가 읽는 것은 리포지토리의 복사본이고, 네트워크는 그 복사본을 업데이트하는 역할만 하도록 만드는 것입니다.

Step 1: 원격 항목을 커밋된 로컬 경로로 대체하기

opencode.json에서 URL 항목을 리포지토리 내부의 경로로 변경합니다. 공유 가이드를 보관하는 docs 폴더 같은 곳을 지정하고, instructions 배열에서 일반 경로로 참조하도록 합니다. 그리고 파일을 커밋합니다.

이렇게 하면 의존성이 역전됩니다. 이제 OpenCode는 디스크에 있는 파일을 읽게 되며, 이 파일은 존재하거나 존재하지 않으므로 실패 모드가 간헐적이지 않고 일관되게 바뀝니다. 리포지토리를 클론하는 사람은 내부 호스트에 연결할 수 있는지 여부와 관계없이 규칙을 얻게 됩니다.

목록을 편집하는 동안 목록에 있는 모든 glob을 확인하세요. 확장자가 대상 도구가 실제로 작성하는 것과 일치하는지 확인하고(이 부분이 Cursor 규칙 예시가 잘못된 부분입니다), 각 glob이 현재 최소 하나 이상의 파일과 일치하는지 확인하세요. 아무것도 일치하지 않는 glob은 정상 작동하는 항목과 구별할 수 없으며, 이는 바로 우리가 제거하려는 특성입니다.

Step 2: 업데이트를 시작 시의 부작용이 아닌 가시적인 단계로 만들기

이제 로컬 복사본을 업데이트하는 방법을 결정합니다. 가장 좋은 방법은 팀이 이미 검토하고 있는 프로세스를 활용하는 것입니다. 업스트림 가이드가 변경될 때 풀 리퀘스트(PR)를 생성하는 예약된 작업이나, 의존성 업데이트 루틴의 한 단계로 포함시키는 것입니다.

중요한 것은 업데이트가 사람의 눈에 보여야 한다는 점입니다. 공유 가이드가 변경될 때 누군가는 이 프로젝트의 맥락에서 변경 사항(diff)을 검토해야 합니다. 중앙 리포지토리에서는 타당한 규칙이 특정 서비스에서는 맞지 않을 수 있기 때문입니다. 시작 시 가져오기를 수행하면 검토 없이 새 텍스트가 적용되지만, 풀 리퀘스트를 통하면 새 텍스트와 함께 의사 결정 과정을 거치게 됩니다.

또한 이력(history)도 남길 수 있습니다. 6개월 후 "이 규칙이 우리에게 언제부터 적용되기 시작했는가?"에 대한 답을 리포지토리 로그에서 찾을 수 있습니다. 이는 실시간으로 가져온 파일이 결코 제공할 수 없는 가치입니다.

Step 3: 결합된 지침 세트가 예상대로 작동하는지 검증하기

세션을 시작하고 규칙이 적용되는지 확인합니다. 에이전트에게 규칙을 가지고 있는지 묻는 방식이 아니라, 규칙의 지배를 받는 작은 작업을 부여하고 출력이 규칙을 따르는지 확인하는 방식으로 검증해야 합니다.

명확하고 비용이 적게 드는 작업을 선택하세요. 공유 가이드에서 특정 에러 처리 형식을 요구한다면, 에러를 반환해야 하는 작은 함수를 요청하고 그 형식을 확인하세요. 주석 규칙을 요구한다면 새 파일을 요청하고 헤더를 읽어보세요.

변경 후 한 번 수행하고, 로컬 복사본이 업데이트될 때마다 다시 수행하세요. 규칙을 실행해 보는 테스트만이 유일하게 신뢰할 수 있는 확인 방법입니다. 지침 세트는 항목별 보고 없이 하나의 본문으로 병합되기 때문입니다. 이는 지침의 범위를 특정 파일로 제한하는 작업을 가정이 아닌 의도적으로 수행해야 하는 이유와 동일합니다.

공유 가이드는 하나의 도구를 위한 설정일 뿐입니다. 규칙 뒤에 숨겨진 추론(왜 이런 에러 형식인지, 왜 이런 경계인지)이야말로 실제로 모든 도구와 모든 세션에서 사용하고 싶은 내용입니다. MemoryLake는 가져오기 완료 여부에 의존하지 않고 이러한 추론을 보관할 수 있는 공간입니다.

여러분은 자신의 언어로 직접 항목을 작성합니다. 원격 지침 파일, OpenCode 설정 또는 공급업체의 저장소에서 아무것도 읽거나 쓰거나 삭제하지 않습니다.

Step 1: API 키 생성하기

로그인하고 대시보드에서 키를 생성합니다. 이 키를 사용하면 에이전트가 중간에 가져올 파일이나 손실될 타임아웃 없이 항목을 직접 읽을 수 있습니다.

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

공유 가이드가 인코딩하는 결정을 항목당 하나씩, 각각의 이유와 함께 추가합니다. "호출자가 종류에 따라 분기해야 하므로 에러는 타입이 지정된 결과를 반환합니다"는 이식성이 있습니다. 반면 "에러 처리 가이드를 따르세요"는 포인터가 끊어지는 순간 작동을 멈추는 포인터일 뿐입니다.

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

에이전트가 워크스페이스를 가리키도록 설정합니다. 그러면 팀이 사용하는 모든 도구에 추론이 존재하게 되며, 도구별 지침 파일은 도구에 필요한 만큼 가볍게 유지할 수 있습니다.

첫 번째 변화는 네트워크 상태 불량이 더 이상 조용한 규칙 누락으로 이어지지 않는다는 점입니다. 디스크에서 읽는다는 것은 규칙이 존재하거나 눈에 띄게 존재하지 않는다는 것을 의미하며, "눈에 띄게 존재하지 않음"은 3주 후 코드 리뷰 때가 아니라 첫 번째 실행 시 사람이 알아차릴 수 있는 현상입니다.

두 번째는 공유 가이드에 검토 단계가 추가된다는 점입니다. 중앙 규칙 리포지토리에는 규칙이 계속 쌓이게 되며, 시작할 때 이를 가져오는 프로젝트는 자신에게 적용되지 않는 규칙을 포함하여 모든 추가 사항을 자동으로 채택하게 됩니다. 하지만 diff 형태로 제공되는 업데이트는 검토를 거치게 됩니다.

세 번째는 지침 목록을 감사(audit)할 수 있게 된다는 점입니다. 모든 항목은 확인할 수 있는 경로 또는 glob이며, glob을 확인하는 데는 몇 초밖에 걸리지 않습니다. 목록에 URL이 없어지면 "내 지침 세트에 무엇이 포함되어 있는가?"라는 질문에 명확한 답을 내릴 수 있습니다. 이는 지침 파일을 유지 관리할 가치가 있게 만드는 특성이며, 파일 순서와 우선순위를 명시적으로 확정해야 하는 이유이기도 합니다.

비용도 존재하며, 이를 솔직하게 밝히는 것이 좋습니다. 바로 로컬 복사본이 오래된 상태(stale)가 될 수 있다는 점입니다. 실시간으로 가져온 파일은 항상 최신 상태이지만, 커밋된 파일은 마지막 업데이트 시점을 기준으로 최신 상태입니다. 오래된 규칙은 파일에서 눈에 보이지만 누락된 규칙은 보이지 않기 때문에 이 트레이드오프는 감수할 가치가 있습니다. 다만 이는 실제로 업데이트가 수행될 때만 유효합니다. 팀에서 업데이트를 실행하지 않는다면, 이는 예상치 못한 상황이 아니라 오래된 상태를 스스로 선택한 것입니다.

이러한 트레이드오프는 도구가 다른 곳에서 지침을 가져오겠다고 제안할 때마다 나타납니다. 그것이 요청 시 에이전트가 규칙을 생성해 주는 것이든, 설정을 새 도구의 형식으로 다시 작성하는 마이그레이션이든 마찬가지입니다. Cursor에서 OpenCode로 프로젝트를 이전해 본 사람이라면 누구나 공감할 것입니다.

시작 경로는 로컬로 유지하세요. OpenCode가 첫 번째 턴 전에 읽어야 하는 모든 것은 디스크에 있어야 합니다. 네트워크 호출은 세션 시작이 아니라 업데이트 작업에 포함되어야 합니다.

대상 도구의 실제 확장자와 비교하여 모든 glob을 검증하세요. 이는 가장 흔하게 발생하는 '조용한 무반응' 항목을 잡아내는 2분짜리 확인 작업입니다. 공식 예시를 포함하여 그 어떤 예시도 맹신하지 마세요.

리포지토리당 하나의 신뢰할 수 있는 복사본을 커밋하여 유지하세요. 공유 체크아웃에 대한 심볼릭 링크나 프로젝트 외부의 경로가 아니어야 합니다. 새로 클론하는 사람도 규칙을 즉시 얻을 수 있어야 합니다.

규칙을 테스트하되, 규칙에 대해 묻지 마세요. 에이전트가 지침을 가지고 있다고 보고하는 것은 증거가 되지 않습니다. 규칙의 지배를 받는 작은 작업이 증거가 됩니다.

규칙 파일 외부의 안전한 곳에 이유를 보관하세요. 도구가 변경되면 규칙 파일은 다시 작성됩니다. 규칙이 존재하는 이유는 다음 사람이 규칙을 유지할지 여부를 결정하는 기준이 됩니다.

로컬 복사본에 날짜를 기입하세요. 상단에 마지막으로 업데이트된 날짜를 적은 한 줄의 메모는 "이것이 최신인가"라는 의문을 조사 대상에서 한눈에 확인 가능한 정보로 바꾸어 줍니다.

무엇이 늘어나는지 주시하세요. 지침 목록의 모든 항목은 요청에 결합됩니다. 항목이 누적되는 목록은 매 턴마다 늘어나는 접두사(prefix)가 되며, 이는 매번 전송하는 내용으로 인해 발생하는 토큰 비용과 동일한 회계 문제입니다.

원격 지침 파일은 실제 문제를 해결하지만 동시에 특정 문제를 야기합니다. OpenCode는 5초 타임아웃으로 이를 가져오고, 도달한 모든 것을 AGENTS.md와 결합하며, 항목별 보고를 제공하지 않습니다. 따라서 도달하지 못한 지침 파일은 도달한 파일과 완전히 똑같아 보입니다.

목록이 커밋된 로컬 복사본을 가리키도록 설정하고, 업데이트를 시작 시의 부작용이 아닌 검토 단계를 거치도록 만들며, 에이전트에게 규칙이 적용되는 작업을 부여하여 규칙이 활성화되어 있음을 증명하세요. 자동 최신화 기능은 잃게 되지만, 눈으로 확인할 수 있는 실패 모드를 얻게 됩니다.

그런 다음 규칙 뒤에 숨겨진 추론을 특정 도구의 설정 파일이 아닌 다른 곳에 보관하세요. 다음 마이그레이션 이후에도 여전히 필요한 부분은 바로 그 추론이기 때문입니다. 이는 팀들이 에이전트 간에 지침을 이동하면서 파일 자체는 가장 쉬운 부분이었음을 깨달았을 때 도달하는 결론과 같습니다.