기여자 가이드 초안 작성 전 레포지토리 계약서 확정하기

생성된 기여자 페이지는 모델이 소유자(owners), 비밀 정보(secrets), 라이선스 의무(license duties)를 임의로 생성하도록 허용될 경우 실패합니다. 팀은 어떠한 오리엔테이션 서사도 작성되기 전에 레포지토리 계약서에서 이러한 사실들을 확정해야 합니다. 모델은 기존 계약 항목을 일반 언어로 설명할 수는 있지만, 새로운 항목을 만들 수는 없습니다. 로컬 검사기(local checker)는 따라서 누락된 식별자(identifiers)를 인용하거나 지원되지 않는 제품 주장을 삽입하는 초안을 거부할 수 있습니다.

이러한 분리는 중요합니다. 온보딩 텍스트는 아무도 그 숨겨진 가정을 검토하지 않았더라도 권위적으로 보일 수 있기 때문입니다. 새로운 기여자는 생성된 경로 소유자(path owner)를 실제 검토 규칙인 것처럼 취급할 수 있습니다. 같은 독자가 오류를 아무도 알아차리지 못하는 사이에 생성된 비밀 위치(secret location)를 셸 스크립트(shell script)에 복사해 넣을 수도 있습니다. 계약 파일은 이러한 영향력이 큰 줄들을 명시적이고, 검토 가능하며, 일반적인 산문 스타일 선택과 분리하여 유지합니다.

공개 초안 도구들은 이 특정 실패를 생산하는 비용을 낮추고 눈에 띄지 않게 병합하기 쉽게 만들었습니다. 짧은 프롬프트만으로도 평범한 README 파일을 비정상적으로 구체적인 느낌의 환영 가이드로 확장할 수 있습니다. 구체성이 소유권(custody)과 같지는 않습니다. 왜냐하면 유창한 문장이라도 어떤 인간도 승인하지 않은 경로를 이름 지을 수 있기 때문입니다. 아래 워크플로우는 소유권을 검토된 파일로 취급하고, 유창성은 나중 단계에서 처리합니다.

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

모델은 계약서에 이미 존재하는 식별자들을 인용하는 전환(transitions), 정의(definitions), 단계 설명 등을 초안 작성할 수 있습니다. 또한 헤딩 순서, 용어집 의역, 그리고 짧은 다음 볼 곳(where-to-look-next) 마무리를 제안할 수도 있습니다. 이러한 초안들은 검토 도구가 소유된 사실들과 분리하여 스캔할 수 있도록 표시된 섹션 안에 유지되어야 합니다. 만약 문장이 새로운 소유자, 비밀 정보, 라이선스 또는 버전을 필요로 한다면, 모델은 멈추고 공백을 남겨두어야 합니다.

그 경계는 전체 온보딩 페이지를 처음부터 작성해 달라는 포괄적인 요청보다는 좁습니다. 서사적 도움(Narrative help)은 문장의 모든 구체 명사가 이미 식별자일 때만 허용됩니다. 허용되는 문장에는 [[cmd-test]]에 대한 포인터나 독자가 다음에 [[lic-apache]]를 열어봐야 한다는 짧은 알림이 포함됩니다. 금지된 문장에는 새로운 지원 창, 새로운 토큰 할당량, 그리고 어떤 서비스가 무료라는 새로운 주장 등이 포함됩니다.

아래의 검사기는 쉬운 경우들을 강제하고 더 어려운 판단은 지정된 인간 소유자에게 맡깁니다. 이 검사기는 의도를 이해하지 못하며, 새로운 사실을 요청하는 프롬프트를 구제해 주지 않습니다. 리뷰어들은 여전히 초안을 읽어야 합니다. 왜냐하면 깨끗한 인용(citation)이 오도하는 동사 옆에 놓일 수 있기 때문입니다.

인간이 소유해야 할 것들

