참조 페이지에서 쓰기 가능한 유일한 영역은 'Orientation Slots'입니다

인터페이스 사실(interface facts)을 추출하고 잠가 놓기 전에 모델이 주변에 설명 문구(orientation prose)를 작성하더라도 참조 문서가 신뢰성을 유지할 수 있습니다. 블록-역할 매니페스트(block-role manifest)는 초안 작성이 시작되기 전에 이러한 분리를 기록하므로, 검토 과정이 눈으로 상상된 플래그를 잡아내는 것에 의존하지 않습니다. 결정론적 추출(Deterministic extraction)은 시그니처(signatures), 플래그(flags), 환경 변수(environment variables), 오류 코드(error codes)와 같은 요소를 소유하며, 모델은 표시된 방향성 슬롯(orientation slots)만 채울 수 있습니다. 이 글의 후반부에서 소개할 검사기(checker)는 작성된 문구에 잠긴 인벤토리(locked inventory)가 포함하지 않는 인터페이스 토큰이 언급될 경우 해당 페이지를 실패 처리합니다.

참조 페이지 초안을 작성하는 모델들은 종종 누락된 행을 그럴듯한 플래그, 상태 또는 기본값으로 상상하여 채웁니다. 이러한 실패는 약한 설명과는 다릅니다. 왜냐하면 문장은 유창해 보이지만 실제 계약(contract) 자체가 거짓이기 때문입니다. 여러 엔드포인트가 하나의 풀 리퀘스트(pull request)를 공유하고 각 페이지가 표와 서술을 혼합할 경우, 전체 페이지 검토는 확장성이 떨어집니다. 모든 블록에 역할 태그(role tag)를 지정하면 허용되는 초안 표면이 스크립트가 다시 읽지 않고도 확인할 수 있을 만큼 작아집니다.

하나의 헤딩(heading) 안에 생성된 플래그 테이블과 조언 단락이 모두 포함되어 있다면, 단순히 헤딩 수준의 소유권만으로는 충분하지 않습니다. 여기서 제어 단위는 파일이나 헤딩이 아니라 블록(block)입니다. 왜냐하면 더 큰 단위들은 혼합된 권한을 숨기기 때문입니다. 어조에 대한 스타일 약속(style promise) 역시 모델이 출시된 적 없는 플래그를 추가하는 것을 막지 못합니다. 따라서 매니페스트는 구체적인 토큰(concrete tokens)의 이름을 지정하며, 검사기는 작성된 문장들을 그 폐쇄된 토큰 세트와 비교합니다.

모델이 초안을 작성할 수 있는 내용

모델은 시퀀싱(sequencing), 선행 조건(prerequisites)을 일반 언어로 설명하고 잠긴 행(locked row)의 흔한 오해를 풀이하는 'Orientation Slots' 초안을 작성할 수 있습니다. 해당 슬롯들은 두 개의 문서화된 플래그가 모두 해당 페이지의 인벤토리(inventory)에 이미 나타날 때만 두 플래그를 비교할 수 있습니다. 또한, 모든 구체적인 토큰(concrete token)이 이미 나열되어 있다면, 작업을 호출하지 말아야 할 시점에 대한 짧은 메모도 제안할 수 있습니다. '요청(request)', '클라이언트(client)', '재시도(retry)'와 같은 일반 단어는 허용되지만, 제품별 특정 토큰(product-specific tokens)은 초안 작성 전에 반드시 나열되어야 합니다.

Orientation 텍스트는 기본값(default), 타입(type), 또는 상태 코드(status code)를 재진술하기보다는 잠긴 행의 표면(surface)을 사용해야 합니다. 이러한 필드를 재진술하는 것은 첫 번째 초안이 아무리 신중했더라도 다음 릴리스에서 벗어날 수 있는 두 번째 진실 공급원(second source of truth)을 만듭니다. 문장에 기본값이 필요한 경우, 페이지는 작성된 단락(drafted paragraph)이 아닌 인벤토리로부터 해당 기본값을 렌더링해야 합니다. 초안 작성 프롬프트는 자유 형식의 글쓰기 캔버스(free-form writing canvas)가 아니라 슬롯 ID와 허용 가능한 표면을 받아야 합니다.

인간이 소유해야 할 것들

