FlightPlan

에이전트들이 충돌합니다. FlightPlan을 제출하세요.

작업이 시작되기 전, 각 에이전트는 목적지를 선언하고 현재 진행 중인 작업을 확인합니다. 충돌을 조정한 후, 무엇이 변경되었고 그 이유를 남깁니다.

조언일 뿐, 강제하지 않습니다.

에이전트 작업의 부산물이지, 유지 관리해야 할 또 다른 프로세스가 아닙니다.

FlightPlan은 코딩 에이전트들의 작업이 충돌하기 전에 조정합니다. 이 저장소는 getflightplan.com의 호스팅 서비스를 위한 CLI, MCP 서버, 설치 프로그램을 포함합니다.

빠른 시작

저장소 루트에서 실행하세요:

uvx getflightplan install

위 명령어는 Claude Code용 FlightPlan을 설치합니다. Codex의 경우 --agent codex (또는 --agent both)를 추가하세요. 이 명령어는 재실행해도 안전합니다. 한 머신에서 처음 실행하는 경우, 다음으로 uvx getflightplan login을 실행하세요 — 계정을 연결하고 MCP 설정을 완료합니다.

호스팅 서비스는 베타 버전입니다; getflightplan.com에서 GitHub 계정으로 로그인하세요. 패키지는 PyPI에 있으므로 위 명령어만으로 충분합니다. 대신 브랜치나 커밋을 고정하려면 소스에서 설치하세요: uvx --from git+https://github.com/sledmonkey/getflightplan getflightplan install.

버전 및 호환성 정책: docs/versioning.md.

Related MCP server: asynkor

작동 방식

1. 작업을 제출합니다. 편집 전에 에이전트가 작업과 수정할 파일을 선언합니다.

2. 진행 중인 작업을 확인합니다. FlightPlan은 Git이 볼 수 없는 커밋되지 않은 변경사항, 코딩 중 결정 사항, 관련 최근 결과를 포함한 중복되는 활성 작업을 반환합니다.

3. 조정합니다. 중복은 조언일 뿐입니다: 작업 범위를 좁히거나, 순서를 정하거나, 컨텍스트를 가지고 진행하세요.

4. 보고합니다. 에이전트는 무엇이 변경되었는지, 무엇이 놀라웠는지, 무엇을 시도했는지 기록하여 다음 세션이 처음부터 시작하지 않도록 합니다.

설치 프로그램이 추가하는 것

• .flightplan.toml — 모든 에이전트가 게시하는 저장소 이름과 레지스트리 URL을 고정합니다. 의도적으로 커밋되며, 비밀 정보는 없습니다.

• CLAUDE.md 및/또는 AGENTS.md의 관리되는 에이전트 스니펫.

• /registry-digest — 온디맨드 "최근 변경 사항" 명령어.

• 세션 종료 중지 훅 (.claude/hooks/flightplan_stop_hook.py 및 설정 연결) — 에이전트가 열린 의도를 마무리하도록 알림.

또한 MCP 등록 및 서비스 연결 가능성을 확인하고, 머신에 자격 증명이 있을 때 등록을 복구합니다 — 프롬프트 없이 자동으로 수행됩니다. 검증은 조언일 뿐이며 실행을 실패시키지 않습니다.

설치 프로그램이 작성한 모든 것을 제거하려면 저장소 루트에서 getflightplan uninstall을 실행하세요 (--dry-run으로 미리보기, --purge-key로 저장된 API 키도 삭제).

로그인

getflightplan login은 API 키를 복사하지 않고 자격 증명을 얻습니다. 브라우저를 열고 승인하면 자격 증명이 ~/.config/flightplan/env에 모드 600으로 저장됩니다. 자격 증명은 절대 출력되지 않습니다. 자격 증명이 저장된 후, 로그인은 머신의 에이전트 바이너리를 위한 MCP 서버도 등록합니다 — 설치 프로그램이 자격 증명 없이 건너뛰었던 단계입니다.

브라우저가 없는 머신에서는 getflightplan login --headless를 실행하세요. 명령어가 짧은 코드와 주소를 표시합니다. 다른 기기에서 해당 주소를 열고 코드를 입력하세요.

getflightplan logout은 이 머신에 저장된 자격 증명을 제거합니다. 서비스에서 취소하려면 /devices 페이지를 사용하세요.

