Claude 채팅이 GitNest 코드 변경을 제안하고 osFoundry에서 승인하는 법

이 글을 끝까지 따라 하면 osFoundry에 연결된 Claude 대화가 GitNest 저장소를 읽고, 코드를 검색하고, 변경까지 준비해 주는 상태가 된다. 준비할 수 있는 건 태스크, 파일 커밋, change set, 체크 재시도, 풀 리퀘스트다. 다만 Claude가 요청한 순간에는 아무 일도 안 일어난다. 전부 osFoundry의 "Needs your approval"(승인 대기)에 제안으로 쌓이고, 카드에는 파일, 브랜치, 대상 커밋이 그대로 찍힌다. 실행되는 건 Approve를 눌렀을 때뿐이다. 애초에 Claude 쪽에는 저장소에 직접 쓰는 tool이 없다.

누가 뭘 하나

	Claude 쪽	osFoundry 쪽
로그인	평소 쓰던 Claude 계정 그대로	osFoundry 계정으로 연결을 한 번 승인해 둔 상태
볼 수 있는 범위	읽기 tool이 돌려준 것만	연결이 들어가 있는 프로젝트에 붙은 GitNest 저장소
코드 읽기	search_gitnest_code: 범위가 제한된 줄 단위 발췌	바이너리 파일, 파일 전체 덤프, 인증 정보, 로컬 바인딩은 안 준다
코드 변경	propose_gitnest_… tool 7개	호출 한 번에 제안 하나, 승인 대기
승인하는 사람	Claude 쪽엔 없음	연결 오너인 나. 저장소 권한이 남아 있는 동안만
실제로 쓰는 쪽	없음	승인된 작업을 osFoundry가 실행하고, 연결 이름으로 기록
provider 토큰	절대 안 넘어감	연결해 둔 GitHub/GitLab 계정은 provider PR을 승인할 때만 쓰인다

설정

1. 채팅을 한 번 연결해 두기

Claude 채팅이 아직 osFoundry에 연결돼 있지 않다면, 여기는 평범한 커스텀 커넥터 절차다. 열쇠 아이콘 → Connected에서 연결을 만들고, 그 서버 주소를 Claude에 커스텀 커넥터로 추가한 다음, 워크스페이스 하나를 승인하면 된다. Claude 쪽 화면은 Anthropic의 커스텀 커넥터 가이드에 나와 있다. 아래부터는 연결 상태가 "Connected."로 떠 있다고 보고 진행한다.

2. 저장소를 프로젝트에 넣기

연결이 GitNest 저장소를 알아서 보는 일은 없다. 저장소가 연결이 속한 프로젝트에 들어가 있어야 한다.

GitNest에서 저장소를 열고 Project 섹션을 찾는다. 설명 문구는 "Connected agents in this project can use approved GitNest read tools when their connection owner still has repository access."다. 프로젝트를 고르는 선택 상자는 저장소 오너에게만 보이고, 나머지 사람에게는 프로젝트 이름이 텍스트로만 나온다. 프로젝트를 고르면 "Repository project updated."라고 확인 메시지가 뜬다.

3. 연결을 같은 프로젝트에 추가하기

다시 열쇠 아이콘 → Connected로 가서 연결을 고르고, Projects에서 같은 프로젝트에 추가한다. 그러면 그 프로젝트의 GitNest 저장소가 노트, 지식 베이스 같은 다른 동기화 콘텐츠와 함께 딸려 온다.

Tools를 열면 "All supported tools are on by default"라고 나오고, tool 이름은 밑줄 대신 공백으로 표시된다. GitNest 쪽은 이것들이다.

read gitnest repository        propose gitnest work
search gitnest code            propose gitnest change set
list gitnest work              propose gitnest server composition
read gitnest work              propose gitnest file import
list gitnest saved results     propose gitnest check rerun
list gitnest checks            propose gitnest native publication
                               propose gitnest provider publication

예시: Claude 연결의 Tools 체크리스트. 기본값은 전부 켜짐

커밋까지만 맡기고 풀 리퀘스트 준비는 절대 안 시키고 싶다면, publication tool 두 개의 체크를 풀고 Save tools를 누르면 된다. 어느 쪽이든 제안에는 승인이 필요하다. 체크를 푸는 건 Claude가 그 요청 자체를 못 하게 만들 뿐이다.