인간은 그 출처가 OpenAPI 문서, 캡처된 도움말 파일, 또는 오류 카탈로그 중 무엇이든 관계없이 인벤토리(inventory) 출처를 소유해야 합니다. 인간은 상태 매핑(status mappings), 기본값(default values), 사용 중단 마커(deprecation markers), 그리고 주어진 토큰이 공개적인지 여부에 대한 결정을 소유해야 합니다. 인간은 각 Orientation Slot이 존재하기 전에 승인해야 하는데, 추가 슬롯 하나는 범위(scope)를 발명할 수 있는 추가 장소이기 때문입니다. 또한, 모델이 주변의 산문(prose)을 다듬으면서 잠긴 블록(locked block)을 다시 작성하는 것을 막기 위해 추출된 표(tables)도 페이지에 병합해야 합니다.

소유권은 독자가 최종적으로 게시된 페이지에서 보게 될 모든 문장을 직접 타이핑하는 것과는 같은 것이 아닙니다. 인간은 스크립트에 추출 작업을 위임할 수 있고, 그 후 어떤 산문 작업이 실행되기 전에 인벤토리 차이(inventory diff)를 검토할 수 있습니다. 위임될 수 없는 것은 토큰을 문서화하기에 안전한지, 이름을 붙일 만큼 안정적인지, 그리고 올바르게 범위가 지정되었는지에 대한 판단입니다. 만약 이 판단이 누락된다면, 초안 작성 과정은 이를 만들지 못하며, 검사기(checker)는 단지 그 발명이 일관성이 있었는지 여부만을 확인할 것입니다.

단계별 워크플로우

여섯 단계를 순서대로 따르고, 각 아티팩트를 선택적 메모가 아닌 다음 입력값으로 취급해야 합니다. lock 파일을 건너뛰고 전체 페이지를 요청하는 것은 마치 꾸며낸 플래그들이 그렇지 않은 신중한 저장소에 재진입하는 방식과 같습니다. 아래의 명령어와 파일들은 제안된 워크플로우이며, 실제 프로덕션 문서 세트에 대한 실행 기록이 아닙니다. 샘플 명령어 이름을 팀이 이미 인터페이스 소스로 취급하는 바이너리나 스펙으로 대체하십시오.

1. 인터페이스 인벤토리 캡처

참조 페이지당 하나의 인벤토리 파일을 저장하고, 그 파일이 해당 페이지가 명명할 수 있는 공개 토큰의 유일한 목록으로 간주해야 합니다. 결정론적인 명령어(deterministic command)를 사용하여 도움말 텍스트나 스펙 발췌본을 캡처한 다음, 이 캡처를 사람이 검토하는 토큰 파일로 변환합니다. 아무리 스펙이 길거나 어색하게 포맷되어 있어도 모델에게 스펙을 인벤토리로 전사(transcribe)하도록 요청하지 마십시오. 전사 과정은 필수 필드를 누락시킬 수 있으며, 소스를 열어보지 않은 검토자에게는 여전히 완벽해 보일 수 있습니다.

mkdir -p docs/inventory docs/pages docs/slots docs/fixtures tools
# 캡처 제안. mycli를 팀이 실제로 배포하는 바이너리로 대체하십시오.
mycli --help > docs/inventory/mycli-help.txt

{
  "page_id": "export-job",
  "source_capture": "docs/inventory/mycli-help.txt",
...
}

소스가 OpenAPI인 경우, 팀이 이미 신뢰하는 파서(parser)를 사용하여 작업 ID(operation ids), 매개변수(parameters), 그리고 응답 코드(response codes)를 추출하십시오. 검토자가 파서가 무엇을 누락시키거나 이름을 변경했는지 볼 수 있도록 원본 캡처를 토큰 파일 옆에 보관하십시오. 원본 캡처와 토큰 파일을 같은 변경 사항(change)에 커밋하고, 일치하는 캡처가 없는 토큰 파일은 거부하십시오. 이 단계는 사람이 각 토큰을 공개(public), 내부(internal), 또는 페이지에서 제외됨(omitted)으로 표시할 때만 완료됩니다.

2. 블록-역할 매니페스트 작성

매니페스트(manifest)는 추출(extraction)과 초안 작성(drafting) 사이의 계약이며, 산문처럼 보기보다는 스키마 변경처럼 검토해야 합니다. 각 블록은 '추출' 또는 '배치(orient)' 역할을 가지며, 해당 역할이 언급할 수 있는 토큰 ID를 포함합니다. 추출 블록은 토큰 파일에서 렌더링되며 쓰기 가능한 텍스트로 모델에 전송되지 않습니다. 배치 블록만이 초안 작성 작업이 대체할 수 있는 유일한 영역이며, 각 블록에는 단어 제한(word cap)이 있습니다.

