다른 언어: English, Español, Português, 日本語, Deutsch, Français, 简体中文, Italiano, हिन्दी · 한국어 가이드 전체
공개: 저희는 100monkeys.ai에서 Carbon Forge를 만들고 있으므로 이 글은 만든 쪽의 설명으로 읽어 주세요. 이 가이드는 저희 AI 에이전트 하나가 공개 문서(영어), 주로 MCP tools catalog: Semantics의 symbols.drift와 Governed seams 절, 그리고 The Carbon paradigm의 "Drift between prose and code"를 바탕으로 초안을 쓰고 회사가 검토했으며, 이 한국어판은 영어 원문 가이드의 번역입니다. 표와 호출은 문서 자체의 예시이고, 인용은 영어 원문 옆에 번역을 붙였습니다. 문서가 답하지 않은 질문은 마지막 절에서 밝힙니다.
보고서는 무엇인가
패러다임 페이지의 한 줄: "A workspace's reserved .governed-seams page declares which pages govern which definitions of a code tree"(워크스페이스의 예약된 .governed-seams 페이지는 어떤 페이지가 코드 트리의 어떤 정의를 다스리는지 선언합니다). symbols.drift는 "joins every definition a lane adds, removes or re-signs to the seams that govern it and reports each as changed with or without a patch to its governing page on the same lane, from the syntax index alone, so the same lane and the same seams page answer the same report byte for byte."(lane이 추가하거나, 지우거나, 시그니처를 바꾸는 모든 정의를 그것을 다스리는 seam에 연결하고, 각각을 같은 lane에서 다스리는 페이지에 대한 패치와 함께 또는 없이 바뀐 것으로 보고합니다. 구문 인덱스만으로 하므로, 같은 lane과 같은 seams 페이지는 바이트 단위로 같은 보고서를 답합니다.) 어떤 모델도 무엇을 읽지 않습니다. 그리고 기억해 둘 한계 하나: "The report advises and never refuses a landing."(보고서는 조언할 뿐 랜딩을 거부하지 않습니다.)
1단계. 페이지가 설명하는 정의 고르기
코드가 그 아래서 움직이면 독자를 오도할 페이지부터 시작하세요. 결제에 관한 아키텍처 페이지, 로그인 가이드 같은 것입니다. 그 페이지들이 설명하는 정의를 시맨틱 인덱스로 찾습니다.
symbols.search { "tree": "app", "query": "charge", "prefix": true }정의는 TypeScript와 TSX, JavaScript, Python, Go, Rust, C, C++, C#, Java, Ruby, PHP, Scala, Bash에 대한 tree-sitter의 tags 쿼리에서 나옵니다. CSS, HTML, JSON, YAML, TOML, HCL은 구문 트리를 얻지만 "but no definitions or references"(정의나 참조는 없으므로), 그런 파일에 대한 seam은 아무것도 보고하지 않습니다. 이름은 "matched by name, not by type checking"(타입 검사가 아니라 이름으로 매칭됩니다).
2단계. .governed-seams 페이지 쓰기
예약된 경로 .governed-seams에 페이지를 만들고, 첫 번째 Markdown 표의 머리를 tree | glob | symbols | records로 하세요. 문서의 예시:
| tree | glob | symbols | records |
| --- | --- | --- | --- |
| app | src/billing/** | chargeCard, refund | architecture/billing |
| app | src/auth/*.ts | * | guides/login, architecture/security |tree: 코드 트리의 경로.glob: 트리의 파일 경로에 대한 import ignore 규칙 문법의 규칙 하나.!로 시작하지 않습니다.symbols: 쉼표로 구분한 정의 이름들, 또는 glob 아래의 모든 정의를 뜻하는*하나.records: 쉼표로 구분한 페이지 경로들. 그 정의를 다스리는 페이지입니다.
"A seam is declared, never inferred: no link, tag, metadata key or embedding makes one."(seam은 선언되며 추론되지 않습니다. 링크, 태그, 메타데이터 키, 임베딩 그 어느 것도 seam을 만들지 않습니다.) 페이지는 trunk에서 읽히므로 "so a lane cannot ungovern its own change."(lane이 자기 변경을 다스림에서 빼낼 수 없습니다.) 지켜볼 작업보다 먼저 trunk에 랜딩하세요. 형식이 잘못된 페이지는 고칠 때까지 모든 보고서를 멈추며, 그 줄을 밝히는 문장을 냅니다. The governed seams page .governed-seams is malformed at line <n>, ...
3단계. lane에서 다스려지는 코드 바꾸기
보고서는 lane을 읽으므로 변경은 lane 위에 있어야 합니다. Working in lanes가 보여 주듯 lanes.create, 그다음 lane을 붙인 trees.apply_patch나 trees.put입니다. 예를 들어 매개변수를 하나 추가해 chargeCard의 시그니처를 바꿔 보세요.
4단계. drift 보고서 읽기
symbols.drift { "lane": "agent/7/fix-login" }트리 하나만 읽으려면 tree를 추가하세요. 답은 이렇습니다.
{ lane, composition_hash, report_sha256, findings, pending, governed_rows }각 발견 사항은 tree, path, symbol, kind, trunk의 from_signature와 lane의 to_signature(어느 쪽에 없으면 null), { path, updated_on_lane } 형태의 records, 그리고 lane에서 그 이름에 대한 참조 수인 callers를 밝힙니다. class가 판정입니다. lane에 다스리는 페이지에 대한 살아 있는 패치가 없으면 seam_changed_without_record. 그것이 여러분의 낡은 문서이며, 랜딩 전에 잡힌 것입니다.
빈 보고서를 믿기 전에 pending을 읽으세요. seam의 glob 아래에서 바뀌었지만 인덱스가 "cannot answer yet"(아직 답할 수 없는) 파일을 나열하며, "the report is complete when pending is empty."(pending이 비어 있을 때 보고서가 완전합니다.) 충돌 상태의 lane은 충돌이 해결될 때까지 거부됩니다.
5단계. 같은 lane에서 다스리는 페이지 고치기
pages.apply_patch와 같은 lane으로 architecture/billing을 고치면, 페이지와 코드가 함께 기다립니다. 코드 변경과 그 문서를 하나의 changeset으로 랜딩하기 가이드가 그 부분을 따라갑니다.
6단계. 보고서를 다시 읽고 랜딩하기
symbols.drift를 다시 실행하세요. 이제 발견 사항은 seam_changed_with_record이고, 그 record는 updated_on_lane을 보여 줍니다. 보고서를 리뷰와 함께 보관하세요. composition_hash는 보고서가 읽은 lane 구성의 해시이고, report_sha256은 보고서의 정규 텍스트를 덮으므로, "so a report is bound to the exact change it read."(보고서는 그것이 읽은 정확한 변경에 묶입니다.) 이후의 패치는 둘 다 바꿉니다. 그런 다음 lane을 하나의 changeset으로 랜딩합니다.
보고서는 조언만 하므로, 강제하는 일은 여러분이 더해야 합니다. 문서가 아니라 저희가 제안하는 한 가지 패턴: 보호된 trunk에서 .landing-rules에 다스려지는 코드의 glob을 적고 다스리는 페이지의 소유자를 승인자로 지정한 뒤, 그 승인자가 먼저 drift 보고서를 읽게 하세요.
문서가 답하지 않는 것
- 누가
.governed-seams를 쓸 수 있는지. 문서는.landing-rules를 관리자 전용으로 하지만, seams 페이지에 대해서는 "whoever wrote it"(누가 썼든) trunk에서 읽힌다고만 말합니다. - 앱의 화면. 문서는 도구와 그 답을 설명할 뿐, 보고서를 보여 주는 브라우저 페이지는 설명하지 않습니다.
- Markdown은 "not parsed yet"(아직 파싱되지 않으므로), 페이지 자체가 다스려지는 쪽이 될 수는 없습니다.