4. 채팅에서 부탁하기

Claude 대화에서 + 메뉴 → Connectors로 osFoundry 커넥터를 켜고, 그냥 말로 부탁하면 된다. 같은 서버를 Claude Code에 osfoundry라는 이름으로 추가했다면, tool은 거기서 mcp__osfoundry__propose_gitnest_file_import 같은 이름으로 보인다.

실제로 돌려 보면

아래 tool 이름과 인자 이름은 osFoundry 서버가 tools/list에 내놓는 그대로다. 저장소, 요청 문장, ID, 답변은 예시 내용이다.

예시

나: osFoundry에서 demo-api에 테스트 돌리는 법(tests/에서 pytest 씀)을 설명하는
    CONTRIBUTING.md를 추가하고, README에서 링크 거는 태스크도 우선순위 낮음으로 하나 열어 줘.

Claude → list_granted_resources {}
       ← 프로젝트 "API" · GitNest 저장소 "demo-api"
Claude → read_gitnest_repository {"repository_id": "…"}
       ← 네이티브 저장소, 기본 브랜치 main
Claude → search_gitnest_code {"repository_id": "…", "query": "pytest", "branch": "main"}
       ← pyproject.toml: [tool.pytest.ini_options] · tests/test_limits.py: import pytest
Claude → propose_gitnest_file_import {"repository_id": "…", "branch": "main",
           "message": "Add CONTRIBUTING.md with test instructions",
           "files": [{"path": "CONTRIBUTING.md", "content": "# Contributing\n…"}],
           "idempotency_key": "…"}
       ← 오너 승인 대기 중인 제안
Claude → propose_gitnest_work {"repository_id": "…",
           "title": "Link CONTRIBUTING.md from README", "priority": "low",
           "idempotency_key": "…"}
       ← 오너 승인 대기 중인 제안

Claude: osFoundry에 제안 두 개를 준비했어요. main에 CONTRIBUTING.md를 추가하는 커밋 하나,
        README에서 링크하는 태스크 하나예요. 아직 아무것도 커밋하지 않았고, 둘 다 승인 대기 중이에요.

osFoundry 헤더에는 "Claude research proposes GitNest file changes"가 뜨고, 연결 패널의 "Needs your approval" 아래에 두 개가 나란히 올라온다. 커밋 카드는 "Commit GitNest files in demo-api"로 시작해서 "Commit to branch: main", 커밋 메시지, 접혀 있는 "Review all proposed files (1)"이 이어진다. 펼치면 CONTRIBUTING.md 전체가 보인다. 그 아래에 "Expires …", Approve and create, Decline이 있다.

예시: Needs your approval에 올라온 GitNest publish 제안

두 번째 요청은 이미 있는 change set에 대한 거다.

예시

나: rate-limit change set 초록불이야? integration이 실패했으면 다시 돌리고,
    통과하면 풀 리퀘스트로 낼 수 있게 준비해 줘.

Claude → list_gitnest_work {"repository_id": "…", "kind": "changes"}
       ← "Rate-limit fix" · 버전 3
Claude → list_gitnest_checks {"repository_id": "…", "change_set_id": "…"}
       ← 합성 커밋 9c1e47a…: unit 통과 · integration 실패 (종료됨)
Claude → propose_gitnest_check_rerun {"repository_id": "…", "change_set_id": "…",
           "check_name": "integration", "expected_change_set_version": 3,
           "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"}
       ← 오너 승인 대기 중인 제안
  … 재시도를 승인하고, 통과 …
Claude → propose_gitnest_native_publication {"repository_id": "…", "change_set_id": "…",
           "expected_change_set_version": 3,
           "expected_composition_oid": "9c1e47a…", "idempotency_key": "…"}
       ← 오너 승인 대기 중인 제안

여기서 봐야 할 건 Claude가 보내야 하는 값이다. 재시도도 publication도 Claude가 본 change set 버전과 합성된 커밋을 박아서 보낸다. 내가 누르기 전에 누가 change set을 다시 합성하면, 내가 승인하려던 버전이나 커밋은 더 이상 카드에 적힌 그게 아니다. 그러면 승인 시점에 osFoundry가 다시 확인하고 실행을 거부한다.

카드마다 뭘 승인하는 건가