# docs/inventory/export-job.manifest.yaml
# 제안된 예시입니다. 캡처된 프로덕션 파일은 아닙니다.
page_id: export-job
...

표면 목록(surface list)은 문장이 토큰을 위해 사용할 수 있는 철자들의 집합이며, 샘플은 이러한 철자들을 구별되게 유지합니다. 예를 들어 이름이 붙은 오류 구문과 같은 다중 단어 표면은 그 목록에 포함되어야 하며, 그래야 검사기가 주변의 임의적인 발명을 허용하지 않으면서도 해당 구문을 허용할 수 있습니다. allowed_token_ids를 좁게 유지하세요. 왜냐하면 페이지의 모든 토큰을 이름 지을 수 있는 슬롯은 전체 페이지 프롬프트만큼이나 느슨하기 때문입니다. 만약 두 개의 슬롯이 동일한 플래그가 필요하다면, 전체 페이지를 포괄하는 하나의 큰 슬롯을 만드는 것보다 양쪽에 해당 플래그를 나열하는 것이 좋습니다.

3. 인벤토리 해시 잠금(Lock the inventory hash)

사용자가 토큰 파일을 승인한 후 해시를 계산하고, 어떤 슬롯도 초안 작성되기 전에 그 해시를 매니페스트에 저장해야 합니다. 이 해시는 산문 작업과 특정 인벤토리를 연결하므로, 조용한 편집(quiet edit)으로는 이전 초안 아래의 계약을 변경할 수 없습니다. 토큰 파일이 변경되면, 사용자가 의도적으로 동일한 커밋에서 매니페스트를 업데이트하기 전까지는 해시 검사에 실패합니다. 이러한 실패는 유용합니다. 왜냐하면 배치 작업은 인터페이스가 이동할 때 스스로 재작성되는 대신 멈춰야 하기 때문입니다.

python3 - <<'PY'
import hashlib
import pathlib
...

인쇄된 요약본을 inventory_sha256에 붙여넣고, 초안 작성 스크립트가 해당 필드를 자동으로 업데이트하도록 두지 마십시오. 자동 해시 업데이트는 검토 과정에서 잠금(lock)이 표시하려는 바로 그 수정을 숨길 것입니다. 검토자는 먼저 토큰 차이(token diff)를 살펴본 후, 새로운 요약본을 별도의 결정으로 승인하거나 거부해야 합니다. 그러한 결정이 내려진 후에야만 누군가 허용된 토큰이 변경된 슬롯에 대한 새로운 방향성 초안 일정을 잡아야 합니다.

4. 방향성 슬롯만 초안 작성하기

모델에게 슬롯 ID, 단어 제한(word cap), 그리고 허용된 표면(allowed surfaces)을 전송하고 해당 슬롯만을 요청하십시오. 참조 페이지, 서론, 예시를 한 번에 작성하라는 요청은 보내지 마십시오. 좁은 프롬프트는 모델이 단순히 표와 일관성 있게 들리는 형제 플래그(sibling flag)를 추가할 가능성을 줄여줍니다. 결과를 블록 ID로 이름 붙인 슬롯 파일 아래 저장하고, 모든 추출 블록은 해당 작업에 의해 건드리지 않도록 하십시오.

Draft slot sequencing only.
Allowed surfaces: --out, --since, EXPORT_PARTIAL, partial export.
Do not name any other flag, environment variable, status, or error code.
...

초안 작성 도구가 이 단계에 유용하다면, 인벤토리 해시가 이미 커밋된 후에도 슬롯 텍스트에만 유지하십시오. MonkeyCode의 무료 모델 액세스로는 승인된 방향성 슬롯을 초안 작성할 수 있으며, 무료 서버 옵션으로는 해시 단계와 검사기(checker)를 실행할 수 있습니다.

공개: 이 문서는 MonkeyCode의 제품 홍보의 일환으로 준비되었습니다.

이 문서는 특정 모델 이름, 할당량, 하드웨어 크기, 시간 제한 또는 해당 설정에 대한 벤치마크 결과를 주장하지 않습니다. 페이지는 이러한 옵션 없이도 유용합니다. 왜냐하면 매니페스트(manifest), 해시(hash), 그리고 검사기는 일반적인 리포지토리 파일이기 때문입니다. 로컬 Python 설치만으로도 호스팅된 러너가 관여하기 전에 게이트를 연습하는 것이 충분합니다. 호스팅 옵션은 이미 지정된 단계에 대한 배치 선택일 뿐, 인터페이스 사실의 원천이 아닙니다.

