gvozdb/semantic-spec-writer-skill

의미론적 사양 작성기(Semantic Spec Writer)

구현 에이전트가 이 스킬을 로드하지 않고도 사용할 수 있는 .plan.ctx 및 .spec.ctx 파일을 생성합니다.

모드

• 새 문서: 요청과 근거가 있는 저장소 사실로부터 최종 의미론적 산출물을 직접 작성합니다. 먼저 산문 초고를 만들지 마십시오.
• 기존 문서: 요청된 대로만 변환하며, 원본 의미와 식별자를 보존합니다. 최종 산출물은 원본보다 짧아야 합니다.
• 인계 또는 반복 사용: 다른 에이전트나 이후 턴에서 독립적으로 실행할 수 있도록 최적화합니다.
• 저장소 실행 패킷: 사용자가 코딩 인계를 원하고 코드베이스를 사용할 수 있는 경우, references/execution-packets.md를 읽으십시오. 패킷을 작성하기 전에 최소한의 읽기/편집 경로를 설정하십시오.

일회성 구현에 대해 변환이 총 토큰을 절약한다고 주장하지 마십시오. 변환은 작성 단계를 추가합니다. 그 경제성은 더 작은 재사용 가능한 컨텍스트와 더 적은 구현 모호성에서 비롯됩니다.

목표

단순 문자 수가 아닌 전체 구현 루프를 최적화합니다:

• 모든 동작, 제약 조건, 에지 케이스 및 정확한 식별자를 보존합니다.
• 서술, 반복, 장식적 메타데이터 및 일반적인 조언을 제거합니다.
• 요구 사항에서 편집, 검증까지의 가장 짧고 신뢰할 수 있는 경로를 노출합니다.
• 해석이 필요한 약어보다는 직접적인 언어를 선호합니다.

더 작은 파일은 올바르게 실행하기에 더 빠를 때만 유용합니다. 기존 문서를 변환할 때는 쓰기 전에 간결한 구조를 계획하고 원본을 확장하지 마십시오. 파일 크기를 줄이기 위해 도구 루프나 반복적인 재작성을 추가하지 마십시오.

토큰 규율

• 누락된 사실에 대한 목표 조회가 필요하지 않는 한 각 제공된 소스를 한 번만 읽습니다.
• 범위, 인터페이스 및 검증을 설정하는 데 필요한 파일만 검사합니다.
• 하나의 최종 산출물을 작성합니다. 첫 작성에서 더 짧게 만드십시오. 변환의 경우, 이 스킬 디렉토리에서 scripts/check_conversion.py SOURCE OUTPUT을 한 번 실행하십시오. 대상 토크나이저가 알려져 있고 tiktoken을 사용할 수 있는 경우 --encoding NAME을 전달하십시오. 검사가 실패하면 중복을 한 번 제거하고 다시 한 번 실행하십시오. 크기 줄이기 루프를 계속하지 마십시오. 요청되지 않는 한 개요, 초안, 변환 노트, 크기 보고서 또는 설명을 내보내지 마십시오.
• 구현 에이전트가 검색 없이 정확한 대상 파일에서 얻을 수 있는 저장소 사실을 복사하지 마십시오. 잘못된 편집이나 추가 발견을 방지하는 사실을 포함하십시오.
• 일반적인 구현 조언보다는 정확한 경로와 하나의 실행 가능한 검증 명령을 선호합니다.
• 실행 패킷의 경우, 다운스트림 발견을 제거하거나 잘못된 편집을 방지하는 사실에만 작성 노력을 기울이십시오. 패킷을 저장소 덤프로 만들지 마십시오.
• 실행 패킷에 참조의 표준적인 경계 있는 다운스트림 루프를 제공하십시오: 하나의 경로화된 읽기, 하나의 구현 패스, 하나의 선언된 검증, 그런 다음 성공 시 중지합니다. 확장은 명백한 모순이나 실패가 필요합니다.

형식

• plan 또는 spec으로 시작합니다.
• 프로젝트에 다른 규칙이 없는 한 계획에는 .plan.ctx를, 사양에는 .spec.ctx를 사용합니다.
• 명확한 로컬 블록 이름을 사용합니다. 이는 레이블이지 예약된 언어 키워드가 아닙니다.
• 정보를 전달하는 블록만 포함합니다. 빈 섹션을 내보내지 마십시오.
• 별도의 블록이 동일한 정보를 반복할 때는 대상, 범위 및 계약 사실을 결합합니다.
• 파일 경로, 심볼, API 라우트, 필드, 테이블, 환경 변수, 명령, 상태, 역할 및 오류 텍스트를 정확하게 보존합니다.
• 필드 소유권과 중첩을 정확하게 보존합니다. 구현 언어에 맞게 필드 표기법을 조정합니다: Python JSON/맵의 경우 event["payment_id"]를 사용하고 event.payment_id를 사용하지 마십시오. 소스가 정의하지 않은 data, payload 또는 다른 래퍼를 절대 만들지 마십시오.
• .ctx를 마크다운이 아닌 일반 텍스트로 취급합니다. 일반 식별자를 백틱, 굵게 또는 다른 프레젠테이션 마크업으로 감싸지 마십시오. verify 아래의 실행 가능한 명령에만 백틱을 사용하십시오.
• 실제 반복을 제거하는 경우에만 로컬 용어를 정의합니다. 설명적인 용어를 선호합니다. 한 글자 별칭과 발명된 표기법을 피하십시오.
• 다른 항목이 참조하는 경우에만 ID를 추가합니다.
• x=true, x in [a,b], condition -> result와 같은 친숙한 표현을 사용하십시오. 숨겨진 구문에 의존하지 마십시오.
• 구조화된 필드가 중요한 뉘앙스를 잃을 때만 짧은 # 주석을 사용하십시오.
• 동일한 문장 프레임을 반복하는 대신 하나의 간결한 매핑 아래에 병렬 검증, 출력 필드 및 정확한 오류를 그룹화합니다.
• 필드 소유권이 설정된 후에는 전체 소유자 경로를 반복하는 대신 검증 및 오류 맵에서 짧고 명확한 레이블을 사용하십시오.
• 오류 맵에서 블록이 반복되는 문법을 전달하도록 하십시오. 모든 줄에서 invalid owner.field -> ErrorType을 반복하는 대신 field: condition | ErrorType "exact message"를 선호합니다.
• 줄당 하나의 독립적으로 테스트 가능한 규칙을 유지합니다. 공유 매핑은 문법이 일관된 경우 관련 필드 사례를 보유할 수 있습니다.
• A* ID는 acceptance 아래에서 한 번만 사용합니다. 수락 ID를 규칙 또는 작업 ID로 재사용하지 마십시오.