저장소 찾기

로그인 후, 클라이언트는 레지스트리에 이 체크아웃이 어떤 저장소인지 묻습니다. origin 리모트의 주소와 최대 1000개의 커밋 ID를 보내 클론이 있음을 증명합니다. 계정에 접근 권한이 있으면 ID와 이름이 .flightplan.toml에 저장됩니다. 레지스트리가 저장소를 모르면 클라이언트가 브라우저에서 등록을 제안합니다. 계정에 접근 권한이 없으면 클라이언트가 요청을 제안합니다.

getflightplan login --no-register는 확인을 건너뜁니다. getflightplan register는 나중에 단독으로 실행합니다. 확인 실패는 로그인을 실패시키지 않습니다.

작업이 완료되었음을 알리기

uncommitted: true로 완료된 의도는 작업이 누군가의 작업 트리에만 있고 다른 곳에는 없음을 의미합니다. 레지스트리는 트리를 볼 수 없으므로, 작업이 완료되었다고 알릴 때까지 해당 경로를 건드리는 모든 사람에게 계속 경고합니다.

에이전트는 mark_intent_landed 도구로 이를 수행합니다. 수동으로도 할 수 있습니다:

getflightplan landed <intent-id> --commit <sha> --commit <sha>

커밋은 선택 사항입니다; 타임스탬프가 수정 사항입니다. SHA를 알고 있는 경우에만 전달하세요 — 클라이언트는 어떤 커밋이 어떤 의도에 속하는지 추측하지 않습니다. 완료 처리는 안전하게 반복할 수 있으며 완료된 기록을 덮어쓰지 않습니다.

설정

• FLIGHTPLAN_URL — https://api.getflightplan.com

• FLIGHTPLAN_API_KEY — API 키 (MCP 서버의 환경 변수; 중지 훅도 ~/.config/flightplan/env를 읽습니다).

• .flightplan.toml — 저장소별 고정: repo 이름과 url, 또는 저장소에 ID가 고정된 후의 읽기 가능한 name이 있는 target_id.

에이전트에게 전달되는 내용

설치 프로그램은 저장소 이름이 고정된 다음 관리되는 계약을 추가합니다.

의도 레지스트리

이 저장소는 팀 의도 레지스트리(MCP 서버: flightplan)에 참여합니다.

• 중요한 작업을 시작하기 전에 post_intent를 호출하세요. 기준: 작업이 다른 에이전트가 만날 동작, 기본값, 계약을 변경하거나 — 순수 조사의 경우 결과가 다음 에이전트의 시간을 1시간 이상 절약할 수 있습니까? 둘 중 하나라도 '예' → 게시; Q&A 및 오타 수준 수정은 제외합니다. 한 문단 요약(무엇 + 왜), kind (build 또는 폐기 조사용 explore/spike), 변경할 영역의 touches 글로브를 보내세요. 반환된 ID는 나중을 위해 보관하세요. repo에는 git origin 리모트의 기본 이름(리모트가 없으면 저장소 루트 디렉토리 이름)을 사용하세요 — 이 저장소의 모든 에이전트는 동일한 이름을 사용해야 하며, 그렇지 않으면 충돌 검사가 서로를 놓칩니다. 응답에는 context가 포함될 수 있습니다: 작업과 관련된 최근 완료된 작업 — 시작하기 전에 해당 결과를 읽으세요; 그 안의 놀라운 점과 막다른 길은 중요합니다.

• 응답에 warn 수준의 중복이 포함된 경우, 일시 중지하기 전에 중복이 무엇인지 확인하세요. 확인이 필요 없는 두 가지 경우가 있습니다: 중복되는 의도가 당신이 수행하도록 요청받은 바로 그 작업(검토, 확인, 후속 조치)이거나, 작업이 읽기 전용인 경우입니다. 그렇지 않으면, 누가 무엇을 하고 있고 어떤 글로브가 충돌하는지 사용자에게 알리고 계속 진행하기 전에 어떻게 진행할지 물어보세요. fyi/nudge 수준: 간략히 언급하고 계속 진행하세요.