Tool	카드 제목	버튼	승인하면 일어나는 일
propose_gitnest_work	Create GitNest work	Approve and create	Todo와 GitNest work item을 만든다
propose_gitnest_change_set	Create GitNest draft change set	Approve and create	저장된 실행 결과로 draft change set을 만든다. 합성도 공개도 안 한다
propose_gitnest_server_composition	Compose GitNest change set	Approve and create	버전을 다시 확인한 뒤 서버에서 change set을 합성한다
propose_gitnest_file_import	Commit GitNest files	Approve and create	UTF-8 파일 최대 20개(합계 200 KB)를 카드에 적힌 브랜치에 커밋한다
propose_gitnest_check_rerun	Retry GitNest check	Approve retry	그 버전과 커밋에 대해 종료된 체크 하나를 다시 큐에 넣는다
propose_gitnest_native_publication	Publish GitNest pull request	Approve and publish	publication 브랜치를 만들고 네이티브 저장소에 풀 리퀘스트를 연다
propose_gitnest_provider_publication	Open a draft GitHub or GitLab pull request	Approve and publish	연결해 둔 provider 계정으로 그 change set의 브랜치만 push하고 draft PR을 연다

change set을 가리키는 카드에는 "Change set: … · expected version N", "Reviewed commit: …"과 함께, GitNest에서 change set을 열어 주는 "Review change set before approving" 링크가 붙는다. publication 카드 두 개에는 무슨 일이 일어날지 한 줄씩 더 붙는다. 예를 들면 "Approval creates a publication branch and opens a pull request in this native repository." 같은 문장이다.

선은 어디에 그어져 있나

Claude 연결은 GitNest에 못 쓴다. GitNest 자체의 쓰기 라우트는 에이전트 스코프 접근을 거부하고(osFoundry GitNest 라우트의 denyAgentScope), Connected tool은 그 라우트를 부르지도 않는다. Claude 채팅이 할 수 있는 건 제안을 올리는 것뿐이고, 승인 뒤에는 osFoundry가 직접 작업을 실행하면서 연결을 출처로 기록한다. 에이전트의 쓰기는 전부 이 한 길로만 지나가니까 나중에 추적할 수 있다.

승인은 클릭하는 순간 한 번 더 검사된다. osFoundry는 연결이 아직 살아 있는지, 저장소가 아직 연결이 속한 프로젝트에 있는지, 내가 아직 저장소 권한을 갖고 있는지, 제안이 만료되지 않았는지를 다시 본다. 합성, 재시도, publication이면 change set 버전과 커밋도 확인하고, publication이면 저장소의 리스크 정책, 필수 체크, 대상 브랜치까지 본다. 거절됐거나 만료됐거나 낡은 제안은 실행되지 않는다. propose tool은 전부 idempotency_key를 받기 때문에, 응답이 끊겨서 Claude가 같은 호출을 반복해도 두 번째 요청이 되지 않는다.

여기서 배포되는 건 없다. 제안이 갈 수 있는 가장 먼 곳은 풀 리퀘스트다. 네이티브 GitNest PR이거나, GitHub/GitLab의 draft PR이다. 머지와 머지로 촉발되는 모든 건 GitNest나 provider 쪽에서 내가 정한다.

Git provider 토큰은 Claude에 절대 안 간다. provider PR은 osFoundry에 연결해 둔 내 계정을 승인 시점에 쓰고, push하는 것도 그 change set 전용 브랜치뿐이다. 다른 ref는 건드리지 않는다.

읽기는 일부러 제한해 뒀다. search_gitnest_code는 상한이 있는 줄 발췌만 돌려주고, 바이너리 파일이나 파일 전체는 주지 않는다. work, 실행, 저장된 결과를 읽을 때도 로컬 바인딩과 인증 정보는 빠진다. 기존 파일을 고치고 싶으면 지금 내용을 채팅에 붙여 넣어서 Claude가 새 버전 전체를 제안하게 하면 된다. 새 파일 추가는 발췌만으로도 충분하다.

다음 단계

제일 작은 쓰기부터 해 보자. CONTRIBUTING.md 같은 새 파일 하나만 제안하게 하고, 카드를 열어 "Review all proposed files"를 펼쳐 본 다음 승인하면 된다. GitNest 자체가 clone, push, 액세스 토큰을 어떻게 다루는지는 GitNest 기능 페이지에 있다.