Vuk97/forward-implementation-first

코딩 에이전트가 자체적인 서류 작업에 매몰되는 것을 막는 에이전트 스킬입니다.

장시간 실행되는 에이전트 파이프라인은 장부 기록을 늘립니다: 콘텐츠 해시, 잠금 파일, 스테이지가 실행되었음을 증명하는 '영수증', 인증 마커, 대시보드 행, 진행 메타데이터. 이 중 어느 것도 제품 그 자체는 아닙니다. 하지만 모델에게는 이것들이 제품인 것처럼 착각하기 쉽습니다. 일단 이런 일이 발생하면 에이전트는 배포를 멈추고 큐레이션(curating)을 시작하며, 당신은 아무것도 요청하지 않은 것을 만들어내는 에이전트에 전액 비용을 지불하게 됩니다.

이 스킬은 에이전트가 모든 행동 전에 하나의 분류만 내리도록 하고, 절대 수행해서는 안 되는 항목의 짧은 목록을 제공합니다. 약 150줄의 Markdown으로 구성되어 있습니다. 모델에 구애받지 않고(model-agnostic), 도구에 구애받지 않으며(tool-agnostic), 도메인에 구애받지 않습니다(domain-agnostic).

순서화된 스테이지를 가진 파이프라인을 가지고 있다고 가정해 봅시다. 스테이지 40은 파일 하나를 생성하고, 스테이지 41은 그 파일을 사용합니다. 과정 중 어느 시점에서 오케스트레이터는 스테이지 40이 완료되었고, 그 입력값의 해시가 무엇인지 기록하는 작은 JSON 레코드를 작성하기도 합니다.

그런 다음 프로듀서(producer) 하나를 변경했다고 가정해 봅시다. 그러면 해시가 더 이상 일치하지 않습니다. 이 스킬 없이 에이전트가 하는 행동은 다음과 같습니다:

• 불일치를 감지하고, 이것을 정확성 실패로 간주합니다. 왜냐하면 불일치는 그렇게 보이기 때문입니다.
• 스테이지 12부터 40까지를 무효화(invalidate)합니다. 그 이유는 어떤 변경이 이들 중 어느 부분에 영향을 미쳤는지 증명할 수 없기 때문에, 더 많이 무효화하는 것이 더 안전하다고 느끼기 때문입니다.
• 파이프라인이 수동 실행에 대한 '영수증'을 발행할 수 없다고 하여 스테이지 41의 수동 실행을 거부합니다.
• 출력값이 전혀 변하지 않았고 잘못된 적도 없는 스테이지들의 마커를 재생성하는 데 다음 몇 시간을 소비합니다.
• 작업처럼 보이는, 수정된 영수증 건수를 기준으로 진행 상황을 보고합니다.

실패 모드의 후반부는 더 심각합니다. 에이전트가 진행할 수 없다고 알려줍니다. 그러면 사용자가 직접 해당 단계를 실행하거나, 두 번째 에이전트를 열어 처리하게 하고, 첫 번째 에이전트는 해시를 지키며 그 자리에 머무릅니다.

액션을 수행하기 전에, 에이전트는 이를 세 가지 중 하나로 분류합니다:

의미론적 구현 (Semantic implementation). 프로듀서(producer), 컨슈머(consumer), 어댑터(adapter), 런타임 경로(runtime path), 스키마(schema), 고정값(fixture), 또는 최종 출력을 구축하거나 연결합니다.집중 검증 (Focused validation). 동작, 스키마, 카운트, 순서가 지정된 샘플, 보존성(conservation), 일관성(consistency), 비절단(nontruncation), 그리고 측정된 시간 및 메모리를 통해 변경된 종속성 콘(dependency cone)을 테스트합니다.관리 장부 기록 (Administrative bookkeeping). 해시, 잠금(locks), 영수증(receipts), 대시보드(dashboards), 인증 마커(certification markers), 진행 메타데이터(progress metadata), 또는 존재만 확인하는 레코드(presence-only records)를 생성하거나 복구합니다.