인간 소유자는 경로 소유권, 비밀 이름, 라이선스 식별자, 그리고 새로운 기여자가 실행할 것으로 예상되는 명령어들을 고정해야 합니다. 동일한 사람 또는 지정된 대리인이 초안에 어떤 버전 문자열이 나타날 수 있는지 고정해야 합니다. 여기서 소유권이란 문서를 이미 검토했다는 모호한 메모가 아니라 계약을 변경할 권리를 의미합니다. 소유자 스탬프는 계약 파일과 페이지 내 인간 소유 헤딩 옆에 다시 위치해야 합니다.

인간은 또한 법적, 보안적 또는 지원 동작이 잘못될 경우 변경될 수 있는 모든 문장들을 소유해야 합니다. 이 세트에는 자격 증명이 어디에 있는지, 어떤 파일들이 검토가 필요한지, 그리고 실제로 적용되는 라이선스 텍스트가 무엇인지가 포함됩니다. 모델은 아래 아티팩트에 정의된 인용 표시를 사용하여 해당 행들을 재진술할 수 있습니다. 하지만 생성된 문구가 표보다 더 세련되게 들리더라도 그 행들의 출처가 될 수는 없습니다.

허가 경계

표는 스타일 가이드가 아니라 권한 경계로 읽어주십시오. 인간이 담당하도록 표시된 행은 모델이 그럴듯한 값을 추측할 수 있더라도 계약서에 유지됩니다. 모델이 담당하는 행의 경우, 구체적인 레포지토리 사실을 언급할 때는 반드시 식별자를 인용해야 합니다. 체커는 표면 패턴으로 볼 수 있는 행만 구현하므로, 이 표가 편집 규칙으로 남아 있습니다.

제안된 아티팩트

다음 파일들은 제안된 로컬 체크이며, 이 글을 작성하는 동안 실행되지 않았습니다. 이 예제들은 tomllib가 해당 버전부터 표준 라이브러리에 포함되기 때문에 Python 3.11을 사용합니다. 인용 표시는 [[own-docs]]와 같은 이중 대괄호 식별자이며, grep으로 찾기 쉽고 Markdown 링크와 혼동하기 어렵습니다. 패턴들을 글이 사실임을 증명하는 것이 아니라 시작점(starting gate)으로 간주해야 합니다.

계약 파일, repo-contract.toml:

owner = "docs-platform"
reviewed = "2026-10-09"

...

체커, check_orientation.py:

#!/usr/bin/env python3
"""제안된 게이트. 이 글을 위해 실행되지 않았습니다."""

...

샘플 페이지 조각, docs/orientation.md:

## 인간 소유 계약

owner: docs-platform
...

검토자가 나중에 저장하고 실행할 수 있는 명령어들:

python3 check_orientation.py repo-contract.toml docs/orientation.md
git diff -- repo-contract.toml docs/orientation.md

첫 번째 명령어는 인용 게이트이며, 본문만 검토하는 경우 diff에서 변경된 owner 행을 놓칠 수 있습니다. 이 글에 대해서는 어떤 명령어도 실행되지 않았으므로, 측정된 결과라기보다는 실험 스케치(lab sketch)로 복사하십시오. 유용한 부정 사례(negative case)는 [[own-missing]]를 인용하거나 allowed_versions 외부의 버전을 출력하는 초안이며, 이는 0이 아닌 값으로 종료되어야 합니다. 나중에 편집할 때 인용 규칙이 조용히 사라지지 않도록 그 실패하는 페이지를 스크립트 옆에 보관하십시오.

번호가 매겨진 워크플로우

1. 이름이 지정된 사람이 repo-contract.toml 파일을 작성하며, 여기에는 소유자(owners), 비밀 규칙(secret rules), 라이선스 식별자(license identifiers) 및 예상되는 명령어들이 포함됩니다. 각 행은 나중에 서술에서 해당 사실을 인용할 때 조용히 이름을 변경하지 않도록 안정적인 ID가 필요합니다. 소유자 필드는 검토 후 해당 행들을 변경할 수 있는 사람이나 팀의 이름을 지정합니다. 서술에 나타날 수 있는 버전들은 allowed_versions에 넣고, 다른 모든 버전 문자열은 실패(fail closed)해야 합니다.