5. 역할로부터 페이지 렌더링하기

렌더러는 모델에게 페이지 조립을 요청하지 않고 추출된 테이블과 오리엔테이션 파일을 매니페스트 순서대로 연결해야 합니다. 또한, 슬롯 파일은 초안(draft)이 잠긴 영역을 덮어썼다는 증거가 되므로, 추출 블록에 대한 슬롯 파일 읽기를 거부해야 합니다. 마찬가지로, 빈 공간을 생성된 산문으로 채우기보다는, 슬롯 파일이 누락된 오리엔테이션 블록의 렌더링도 거부해야 합니다. 누락된 산문은 사람이 채울 수 있는 눈에 보이는 공백이지만, 침묵적인 생성(silent generation)은 승인된 슬롯 텍스트가 존재하지 않았다는 사실을 숨깁니다.

6. 토큰 검사기 실행하기

검사기는 허용된 표면(allowed surfaces)들을 로드하고, 오리엔테이션 파일에서 알 수 없는 인터페이스형 토큰을 거부하며, 산문을 읽기 전에 인벤토리 해시를 확인합니다. 이는 제안되었지만 아직 실행되지 않은 예시이므로, 그 결과를 측정된 결과라기보다는 게이트(gate)에 대한 사양으로 간주해야 합니다. 이 스크립트는 PyYAML에 의존하며, 그 외에는 표준 라이브러리만을 사용하고 모델이나 네트워크 서비스와는 절대 통신하지 않습니다. 페이지를 빌드하는 것과 같은 작업에서 실행하고, 종료 코드가 0이 아니면 출판을 차단해야 합니다.

#!/usr/bin/env python3
"""오리엔테이션 슬롯에 대한 제안된, 미실행 검사기.

...

성공하는 슬롯은 허용된 표면만을 사용하며 매니페스트에서 해당 블록에 기록된 단어 제한(word cap)을 초과하지 않습니다. 실패하는 슬롯은 해당 슬롯의 표면 목록에 절대 나타나지 않는 플래그 또는 오류 상수를 명시합니다. 아래 샘플 실패 사례는 gzip 플래그와 export timeout 상수를 사용하는데, 이 둘 다 샘플 인벤토리에는 존재하지 않습니다. 이러한 실패한 장치(failing fixture)를 대상으로 검사기는 0이 아닌 값으로 종료하고 목록에 없는 모든 플래그나 상수를 출력하도록 지정되어 있습니다.

Write the archive with --out, then narrow the window with --since.
If the job reports EXPORT_PARTIAL, rerun only after the source is complete.
Do not treat a partial export as a finished archive.

<!-- Proposed failing fixture. Keep it outside docs/slots until you want a red build. -->
Pass --gzip when the archive is large, and set EXPORT_TIMEOUT if the network is slow.

python3 tools/check_orientation_slots.py \
  docs/inventory/export-job.manifest.yaml \
  docs/inventory/export-job.tokens.json \
...

검사기 실패 읽는 방법

실패를 전체 페이지를 재생성하고 다음 초안이 더 깨끗하기를 바라는 제안으로 읽지 마십시오. 아래 표는 일반적인 신호를 수정해야 하는 역할과 행동해야 할 사람 또는 도구에 매핑합니다. 이 표를 검토 중에 사용하면 모델에게 사람이 여전히 소유해야 하는 행을 수리하도록 요청하는 것을 방지할 수 있습니다. 만약 표와 검사기가 의견이 다르면, 프롬프트를 넓혀 게이트를 침묵시키기보다 인벤토리(inventory)를 신뢰하고 검사기를 수정하십시오.

게이트의 한계 (Limitations of the gate)

단어 경계 및 힌트 일치는 토큰을 회피하는 발명품, 예를 들어 이름을 지정하지 않고 선택적 경로 인수를 추가하는 문장 같은 것을 놓칩니다. 실제 플래그는 새로운 토큰을 도입하지 않고도 잘못 설명될 수 있으므로, 인간은 여전히 모든 오리엔테이션 슬롯(orientation slot)을 읽어야 합니다. 구문 검색(Phrase search)은 표면이 일반 단어일 때 거짓 양성(false-positive)일 수 있으므로, 인터페이스가 제공하는 경우 항상 식별적인 철자를 선호하십시오. 검사기는 보안 주장, 법률 문구, 지원 약속 또는 공개 토큰이었어야 하는지 여부를 검토하지 않습니다.