1번과 2번을 수행하고, 사용자가 요청하지 않거나 해당 아티팩트가 제품의 일부가 아닌 경우 3번은 건너뜁니다. 만약 카테고리 3이 정확성을 보호하지 않은 채 경로를 차단한다면, 종속성을 삭제합니다.

이것이 전체 아이디어입니다. SKILL.md의 나머지 부분들은 이를 회피하기 어렵게 만듭니다. 왜냐하면 장부 기록을 하려는 모델은 항상 이유를 찾기 때문입니다.

이 부분이 스킬(skill)을 설치하는 데 안전하게 만드는 부분이며, 대부분 '더 빨리 움직여라' 프롬프트가 잘못 처리하는 부분입니다. 장부 기록은 건너뛰기 쉽습니다. 증거는 그렇지 않습니다. 이 스킬은 다음 사항들을 명시적으로 보존합니다:

• 제품 자체에 속하는 무결성(integrity). 사용자가 검증하는 체크섬, 형식이 요구하는 서명, 출력 계약의 일부인 해시 등이 있습니다. 이것들은 기능이지 서류 작업이 아닙니다;
• 입력 및 개정 식별자(input and revision identity). 어떤 버전의 대상(thing)을 다루고 있는지 결정할 때 필요합니다. 이를 잘못 알게 되면, 잘못된 대상을 대상으로 정확한 작업을 수행하게 됩니다;
• 결과를 단언하는 테스트, 벤치마크, 재현(reproductions), 그리고 종단 간 실행(end-to-end runs);
• 커버리지와 결과 사이의 차이점. 경로를 실행한다고 해서 그 경로가 올바른 답을 생성했다는 확인은 아닙니다.

명령어, 입력, 결과, 그리고 검증된 기대치를 담고 있는 실행 기록(execution record)이 실제 증거입니다. 이것의 부재는 그것이 지지하는 주장을 막습니다. 이는 20단계 전의 관련 없는 단계를 소급하여 무효화하지 않습니다. 그 구분이 바로 엄밀함(rigor)과 미신(superstition) 사이의 전체 차이이며, 이 기술(skill)이 그 경계를 그립니다.

파이프라인 단계는 실제 이유가 있을 때만 재실행되거나 롤백될 수 있습니다:

• 입력 의미가 변경되었을 때;
• 대상 또는 고정된 리비전(pinned revision)이 변경되었을 때;
• 출력이 잘못 형식이거나, 잘리거나, 비보존적(nonconserving), 불일치하거나, 소비자(consumer)와 호환되지 않을 때;
• 관찰된 실행이 이전의 정적 결과(static result)를 반증할 때;
• 변경된 프로듀서(producer)가 선언한 의존성 콘(dependency cone)이 요구할 때.

누락되거나 오래된 메타데이터는 이 목록에 없습니다. 단계가 단순히 마커(marker)에 의해 차단되는 경우, 에이전트는 이를 수동으로 실행하고 출력을 검증하며, 이를 게시한 다음 커서(cursor) 위치에서 계속 진행합니다. 그런 다음 관리 전용 게이트를 제거하여 같은 블록이 다시 발생하지 않도록 합니다. 전체 이력이 아닌 가장 작은 영향을 받는 콘을 재실행하십시오.

이 기술은 병렬성(parallelism)도 다룹니다. 왜냐하면 두 문제가 함께 나타나기 때문입니다. 책 정리(bookkeeping)로 바쁜 에이전트는 보통 모든 것을 직렬화(serialize)하기 때문입니다.

초기 피드백을 통해 첫 번째 버전에서 잘못 처리했던 경계가 하나 생겼습니다: 기술은 오케스트레이터(orchestrator) 역할을 해서는 안 됩니다. 스케줄링, 리소스 경쟁, 워커 토폴로지(worker topology)는 런타임(runtime)에 속하며, 이들을 주장하는 몇 줄의 마크다운(Markdown)은 어떤 실제 스케줄러와도 충돌할 것입니다. 따라서 해당 섹션은 두 부분으로 나뉩니다.

불변성(Invariants): 모든 스케줄러 하에서 유지되는 일급 규칙(first-class rules)으로서:

