레시피 규약

레시피 규약

integration cookbook의 모든 실행 가능 레시피는 동일한 계약을 따릅니다. 이 페이지는 그 계약을 문서화해, 독자는 레시피에서 무엇을 기대할 수 있는지, 작성자는 레시피가 무엇을 충족해야 하는지 알 수 있습니다. 이 페이지는 설명형 문서로, 규약을 기록합니다. 집행은 이 페이지가 아니라 저장소 도구와 스타일 override 시트가 담당합니다.

각 통합의 자체 소스 저장소는 docs/public/ 아래에 레시피를 보관하며, aggregator가 이를 이 사이트로 가져옵니다. 아래 규약은 레시피가 어디에 있든 적용됩니다.

1. 샘플은 직접 입력한 조각이 아니라 실제 코드입니다

레시피의 코드는 본문에 직접 입력한 코드 조각이 아니라 저장소에 존재하는 실제 코드입니다.

• 다섯 줄보다 긴 모든 PHP 코드 블록은 해당 저장소의 examples/ 디렉터리 또는 tests/Cookbook/ 디렉터리에서 가져옵니다.
• 각 블록은 펜스 블록 정보 문자열에 자체 출처를 선언합니다. 예를 들어 title="examples/standalone.php"처럼 선언합니다.
• 대응하는 테스트는 예제가 여전히 컴파일되고 문서화된 출력을 생성하는지 검증하므로, 렌더링된 페이지가 표시하는 코드와 달라질 수 없습니다.

이 규약은 문서 스타일 override 시트 §3.4(“샘플은 실행 가능해야 한다”)에 해당합니다. 뒷받침하는 예제나 테스트 없이 코드를 보여 주는 레시피는 이 규약을 충족하지 않습니다.

2. 블록당 한 언어, 그리고 가시적인 오류 처리

• 펜스 코드 블록은 정확히 하나의 언어를 포함하며, 명시적으로 선언됩니다( ```php, ```bash, ```yaml, ```json). 언어 표시가 없는 펜스는 사용하지 않습니다.
• 프로덕션에서 사용할 수 있는 how-to로 표시된 레시피는 try / catch를 명시적으로 보여 주고, 단순한 \Exception 대신 적용 가능한 가장 구체적인 예외 유형을 잡으며, catch 블록에서는 독자가 그대로 가져다 쓸 수 있는 작업(로그, 재발생, 또는 정의된 오류 객체 반환)을 수행합니다. 빈 catch 블록은 사용하지 않습니다.
• HTTP 전송 통합의 경우, 레시피는 전송 실패와 성공이 아닌 HTTP 상태를 별개의 두 사례로 취급합니다. PSR-18 클라이언트는 요청을 보낼 수 없는 경우에만 타입이 지정된 클라이언트 예외를 발생시킵니다. 4xx 또는 5xx 응답은 레시피가 잡아야 할 예외가 아니라, 레시피가 검사해야 하는 정상적인 반환값입니다.

3. Reproducibility front-matter

각 레시피는 사이트 콘텐츠 스키마가 집행하는 §5.1 front-matter 계약을 사용해 출력이 얼마나 재현 가능한지 선언합니다. 관련 필드는 다음과 같습니다.

• reproducibility_profile — bitwise, structural, semantic 중 하나입니다. bitwise는 고정된 입력이 주어졌을 때 출력 바이트가 매번 실행할 때마다 동일하다는 뜻입니다. structural은 문서 구조는 동일하지만 부수적인 바이트(타임스탬프, 객체 순서)는 다를 수 있다는 뜻입니다. semantic은 바이트나 구조에 대한 보장 없이 렌더링된 결과가 동등하다는 뜻입니다. 레시피는 존재하는 가장 강한 프로파일이 아니라, 정직하게 보장할 수 있는 가장 강한 프로파일을 명시합니다.
• output_hash — 프로파일이 bitwise일 때 예상 출력의 SHA-256으로, 독자가 문서화된 결과를 검증할 수 있게 합니다. 프로파일이 안정적인 해시를 지원하지 않으면 비어 있습니다.
• runnable_example — 레시피의 출력을 생성하는 examples/… 경로이며, 페이지를 §1의 소스 기반 샘플에 연결합니다.
• performance_budget — 레시피에 대한 선택적인 실제 경과 시간 및 최대 메모리 상한으로, 성능 주장이기도 한 레시피가 한정되고 테스트 가능한 상태로 유지되게 합니다.
• compatibility — 레시피가 동작한다고 주장하는 PHP 버전입니다. 레시피는 기본적으로 PHP 8.4를 사용합니다. 8.4 전용 기능을 명시하는 레시피는 front-matter에 백포트를 나열하고 코드 블록에서 해당 기능을 명시합니다.

reproducibility 프로파일은 §8.4 reproducibility 계약에 해당합니다. 독자는 이를 통해 “출력”이 정확한 바이트를 뜻하는지, 아니면 동등한 문서를 뜻하는지 파악합니다.

4. 발행 gate

이 cookbook의 모든 페이지는 Writing Gate를 통과할 때까지 publish: false를 유지합니다. 기본값은 거부입니다. 즉, 페이지를 병합해도 발행되지 않으며, front-matter에 기록된 명시적인 gate 결정만 발행을 허용합니다. 실제 compliance-engine 장애로 인해 규범적 인용을 고정할 수 없었던 레시피는 추가로 미해결 인용 표시를 포함합니다. 인용이 다시 고정될 때까지 publish: false를 유지합니다. 저장소의 RAG 인프라 장애 대체 프로토콜이 그 표시를 관리합니다. 레시피 작성자는 인용을 지어내거나 주장을 삭제하는 대신 그 프로토콜을 따릅니다.

5. aggregator가 provenance 필드를 기록합니다

레시피 작성자는 aggregator가 소유하는 네 개의 소스 provenance 필드, 즉 source_repo, source_ref, source_hash, manifest_hash를 직접 작성하지 않습니다. aggregator는 소스 저장소에서 레시피를 가져올 때 이 필드들을 채우므로, 발행된 페이지는 정확히 어떤 저장소 리비전에서 생성되었는지 기록합니다. 작성자가 이 필드 중 하나에 자리표시자를 남겨 두면 aggregator가 이를 덮어씁니다. 자리표시자는 발행된 페이지에 절대 도달하지 않습니다.

요약

이 cookbook의 레시피는 다음 조건을 갖춥니다. 테스트를 갖춘 소스 기반 코드, 블록당 한 언어, 프로덕션 how-to를 위한 명시적 오류 처리, 정직한 reproducibility 프로파일, Writing Gate 전까지의 publish: false 기본값, 그리고 aggregator가 주입한 provenance입니다. 이 여섯 가지를 모두 충족하는 페이지는 레시피이며, 그보다 적게 충족하는 페이지는 초안입니다.

함께 보기

• Integration cookbook — 패키지와 핵심 제약에 대한 참조입니다.
• Choose an integration — 유스 케이스 결정 매트릭스입니다.