근거 설정

코드베이스를 사용할 수 있는 경우 작성 전에 검사합니다. 알려진 편집 범위, 기존 인터페이스, 제약 조건 및 실행 가능한 검증 명령을 캡처합니다. 정확한 명령이나 기존 명명된 검사에 대해서만 verify를 포함합니다. 검증 시나리오를 발명하지 마십시오. 파일 이름이나 아키텍처를 추측하지 마십시오.

알려지지 않은 결정은 open_questions에 속합니다. 미지의 것이 없으면 해당 블록을 생략합니다.

정보 순서

구현 에이전트가 필요한 순서대로 정보를 배치합니다. 관련 부분만 사용하십시오:

1. 목표 또는 대상, 알려진 경우 정확한 편집 범위 포함;
2. 대상에 의해 아직 명시되지 않은 계약;
3. 규칙, 불변 조건, 상태 또는 흐름;
4. 종속성이 중요한 경우에만 순서가 지정된 작업;
5. 검증 명령 및 관찰 가능한 수락;
6. 해결되지 않은 질문.

정확한 범위와 검증은 일반적으로 공격적인 산문 압축보다 더 많은 에이전트 작업을 절약합니다.

압축 규칙

• 각 사실을 한 번만 명시합니다.
• 중복 요구 사항을 병합합니다.
• 콘텐츠가 이미 다른 줄에 포함된 경우 블록을 생략합니다.
• 수락은 산문을 다시 설명하는 대신 기존 규칙, 계약 및 검증 ID를 참조하도록 합니다.
• 참조된 블록이 이미 관찰 가능한 동작을 명시하는 경우에만 수락을 참조로 유지합니다.
• 구현 결정을 변경하는 경우에만 이유를 유지합니다.
• 개선, 지원, 처리, 최적화 및 수정과 같은 모호한 동사를 관찰 가능한 결과로 대체합니다.
• 드물지만 중요한 에지 케이스를 유지합니다. 파일을 더 짧게 만들기 위해 절대 삭제하지 마십시오.
• 단어를 줄이기 위해 일반 요구 사항을 공식으로 인코딩하지 마십시오.
• 올바르게 실행하기 더 쉬운 경우 긴 산문 설명보다 정확한 소스 기반 정수 공식을 선호합니다.

예제

구현 사양:

spec
target: [src/payments.ts, tests/payments.test.ts] :: Idempotency-Key로 POST /payments를 멱등적으로 만듦
keep: 응답 스키마, 인증 동작

rules:
  R1: 키 범위는 user_id
  R2: 동일한 사용자 + 동일한 키 + 동일한 본문 -> 원래 상태 및 본문 재생
  R3: 성공을 반환하기 전에 결과 유지

errors:
  E1: Idempotency-Key 누락 -> 400 idempotency_key_required
  E2: 동일한 키 + 다른 본문 -> 409 idempotency_conflict

verify:
  V1: `pnpm test tests/payments.test.ts`

acceptance:
  A1: R1,R2,R3,E1,E2 -> V1

병렬 검증 맵:

validation:
  retries: int>=0 | ValueError "재시도 횟수는 음수가 아니어야 합니다"
  timeout: int>0 | ValueError "시간 제한은 양수여야 합니다"

구현 계획:

plan
goal: API 동작을 변경하지 않고 세션 스토리지를 메모리에서 Redis로 이동

facts:
  현재 스토어: src/session/memory.ts
  계약 테스트: tests/session.contract.test.ts

tasks:
  T1: 기존 SessionStore 인터페이스 뒤에 Redis 어댑터 추가
  T2: 메모리 및 Redis 어댑터에 대해 계약 테스트 실행
  T3: T2 통과 후 컴포지션 루트 전환

verify:
  V1: `pnpm test tests/session.contract.test.ts`

품질 관문

마치기 전에 다음을 확인하십시오:

• 새로운 구현 에이전트가 이 스킬이나 명시되지 않은 컨텍스트 없이 작업을 수행할 수 있습니다.
• 모든 줄이 범위, 동작, 구현 순서 또는 검증을 변경합니다.
• 어떤 요구 사항도 중복되지 않거나 정의되지 않은 약어로 대체되지 않았습니다.
• 알려진 파일, 인터페이스 및 명령이 정확합니다.
• 수락이 관찰 가능하고 명시된 계약으로 추적됩니다.
• 모든 필드가 여전히 원본과 동일한 소유자와 중첩을 가지고 있습니다.
• 의미를 모호하게 하지 않고 중복을 제거하여 결과가 더 짧아졌습니다.

의미론적 문서를 먼저 출력합니다. 구현을 실질적으로 차단하는 해결되지 않은 결정에 대해서만 별도의 메모를 추가합니다.