opencode.jsonc 설정 가이드: 커밋 전 7가지 점검

핵심은 파일 위치만이 아닙니다. opencode.jsonc는 비밀값이 없는 검토 가능한 OpenCode 설정으로 두고, 자격 증명은 저장소 밖에 보관합니다. 전역 설정과 프로젝트 설정이 병합되는 방식을 이해한 뒤 Provider, 모델, 권한, 롤백을 검증해야 합니다.

공식 문서는 JSON과 JSONC 지원을 설명합니다. 주석은 설정 이유, 담당자, 확인 날짜, 재현 명령을 남기는 운영 메모로 쓰는 것이 좋습니다.

비밀값은 파일에 넣지 않습니다. 모델, shell, 도구, 권한, 프로젝트 경로는 설정할 수 있지만 API key, token, private URL, proxy 자격 증명은 환경 변수나 Provider 인증 흐름에 둡니다.

OpenCode 설정은 완전히 대체되지 않고 병합됩니다. 전역 설정과 프로젝트 설정이 함께 적용될 수 있으며, 같은 키만 더 높은 우선순위에서 덮어씁니다.

개인 습관은 전역 설정에, 팀이 검토해야 하는 규칙은 프로젝트 설정에 둡니다. 기본 모델, 무시 경로, 명령 정책, MCP, 권한은 리뷰 대상입니다.

Provider와 모델 ID는 최신 공식 문서나 Provider 화면에서 복사합니다. JSON이 유효해도 실제 모델 ID가 틀리면 요청 단계에서 실패합니다.

주 모델과 작은 모델은 비용, 속도, 컨텍스트, 로컬 사용 가능성, 컴플라이언스 같은 이유가 있을 때만 나눕니다. 이유가 바뀌면 설정도 재검토합니다.

권한은 가장 조심해야 하는 부분입니다. 편집과 shell 명령은 처음에 ask로 두고, 반복 가능하고 되돌리기 쉬운 저위험 작업만 좁게 allow로 바꿉니다.

패키지 설치, 삭제, 마이그레이션, 배포, push, secret, 저장소 밖 디렉터리는 deny 또는 명시적 확인으로 남겨야 합니다. agent나 MCP 예외는 해당 역할 가까이에 둡니다.

공식 Schema URL을 추가하면 편집기 검증과 자동완성이 가능합니다. 보안 검토를 대체하지는 않지만 오타와 오래된 값 형태를 빠르게 찾습니다.

그 다음 각 키가 비밀값이 아닌지, 프로젝트에 공유될 이유가 있는지, 주석이 맞는지, 버전 의존성이 있는지 사람이 확인합니다.

커밋 전에 낮은 위험의 저장소에서 테스트합니다. OpenCode 실행, 모델 목록, 파일 읽기, 작은 편집, 예상 명령, 차단되어야 하는 작업을 확인합니다.

운영체제, shell, Provider, 모델 ID, 테스트 명령, 롤백 방법을 기록합니다. 설정이 추측이 아니라 재현 가능한 기준이 됩니다.

1. 최소 파일 만들기Schema, 모델, 검토된 권한 자세로 시작합니다.
2. 문법 검증편집기 Schema나 JSONC 도구를 사용합니다.
3. 계층 확인전역, 프로젝트, 사용자 경로, 관리 설정 중 무엇이 이기는지 봅니다.
4. 작은 작업 실행파일 읽기, 가벼운 편집, 알려진 명령을 실행합니다.
5. deny 테스트차단되어야 하는 작업이 실행되지 않는지 확인합니다.
6. 롤백 기록규칙 제거 또는 설정 없이 시작하는 방법을 적습니다.

오류가 나면 JSONC 문법, 현재 디렉터리, Git 루트, 전역 override, 프로젝트 override, 환경 변수, Provider, 권한 순서로 분리해서 봅니다.

Windows에서는 파일 위치와 shell 동작을 나누어 봐야 합니다. 통합 터미널이 환경 변수를 못 보거나 설정한 shell이 존재하지 않을 수 있습니다.