flow-atlas은(는) 무엇을 하나요?
저장소 자체의 AGENTS.md, 설계 문서, 거버넌스 테스트가 이 스킬보다 우선합니다.
세 부분
atlas는 코드가 결정한 내용을 생성합니다. 사용자는 의도가 필요한 내용을 작성하고, atlas는 이를 검증합니다. 이 두 과정 사이에서 사용자는 어떤 작업이 어떤 컴포넌트에 속하는지 references/boundaries.md의 기준에 따라 해석합니다. 사용자가 결정한 모든 내용은 atlas가 읽는 파일(플로우 파일, 예외 파일, 설정, 피드백)에 기록되므로, 다음 실행과 다음 에이전트가 이를 볼 수 있습니다.
atlas가 생성: 절대 수동으로 작성하지 마세요
| 사실 | 명령어 |
|---|---|
| 표면(surface), 호출(call), 엣지(edge), operationId, 레지스트리, 계약 버전 | scan |
| 경로, 메서드 또는 컴포넌트별 표면과 호출 | query |
| 표면의 업스트림 호출자와 다운스트림에서 도달하는 서비스 | trace |
| 플로우 초안: 이름, 코드 경로를 따른 단계, 한 컴포넌트가 호출할 때의 진입점, 분기하는 후보 지점 | draft flow |
| 플로우가 코드에 부합하는지, 작성자 필드가 작성되었는지 | flows (조건들) |
| 위치와 주변 경로가 포함된 발견 결과 | check, explain |
| 리비전 간 변경 사항 | diff |
| 설정 후보 및 설정이 다루는 범위 | inventory, scan |
| 각 컴포넌트의 OpenAPI 설명, 커밋된 설명이 코드와 얼마나 일치하는지, 코드가 결정하는 경우 해당 컴포넌트의 설명은 무엇인지 | scan, inventory |
graph.json을 grep하거나 텍스트 검색으로 호출자를 추측하거나 기억에서 표면 ID를 입력하지 마세요. atlas 출력에서 복사하세요.
사용자가 작성: atlas가 검증
| 내용 | 검증 항목 |
|---|---|
플로우의 title과 각 단계의 role | Documented |
owner, labels, sources, lifecycle (단계가 아직 구현되지 않았으면 planned) | 스키마; Resolved는 계획된 단계를 별도로 집계 |
플로우의 의도를 작성한 후 generated: { by: <tool>/<model>, at }; 검토가 필요할 때 stale_after (OKF) | 스키마; Fresh |
| 첫 번째 단계를 여러 컴포넌트가 호출할 때의 진입 컴포넌트; 핸들러가 분기하는 다음 단계 | EntryCalled, Connected |
produces | ProducesListed |
예외: 사유, decidedBy, reviewBy | 만료 시 발견 결과가 다시 나타남 |
| 오탐(false positive)과 그 이유 | stats |
| 설정 | scan 적용 범위 |
atlas가 파싱할 수 없는 컴포넌트의 프레임워크가 생성하는 OpenAPI 문서 (routes[].openapi, references/openapi.md) | scan 적용 범위 및 limit: 줄 |
origins: 배포 파일에서 각 컴포넌트가 환경에서 실행되는 기본 URL | export arazzo가 누락 시 알림 |
atlas가 설명을 ambiguous로 보고할 때 openapi.<component> | export arazzo가 설정될 때까지 거부 |
도구에 사용자의 역할을 넘기지 마세요: publicSurfaces, 예외 또는 기준선 업데이트는 사람이 수용할 이유 없이 수행하지 마세요. human: 액터가 있는 verified 항목을 절대 작성하지 마세요. 이는 사람의 검토를 기록하며, 플로우의 신뢰 등급(unverified, machine-confirmed, human-reviewed)이 이에 의존합니다.
사용자가 해석: 경계
홉(hop)이 속한 컴포넌트에 적합한지, 유사한 표면이 이미 작업을 수행하는지, 갭(gap)이 결함(defect)인지 계획(plan)인지 오탐(false positive)인지, 엣지를 어느 정도 신뢰할지, 플로우가 어디서 시작하고 끝나는지를 결정합니다. references/boundaries.md를 따르세요. 이 문서는 소스(저장소 규칙 > 플로우 역할 > 코드 순서)를 정렬하고 기준을 제공합니다.
설정
atlas --help를 실행합니다.atlas가 설치되어 있지 않으면 npx(npx github:hellices/flow-atlas --help)를 통해 실행하거나 사용자에게 설치를 요청하세요. 수동으로 읽기를 재구현하지 마세요.- 설정 파일은
<root>/atlas.config.yaml,<out>/atlas.config.yaml, 또는--config <file>입니다. 없으면 아래 "설정하기"를 따르세요. - 저장소에 쓰면 안 되는 경우
--out <외부 디렉토리>를 전달하세요. 모든 쓰기 작업은 해당 디렉토리로 이동합니다.
변경 설계
atlas query --path <경로 또는 일부>및atlas query --component <이름>으로 이미 존재하는 것을 확인합니다.atlas trace <가장 가까운 표면>으로 체인(클라이언트 호출, BFF 라우트, 핸들러가 도달하는 포트 메서드, 각각이 일치하는 서비스 라우트)을 확인합니다.- 결정: 재사용, 확장 또는 추가. 추가하거나 변경할 표면 키와 각 홉을 소유할 컴포넌트를 기록합니다. 두 컴포넌트가 동일한 단계를 수행하게 된다면 코드를 작성하기 전에 이를 해결합니다.
- 저장소에 플로우(
flows/*.flow.yaml)가 있는 경우 플로우를 업데이트하거나atlas draft flow <surface>로 새 플로우를 시작합니다("플로우 작성" 참조). 아직 존재하지 않는 단계는lifecycle: planned로 표시합니다.
구현 중
라우트나 클라이언트 호출을 추가한 후 atlas trace <surface>를 실행합니다. 업스트림에는 의도한 호출자가, 다운스트림에는 의도한 호출이 표시되어야 합니다. 빈 쪽은 아직 연결되지 않았거나 도구가 읽을 수 없는 방식으로 연결되었음을 의미합니다(호출과 멀리 떨어진 경로 구성, 다른 언어의 핸들러). 코드를 열고 이유를 설명하세요.
라우트가 생성된 OpenAPI 문서에서 제공되는 컴포넌트의 라우트를 추가, 제거 또는 변경하는 경우 동일한 변경에서 문서를 다시 생성하세요. 클라이언트 호출만으로는 문서가 변경되지 않습니다.
플로우 작성
atlas draft flow <첫 번째 표면>은 코드가 결정한 모든 내용이 포함된 플로우를 출력합니다.--to <표면>을 추가하여 코드가 특정 종단점까지 이어지도록 할 수 있습니다.flows/<이름>.flow.yaml(또는 변경할 수 없는 저장소의 경우<out>/flows/)에 저장합니다.- 모든
agent:주석을 채웁니다:title, 각 단계의role(컴포넌트가 수행하고 다른 컴포넌트에 남기는 작업),owner,lifecycle,produces; 초안이 후보를 나열하는 곳에서 진입점과 다음 단계를 선택합니다. 마커가 없는 값은 코드에서 오는 값이므로 그대로 둡니다. - 플로우가
Ready=True가 될 때까지atlas flows를 실행합니다.Resolved,Connected또는EntryCalled가 False이면 코드 또는 플로우가 잘못된 것입니다.references/boundaries.md를 사용하여 결정하세요.Documented가 False이면 작성자 필드가 비어 있다는 뜻입니다.
하나의 파일에 ---로 구분하여 여러 플로우를 넣을 수 있습니다. 표면 ID는 경로 매개변수를 OpenAPI 템플릿({id})으로 작성합니다. 위치, 엣지 또는 조건을 파일에 복사하지 마세요. atlas가 각 실행 시 이를 계산합니다. 형식은 flow-atlas 패키지의 schema/flow.schema.json에 정의되어 있으며, docs/schema.md와 docs/responsibilities.md에서 설명합니다.
마무리 전
atlas check --since <시작 리비전>을 실행합니다. 사용자의 변경으로 인해 도입된 발견 결과만 표시됩니다.- 각각에 대해
atlas explain <키>를 실행하면 위치와 유사한 경로가 표시됩니다. 그런 다음 수정하거나, 예외를 기록하거나, 오탐(false positive)을 기록합니다. "발견 결과 처리"를 참조하세요. atlas diff <기준>..WORKTREE --format markdown(또는<기준>..HEAD)의 출력과 각 새 표면의trace를 PR 설명 또는 인수인계 노트에 포함시킵니다.
설정이 뒤처진 경우
징후: stderr에 limit: 줄(설정된 파일이 아무것도 일치하지 않거나, 소스가 기준선의 절반 미만을 산출함)이 나타나거나, 호출된다고 알고 있는 라우트에 FA001이 나타납니다. atlas inventory를 실행하고 설정과 비교하여 수정한 후(references/config.md), atlas scan 적용 범위를 다시 확인하세요. atlas baseline update를 실행하기 전에 사람에게 물어보세요.
설정하기
atlas inventory는 아무것도 결정하지 않고 후보만 나열합니다. 이를 바탕으로 설정을 작성하고(references/config.md), atlas가 파싱하지 않는 서버 프레임워크(Spring, Django, Flask 등)의 경우 OpenAPI 문서를 생성하여 라우트를 가리키도록 한 후(references/openapi.md), atlas scan을 실행하여 모든 소스가 예상한 대로 결과를 산출할 때까지 반복하고, atlas check를 실행하며, 사람과 함께 발견 결과 샘플을 검토합니다. 그런 다음에만 기준선을 기록합니다.
발견 결과 처리
먼저 결함(defect), 계획(plan), 오탐(false positive) 중 무엇인지 결정하고(references/boundaries.md), 다음 단계를 따릅니다:
-
발견 결과가 실제 버그인 경우 수정합니다: 누락된 호출자를 연결하고, 죽은 라우트를 제거하며, 프로듀서를 추가하고, 호출이 제공되는 경로를 가리키도록 합니다.
references/rules.md는 규칙별 일반적인 원인을 나열합니다. -
코드가 의도적으로 올바른 경우 결정을 명시하는 예외를 추가합니다:
# flows/atlas-exceptions.yaml (또는 <out>/exceptions.yaml) - rule: FA001 key: FA001|orders|GET /orders/{id}/history reason: 서비스가 먼저 배포됩니다. 앱 화면은 다음 릴리스에서 따라옵니다. decidedBy: docs/orders.md#history reviewBy: 2026-12-31저장소 외부의 클라이언트에 제공되는 표면은 설정의
publicSurfaces에 기록합니다. -
발견 결과가 잘못된 경우:
atlas feedback <key> false-positive --note "<이유>"를 실행합니다. 추출기가 파일을 잘못 읽은 경우 어떤 파일과 어떻게 잘못 읽었는지 명시합니다.
사람이 요청하지 않는 한 atlas baseline update를 절대 실행하지 마세요. 발견 결과를 만족시키기 위해 생성된 코드를 절대 편집하지 마세요.
기계 판독 가능 출력
--format json 또는 --format yaml은 flow-atlas 패키지의 schema/*.schema.json을 따르는 문서를 출력하며, 각 문서에는 apiVersion, kind, provenance(커밋 및 읽은 파일과 다이제스트)가 포함됩니다. 텍스트 출력을 파싱하는 대신 이 출력을 읽고, 조건의 message가 아닌 reason을 기준으로 분기하세요. atlas check --format sarif는 코드 스캐닝 및 IDE 뷰어를 위한 SARIF 2.1.0 형식으로 발견 결과를 제공합니다. atlas export arazzo는 API 워크플로우 및 E2E 도구를 위한 Arazzo 1.0 형식으로 플로우를 제공하며, 여전히 매개변수, 요청 본문 및 성공 기준을 채워야 합니다.
출력 읽기
- 발견 결과 상태:
new는 사용자의 것,baseline은 수용된 부채,excepted는 처리됨,expired-exception은 사람의 검토가 필요함을 의미합니다. - 트레이스에서
=는 호출을 메서드와 경로로 표면에 연결합니다.~는 라우트를 해당 핸들러가 실행하는 아웃바운드 호출에 연결합니다: 핸들러의 자체 코드 또는 호출하는 함수(증거static), 또는 핸들러가 호출하는 이름의 메서드에 보관된 경우(증거name), Spring 페이지의 경우 뷰 이름이 렌더링하는 템플릿에 의해 만들어진 경우(via view <name>). 일반적인 이름(get,send)을 통한~는 코드를 확인해야 합니다. - 호출의
in <name>은 문자열을 보유한 함수입니다. 오류 레이블이나 로그 메시지의 문자열은 경로처럼 보여도 요청이 아닙니다. 범위(scope)가 일반적으로 이를 보여줍니다. - 설정된 파일만 읽히며, 그 중에서도 확실하게 작성된 내용만 읽힙니다: 리터럴 경로와 표준 또는 프레임워크가 부여한 의미를 가진 것들입니다. 변수, 다른 템플릿 엔진, htmx 또는 Vue 속성의 URL은 읽히지 않으며 추측되지 않습니다. 따라서 "호출자 없음"은
atlas가 읽을 수 있는 호출자가 없다는 의미입니다. 아무것도 제거하기 전에 코드를 확인하고, 저장소 외부에서 제공되는 표면은publicSurfaces에 선언하세요. 발견 결과가 없다고 플로우가 완전하다는 증명이 되지는 않습니다.
참조
- 경계 해석, 결함/계획/오탐 결정:
references/boundaries.md - 규칙, 원인, 해결 방법, 예외가 적합한 경우:
references/rules.md - 설정 작성 또는 수정:
references/config.md - 프레임워크의 생성된 OpenAPI 문서에서 라우트 읽기 및 생성 방법:
references/openapi.md