2. 같은 사람이 출판하고자 하는 행들만 'Human-owned contract'라는 페이지 섹션에 붙여넣습니다. 이 섹션에는 또한 검사기(checker)가 초안 위에 찾을 것으로 예상하는 소유자 스탬프가 있습니다. 이 스탬프는 암호화 서명이 아니라 검토 처리(review handle)이므로, 실제 승인은 여전히 풀 리퀘스트(pull request)에 존재합니다. 만약 스탬프와 계약 소유자가 일치하지 않으면, 검사기는 실패하고 페이지는 병합되어서는 안 됩니다.

3. 해당 계약 파일이 확정된 후에야 모델에게 서술 섹션을 초안 작성하도록 요청해야 합니다. 프롬프트에는 계약 텍스트가 포함되어야 하며, 새로운 식별자, 새로운 버전, 그리고 어떠한 가용성 또는 가격 책정 언어도 금지해야 합니다. 검사기가 어떤 행을 사용했는지 알 수 있도록 [[id]] 형식으로 인용을 요청하세요. 만약 모델이 누락된 행 없이 단계를 설명할 수 없다면, 추측하는 대신 질문을 반환해야 합니다.

4. 저장소에서 검사기를 실행한 다음, 서술의 변경 사항과 계약의 변경 사항을 분리하여 읽으세요. 녹색 체크 표시는 인용과 몇 가지 금지된 단어가 범위 내에 있다는 것을 의미할 뿐이며, 명령이 깨끗한 환경에서도 여전히 성공한다는 것을 의미하지는 않습니다. 페이지가 신규 사용자가 실행할 수 있다고 주장하는 경우, 해당 계약 명령어들은 직접 실행해봐야 합니다. 만약 검토 과정에서 명령어, 소유자 또는 라이선스 행 중 하나가 변경되었다면, 먼저 계약을 업데이트해야 합니다.

무료 초안 작성 작업 공간의 활용 방안

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

MonkeyCode는 무료 모델 접근 및 무료 서버 옵션을 가진 초안 작성 워크스페이스로만 이 워크플로우에 진입합니다. 이 두 가지 가용성 주장은 계약 파일이 로컬에 존재하는 후 호스팅된 워크스페이스에서 내러티브 단계를 배치하기에 충분합니다. 본 문서는 모델 이름, 토큰 할당량(token quotas), 하드웨어 크기, 서비스 지역 또는 기간을 명시하지 않습니다. 해당 세부 사항들은 안정적인 사실로 검증되지 않았으므로 작성된 방법 외부에 남아 있습니다.

실용적인 분할은 저장소에서 repo-contract.toml 파일을 편집한 다음, 그 고정된 파일만 초안 작성 세션에 붙여넣는 것입니다. 모델은 'Model draft' 섹션을 반환하고, 검사기(checker)는 병합 전에 CI 또는 로컬 셸에서 실행됩니다. 무료 서버가 해당 임시 세션을 유지할 수 있으므로 실험이 유료 워크스테이션을 요구하지 않습니다. 계약서, 소유자 도장(owner stamp), 그리고 녹색 체크 표시는 호스팅된 세션뿐만 아니라 저장소 기록에 속해야 합니다.

더 매끄러운 단락을 얻기 위해 운영 비밀(production secrets), 고객 이름 또는 미공개 보안 메모를 업로드하지 마십시오. 샘플 계약서는 로컬 방향이 운영 비밀을 사용하지 않는다고 의도적으로 명시하고 있으며, 그 규칙은 그대로 유지되어야 합니다. 무료 제공의 현재 약관이 불분명한 경우, 워크스페이스에 의존하기 전에 프로젝트 페이지에서 읽어보십시오. 게시된 약관은 변경될 수 있으며, 문서화 게이트는 어제의 한도가 오늘날의 한도라고 가정해서는 안 됩니다.