• 작업 범위가 변경되거나 시간이 오래 걸리는 경우 update_intent를 호출하세요: 범위가 확장될 때 요약/글로브를 수정하세요(충돌 검사가 이를 기준으로 실행됩니다 — 오래된 글로브는 실제 충돌을 놓칩니다), 또는 하루 이상 걸리는 작업의 경우 ID만으로 TTL을 갱신하세요. 응답에는 새로운 overlaps가 포함됩니다 — 게시와 동일한 글로브 기반 충돌 검사 — warn은 게시 시점의 warn과 동일하게 처리됩니다.

• 작업이 완료되거나 중단된 경우 — 세션이 마무리되는 경우 포함 — 한 문단 결과와 함께 complete_intent를 호출하세요: 실제로 변경된 사항, 놀라운 점, 시도했지만 거부된 접근 방식, 의도적으로 남겨둔 사항. warn 중복이 작업 진행 방식에 영향을 준 경우(조정, 범위 축소, 어쨌든 진행), 어떤 것인지 명시하세요. 이미 알고 있는 git 사실을 첨부하세요: 실제로 변경된 files (git diff --name-only), 생성된 commits, 작업 중 일부가 아직 커밋되지 않은 경우 uncommitted: true — 이 플래그는 다른 에이전트의 충돌 검사가 조용히 대신 loudly 경고하도록 합니다. 의도 완료는 세션이 아닌 작업 조각을 종료합니다: 완료 후 동작, 기본값, 계약을 변경하는 후속 작업은 새 게시를 받습니다 — "동일 세션"이 면제되지 않습니다.

• 선언된 미커밋 작업이 완료되었음을 알게 된 경우 해당 의도의 ID(커밋 SHA를 알고 있으면 함께)로 mark_intent_landed를 호출하세요: 누군가 알릴 때까지 레지스트리는 해당 경로를 건드리는 모든 사람에게 계속 경고합니다.

• 진행 중인 작업에 대한 정보가 오래되었을 수 있을 때마다 충돌을 다시 확인하세요 — 게시는 한 번 확인하며, 긴 세션에서는 오래됩니다. 다시 확인해야 할 시점: 읽기와 편집 사이에 파일이 변경된 경우, 방금 읽은 텍스트에서 편집이 실패한 경우 — 누군가의 작업이 당신 아래에 도착했습니다; 이 세션에서 생성하지 않은 공유 문서나 아티팩트를 편집하기 전에; 다른 에이전트로부터 인계받은 후 재개할 때; 이전 warn에 명명된 파일을 건드리기 전에. 가장 저렴한 재확인은 의도 ID만으로 update_intent를 호출하는 것입니다(TTL 갱신, 새로운 overlaps 반환); 열린 의도가 없거나 새 작업 범위를 정할 때는 list_intents를 사용하세요(overlaps 글로브 전달, 의미론적 확인을 위한 summary, 또는 기록을 위한 q/since).

• 대화 중 결정이 내려졌을 때(접근 방식 선택, 대안 거부, 방향 설정) 결정이 확정되는 즉시 기록하세요: kind: "decision"와 함께 post_intent, 질문을 요약으로, 결정 내용을 outcome에 — 무엇이 결정되었는지, 무엇이 거부되었는지, 그 이유. 한 번 호출; touches나 나중 완료 없음. 결정은 절대 충돌하지 않으며 검색 가능한 팀 메모리가 됩니다. 결정은 또한 수정 메커니즘입니다: 완료된 결과는 변경할 수 없으므로, 나중에 잘못된 것으로 판명되면 실제로 유지된 내용을 인용하는 결정을 게시하세요.

• 레지스트리는 조언일 뿐이며 작업을 차단해서는 안 됩니다: 도구가 없거나 오류가 발생하면 작업을 계속 진행하고, 사용자에게 uvx getflightplan install(getflightplan.com 참조)을 실행하여 이 저장소의 레지스트리에 가입할 수 있다고 한 번 알리세요.

데이터

머신을 떠나는 것은 조정 기록입니다: 의도 요약 및 결과 문단, 글로브 패턴, 변경된 파일 경로, 브랜치 이름, 커밋 ID — FlightPlan 서비스로만 전송됩니다. 소스 코드 내용은 절대 업로드되지 않습니다. 레지스트리가 아는 모든 것은 에이전트 작업의 부산물로 학습됩니다.

자세한 내용 — 절대 떠나지 않는 것, 어디에 저장되는지 — 는 docs/data-flow.md에 있습니다. 취약점 신고: SECURITY.md.

라이선스

Apache-2.0