• 출판, 커서 이동, 결론을 소유하는 작성자(writer)는 정확히 한 명이어야 합니다. 병렬 워커들은 준비하고 검사합니다. 그들은 절대 두 번째 진실의 원천(second source of truth)이 되어서는 안 됩니다.
• 소비하기 전에 워커의 출력을 검증하십시오. 보고서는 의도(intent)를 상태가 아닌 결과로 명시해야 합니다.
• 순전진(Forward progress)은 모든 워커를 기다리지 않습니다. 필요한 의존성에 도달했을 때 출력을 소비하십시오.
• 유휴 슬롯을 채우기 위해 결코 바쁜 작업(busywork)을 만들어내지 마십시오.

스케줄링 정책 자체, 워커 개수, 웨이브 크기, 무거운 프로세스로 간주되는 기준 등은 스킬에 전혀 포함되지 않습니다. 런타임이 이미 이를 소유하고 있으며, 자체 정책을 가진 스킬은 런타임과 충돌할 것입니다. 만약 설정에서 아무것도 스케줄링을 소유하지 않는다면, examples/execution-profile.md가 복사하여 편집할 수 있는 시작 프로파일입니다. 스킬이 스스로 이를 로드하는 경우는 없습니다.

불변성(invariants)이 속도 향상보다 더 중요합니다. 저렴한 병렬 워커는 신뢰되지 않기 때문에 유용하며, 그 가치는 출력물이 검사 없이 병합되는 순간 사라집니다.

스킬은 Agent Skills 컨벤션을 따르는 YAML 프론트매터가 포함된 단일 Markdown 파일입니다. 에이전트가 스킬을 찾는 모든 위치에 복사하세요:

git clone https://github.com/Vuk97/forward-implementation-first
cd forward-implementation-first
./install.sh

install.sh는 SKILL.md를 찾은 모든 에이전트 스킬 디렉터리에 복사합니다:

스킬은 제안입니다. 모델이 이를 로드할지 결정합니다. 만약 사용자의 에이전트가 항상 켜져 있는 규칙(always-on rules)이나 후크(hooks)를 지원한다면, 의사결정 규칙도 그곳에 넣어야 합니다. 왜냐하면 이 특정 실패 모드는 모델이 자신 있게 빠지기 쉬운 함정이기 때문입니다.

다음 중 하나라도 사용자의 설정을 설명한다면 설치하세요:

• 순서가 있는 단계와 영속적인 커서(persisted cursor)를 가진 파이프라인;
• 후반 단계가 의존하는 생성된 아티팩트(generated artifacts);
• 작업 자체에 의해 작성된 것이 아니라 오케스트레이터(orchestrator)에 의해 작성된 모든 매니페스트(manifest), 락파일(lockfile), 또는 영수증(receipt);
• 너무 오래 실행되어 모든 단계를 지켜보고 있지 않은 경우;
• 하나의 리포지토리를 건드리는 여러 에이전트나 세션.

일반적인 형태: 단계별 데이터 및 ETL 실행, 대규모 코드 마이그레이션, 빌드 및 릴리스 파이프라인, 다수의 입력에 대한 문서 생성, 배치 분석 작업, 그리고 에이전트가 며칠에 걸쳐 진행하는 모든 로드맵.

단일샷 태스크, 짧은 인터랙티브 세션, 그리고 감사 추적(audit trail) 자체가 결과물인 모든 워크플로우에서는 건너뛰세요. 누군가 당신의 영수증을 읽는다고 해서 그게 장부 정리(bookkeeping)는 아닙니다.

이것은 원래 길게 실행되는 스테이지드 파이프라인(staged pipeline)의 매 세션 상단에 붙여넣던 프롬프트에서 시작되었습니다. 이 파이프라인에서는 에이전트가 메타데이터 드리프트(metadata drift)로 인해 수십 개의 완료된 단계를 반복적으로 무효화했고, 심지어 수동으로 단계를 실행하는 것을 거부했습니다. 매번 이것을 붙여넣는 것이 효과적이었습니다. 이것을 붙여넣는 것을 잊으면 며칠이 손해였습니다.

이를 스킬(skill)로 만듦으로써 기억해야 할 것에서 기본 동작(default behavior)으로 만들 수 있었습니다.

MIT. LICENSE를 참조하세요.