제한 사항 (Limitations)

정규 표현식(regular expressions)은 나열된 단어와 버전 형태의 숫자를 포착하지만, 동일한 주장을 암시하는 의역(paraphrases)은 놓칩니다. 문장은 '할당량'이라는 단어를 피하면서도 여전히 한도를 발명할 수 있으므로, 인간이 초안을 읽어야 합니다. 인용(Citations)은 식별자가 존재한다는 것을 증명할 뿐, 주변 동사가 해당 행에 적합한지까지는 아닙니다. 페이지는 [[cmd-test]]를 인용하면서도 다음 절에서 잘못된 예상 결과를 설명할 수 있습니다.

소유자 스탬프는 일반 텍스트이므로 편집자의 신원을 증명하지 못합니다. 이는 푸시 접근 권한을 가진 사람이 계약서와 페이지를 동시에 수정하는 것을 막지 못할 것입니다. 더 강력한 보관(custody)이 필요한 팀은 계약 소유자를 기존의 코드 검토 규칙에 매핑해야 합니다. Python 3.11보다 오래된 인터프리터는 다른 TOML 파서를 필요로 하며, 이 스케치에는 포함되어 있지 않습니다.

샘플은 여기서 실행되지 않았으므로, 스크립트의 결함이 여전히 트리에 남아 있을 수 있습니다. 파일을 임시 브랜치에 복사하고 좋은 페이지와 나쁜 페이지 모두를 대상으로 검사기를 실행하세요. 나쁜 페이지는 알 수 없는 인용(unknown citation)과 allowed_versions가 목록에 포함하지 않은 버전을 언급해야 합니다. 이 부정 테스트 케이스를 스크립트 옆에 보관하여 나중에 수정할 때 인용 게이트가 조용히 약화되는 것을 막아야 합니다.

누가 이것을 건너뛰어야 하는가

경로 소유자나 라이선스 파일이 변경될 때 아무도 계약서를 업데이트하지 않을 것이 확실하다면 이 게이트를 건너뛰세요. 오래된 계약서는 짧은 README보다 더 나쁩니다. 왜냐하면 검사기가 오래된 행을 인용하는 산문(prose)에 '승인'을 내릴 것이기 때문입니다. 보안 권고, 법적 약관, 지원 약속 등 이 패턴이 위험을 감당하기에는 너무 얕은 경우 건너뛰세요. 팀이 단지 문단을 완성하기 위해 호스팅된 모델에 실시간 자격 증명(live credentials)을 붙여넣어야 하는 경우에도 건너뛰세요.

또한 측정 가능한 품질 점수, 지연 시간 수치 또는 다른 어시스턴트와의 비교가 필요한 경우에도 건너뛰세요. 이 문서는 파일 레이아웃과 제안된 검사기를 제공할 뿐이며, 다른 어떤 도구에 대한 벤치마크는 아닙니다. 이미 생성된 모든 문장을 검토된 추출물(reviewed extract)에 바인딩하는 팀은 다른 인용 구문법을 가진 두 번째 게이트가 필요하지 않을 수 있습니다. 기여자 지향성(contributor orientation)이 흐트러지고 있고, 명시적인 사람이 계약서를 작게 유지할 수 있을 때 이 접근 방식을 사용하세요.

끝

레포지토리 계약을 확정하고, 인용된 방향 설명문만 초안 작성하며, 해당 파일 외부에 새로운 사실이 나타나면 페이지를 실패 처리하세요. 이 순서는 자유로운 초안 작성을 유용하게 유지하면서도 소유 경로 검토, 비밀 정보 또는 라이선스 식별은 허용하지 않습니다. 계약이 확정된 후 내러티브를 작성할 호스팅 공간을 원한다면, 해당 섹션만을 위한 작업 공간을 시도해 보세요. MonkeyCode의 무료 모델 액세스와 무료 서버 옵션은 현재 약관을 직접 확인한 후에 시작하기에 합리적인 장소입니다.