vladyslav-betterme/autopilot-skill

Autopilot

이 스킬은 작업의 '완료' 의미를 가정하지 않고 직접 묻는 포터블 자율 루프입니다. 가정하지 않고 해당 답변이 충족될 때까지 멈추지 않습니다.

이 스킬이 불가능하게 만들고자 하는 세 가지 주장:

• '실행되지 않았는데 동작한다'는 주장
• '평가자가 작업자 자신뿐인데 완료되었다'는 주장
• '시도, 실패, 이유에 대한 기록 없이 작업했다'는 주장

작업 대상은 중요하지 않습니다. 리팩토링, 마이그레이션, 보고서, 데이터셋, 렌더 팜, 클러스터: 아래 루프는 동일하며 오직 체크(check) 만 다릅니다.

0. 부트스트랩 — 프로젝트당 한 번

<skill>은 이 파일이 위치한 디렉토리입니다 — CLI 설치 후 .agents/skills/autopilot 또는 복제된 위치입니다. 모든 명령은 프로젝트 루트에서 실행하세요.

node <skill>/scripts/discover.mjs        # 체크, 메모리 홈, 위험 신호 확인
node <skill>/scripts/bootstrap.mjs       # 원장(ledger)이 없으면 생성
node <skill>/scripts/skills.mjs          # 스킬 라이브러리 — 이 프로젝트의 특화 영역 선택
node <skill>/scripts/tools.mjs           # 이 머신이 이미 접근 가능한 것: MCP 서버, 플러그인

discover는 프로젝트 자체의 체크 명령어를 출력합니다. 해당 명령어는 아래 모든 반복의 완료 정의입니다.

checks: []가 출력되면 아직 믿지 마십시오. 발견(discovery)은 체크를 선언한 파일만 읽습니다. 프로젝트의 실제 체크는 종종 일반 문장으로 명시되어 있습니다. memoryHomes에 나열된 모든 경로와 README, CI 설정에서 실행 가능한 명령어를 grep하세요 — 한 프로젝트에서 checks: []가 출력되었지만 CLAUDE.md에는 ./tests/run_all.sh가 명시되어 있었고, 이는 4초 만에 63개의 테스트를 실행했습니다. 반면 에이전트가 임의로 생성한 체크(node --check)는 죽은 앱에서도 통과했습니다.

해당 검색 결과가 비어있는 경우에만 프로젝트에 자동 체크가 정말로 없는 것입니다 — 이는 산문(prose), 연구, 운영에서 흔하며 자신의 작업을 스스로 판단할 권한이 없음을 의미합니다. 첫 번째 반복 전에 수용 체크(acceptance check)에 동의하고 목표(§1)에 작성하세요. 다음 중 하나가 체크입니다. '내가 검토했고 맞아 보인다'는 체크가 아닙니다:

작업	자신의 의견이 아닌 체크
코드	포그라운드에서 실행되어 0으로 종료되는 명령어
문서	주장별 목록과 각 주장의 출처 또는 명령어
데이터	다른 사람이 다시 실행할 수 있으며 예상된 형태를 반환하는 쿼리
인프라/운영	시스템 자체의 관찰 결과(전후 비교)
연구	숫자를 생성하는 쿼리 또는 추출, 그리고 사전에 반증으로 등록한 결과 — 둘 다 다른 사람이 다시 실행 가능해야 함

발견된 내용을 먼저 읽고 건드리지 마십시오:

• memoryHomes — 내구성 있는 지식이 이미 있는 장소. 해당 파일을 사용하세요. 두 번째 CHANGELOG.md, 두 번째 학습 디렉토리, 두 번째 AGENTS.md를 절대 생성하지 마십시오. 한 종류의 지식을 위한 두 번째 홈은 에이전트가 저장소를 더 나쁘게 만드는 가장 흔한 방법입니다.
• signals.envFilesPresent 및 signals.remote — 첫 번째 반복 전에 작업 환경이 프로덕션을 가리키는지 물어보십시오. 저장소에 명시되지 않았고 모든 로컬 실행이 무해해 보였던 프로젝트에서 실제로 그랬던 경우가 있었습니다. 반대 증거가 있을 때까지 '예'라고 가정하세요.
• signals.vcs — none은 실행 취소 기능이 없음을 의미합니다. 첫 번째 반복 전에 입력을 안전한 곳에 복사하고 goal.md에 위치를 명시하세요. §8의 '통과한 항목 커밋'은 여기서 의미가 없으며, 바로 그 때 작업이 손실됩니다.
• signals.dirty — 커밋되지 않은 작업은 누군가의 것입니다. 브랜치를 생성하고, 그 위에 절대 쌓지 마십시오.

첫 번째 반복 전에 무장하세요

skills.mjs는 공개 스킬 중 가치 있는 것들의 목록으로, 특화 영역(niche)별로 태그되어 있습니다. 태그는 어휘입니다 — 모든 프로젝트에 any와 review, 그리고 프로젝트가 실제로 필요로 하는 web, react, db, docs, perf, a11y, mac, infra, research, design입니다.

node <skill>/scripts/skills.mjs                            # 카탈로그 및 태그
node <skill>/scripts/skills.mjs --install any --dry-run    # 실행될 내용 확인
node <skill>/scripts/skills.mjs --install any              # 항상 유용한 세트 설치
node <skill>/scripts/skills.mjs --install react,perf,db    # 이 프로젝트의 특화 영역 설치

선택하되, 쌓아두지 마십시오. 설치된 모든 스킬의 설명은 매 턴마다 로드됩니다. 100개의 스킬은 100개의 능력이 아니라, 더 작은 창과 훑어보는 모델을 의미합니다.

설치는 타사 코드를 사용자의 권한으로 실행하는 것이므로, 공지된 행위입니다: 먼저 --dry-run을 실행하고, 추가하려는 내용과 이유를 말한 후 설치하세요. 프로젝트가 카탈로그의 어떤 특화 영역에도 맞지 않는다면, any만으로도 올바른 답입니다 — 그리고 find-skills는 카탈로그가 빈약한 특화 영역(현재 연구, 인프라, 데이터가 빈약함)을 위한 진입점입니다.

그런 다음 방금 사용한 자원을 측정하세요. skill-cleaner는 any 세트와 함께 제공되며, '선택하되, 쌓아두지 마십시오'가 조언에 그치지 않도록 합니다:

node --experimental-strip-types <skills-root>/skill-cleaner/scripts/skill-cleaner.ts \
  --root .agents/skills --root-only --no-logs

이는 설치된 설명이 차지하는 예산, 중복(하나의 질문에 답하는 두 개의 스킬 — 이 루프가 한 단계 위에서 찾는 결함), 그리고 압축할 가치가 있는 긴 설명을 보고합니다. 조치하십시오: 이 프로젝트가 사용하지 않는 것을 제거하고, 중복을 두 개 유지하지 말고 병합하세요. 읽고 무시한 감사(audit)는 감사가 없는 것과 같은 컨텍스트 비용이 듭니다.

스킬은 절반입니다 — 나머지 절반은 접근 가능성(reach)입니다

skills.mjs는 에이전트가 아는 것입니다. tools.mjs는 에이전트가 접촉할 수 있는 것입니다: 읽을 수 있는 설정 파일에서 찾은 MCP 서버, 더 많은 것을 제공하는 플러그인, 그리고 디스크에서 알 수 없는 것들입니다. 빈 결과는 '이 파일들에 없음'을 의미할 뿐, '이 머신에 없음'을 의미하지 않습니다.

node <skill>/scripts/tools.mjs

부족한 능력이 목표를 좁힐 이유는 아닙니다. 그것은 사다리입니다 — 이미 접근 가능함 → 앱 자체 CLI → 공개 서버 → 커넥터(§6에 보관) → new-mcp.mjs로 작성. 각 단계, 각각의 비용 및 함정은 references/tooling.md 에 있습니다. 무엇이든 만들기 전에 읽으십시오. 여기서 보이지 않는 두 가지 실패를 방지하기 때문입니다: 이미 구성된 능력이 없다고 판단하는 것, 그리고 이미 답하는 질문에 대한 두 번째 답을 만드는 것.

가장 문제가 될 것: 대부분의 하네스(harness)는 시작 시 MCP 설정을 읽으므로, 실행 중간에 작성된 서버는 일반적으로 해당 세션에 보이지 않습니다. 이것이 스캐폴드가 또한 CLI인 이유입니다 — node server.mjs --call <tool> '<json>', 동일한 핸들러. 지금 이 양식을 사용하고 다음 세션이 서버를 얻도록 하세요. '재시작 후 계속'은 파일을 들고 있는 중단된 루프입니다.

그런 다음, 전체 과정에서: 여기서 배운 내용은 자체 스킬이 됩니다(§5). 루프에 의해 작성되고 동일한 세션에서 사용됩니다. 그리고 부족한 능력은 자체 도구가 되어 같은 방식으로 사용됩니다.

1. 목표 — 루프가 충족될 때까지 실행하는 것

첫 번째 반복 전에 하나의 반증 가능한 문장과 2~5개의 완료 기준을 작성하세요. goal.md에, 또는 발견(discovery)이 이미 이 정보를 담고 있는 파일에 작성하세요.

• 반증 가능: 'X를 더 좋게 만든다'는 불가능합니다. '돈을 소비하는 모든 경로가 명시적인 탭 뒤에 있고, 각각이 타입이나 실패하는 테스트에 의해 보호된다'는 가능합니다.
• 각 기준은 당신이 아닌 다른 사람이 확인할 수 있어야 합니다 — §0과 같은 기준입니다. 당신만 확인할 수 있는 기준은 기준이 아닙니다. 다시 작성하세요.
• 알려지지 않은 것은 자체 기준으로 허용됩니다: 'N이 원인인지 여부를 우리는 안다'는 연구를 위한 정당한 완료 기준입니다.
• 큰 목표는 작은 목표를 통해 달성되며, 기준이 바로 그 분해(decomposition)입니다 — 각각 자체적으로 완료, 확인, 검증될 수 있는 조각입니다. 한 번의 반복에 너무 큰 기준은 자체 기준으로 분할됩니다. 깊이는 괜찮으며, 모든 수준은 동일한 기준(당신이 아닌 다른 사람이 확인 가능)을 유지합니다. 반증 가능하지 않은 수준은 계획일 뿐, 기준이 아닙니다.
• 부족한 능력은 우회로가 아니라 기준입니다. '루프가 X를 헤드리스로 구동할 수 있으며, 한 번의 왕복으로 증명됨'은 차단 해제하는 작업 옆의 표(references/tooling.md)에 들어갑니다. 기록되면 도구 구축은 제한적이며 부재가 명확해집니다. 기록되지 않으면 기준을 생성하지 않은 오후가 되어 진행 상황으로 읽힙니다.
• 아무도 목표를 주지 않은 경우 — '계속'만 있고 다른 것이 없다면 — 첫 번째 반복의 유일한 출력은 제안된 goal.md와 사람을 위한 질문입니다. 당신이 작성하고 충족시킨 기준은 위의 주장 #2에 해당하며, 체크리스트를 착용한 것입니다.
• goal.md는 또한 고정된 상태를 담습니다: 체크 명령어, 기준 출력, 프로덕션 질문에 대한 답변, 브랜치(또는 입력 복사본 위치), 설치된 스킬. 이것들을 다시 유도해야 하는 재개는 재개가 아닙니다.

그런 다음 루프는 모든 기준이 충족되고 검증될 때까지 실행됩니다. 모델이 완료되었다고 느낄 때까지가 아니라, 비평가들이 조용해질 때까지가 아닙니다 — 그들은 결코 조용해지지 않습니다. 각 반복은 goal.md에 어떤 기준이 이동했는지와 그 증거를 표시하며 종료됩니다.

루프를 조기 중단하는 경우는 §6(질문), §7(쓰래싱) 및 §8(컨텍스트)의 이유만 해당됩니다.

2. 반복

한 번의 반복 = 하나의 변경 사항, 확인, 검증, 기록. 하나의 파일이 아닙니다. 한 번의 턴이 아닙니다.

선택. 목표의 충족되지 않은 기준 중에서 선택하세요. 여러 개가 열려 있다면, 실패 시 가장 많은 다른 작업을 무효화할 기준을 선택하세요 — 위험×범위 순서대로 정렬하세요. 쉬운 순서가 아닙니다.

단축하기 전에 이해하세요. 실제 종단 간(end-to-end)을 추적하세요. 그런 다음, 새로운 것을 만들기 전에 이미 존재하는지 물어보세요 — references/premise-check.md 참조, 이 스킬에서 가장 생산성이 높은 단일 습관이며 배우는 데 가장 오래 걸렸습니다.

실제로 올바른 가장 작은 것을 구축하세요. 근본 원인을 찾으세요. 요청이 명명한 증상이 아닙니다: 먼저 동일한 형태의 다른 모든 위치를 찾고, 모두 통과하는 지점에서 수정하세요.

증명하세요. 발견된 체크를 실행하세요. 포그라운드에서, 실행한 셸의 종료 코드를 읽으세요. 또는, 요약을 작성하지 않는 것이 읽어주도록 하는 것이 더 좋습니다:

node <skill>/scripts/prove.mjs --record -- npm run verify   # 체크, 실제 상태, goal.md에 기록
node <skill>/scripts/prove.mjs --times 3 -- <check>         # 자체적으로 일치하지 않는 체크는 불안정함

Prove와 Verify는 모델이 서술할 수 있는 두 단계입니다 — 다른 단계들은 파일, 커밋 또는 diff를 남기는 반면, '체크 통과'와 '검토자 동의'는 모두 사실로 만들고 싶었던 컨텍스트에 의해 작성된 텍스트입니다. 실행기는 첫 번째에 답합니다: 셸 없이 생성되므로 보고하는 상태는 자식 프로세스 자체의 상태입니다. 자체 npm 스크립트에 파이프가 포함된 체크를 거부합니다 ("verify": "tsc | tail"은 tail의 상태를 보고했으며, 이는 여섯 번의 빨간색 배포가 녹색으로 읽히도록 만든 형태입니다). 루프가 중단되었을 때 250을, 동일한 체크가 두 개의 다른 상태를 반환할 때 251을 보고하며, --record와 함께 실행이 생성한 숫자 — 실패하는 것 포함 — 를 goal.md에 기록합니다.

보지 못하는 것: 셸 스크립트 내부의 파이프, Makefile 대상, 또는 체크가 호출하는 바이너리입니다. 증명할 수 있는 거짓말을 제거합니다. 체크를 인증하지는 않습니다. §3은 Verify에 대해 답합니다 — 평결과 증거를 원장에 기록하거나, 그 단계도 서술에 불과합니다.

첫 번째 반복 전에도 한 번 실행하고 goal.md에 붙여넣으세요: 당신보다 먼저 존재했던 실패는 기록할 결정이지 당신 반복의 잘못이 아닙니다. 기준이 없으면 다른 사람의 빨간색을 채택하거나 그들의 녹색을 진행 상황으로 기록하게 됩니다. 자체적으로 일치하지 않은 적이 있는 체크는 불안정합니다 — 기준이 충족된 것으로 표시되기 전에 세 번 다시 실행하세요. 체크가 거짓말하는 세 가지 방법, 모두 관찰됨:

check | tail	tail의 상태를 보고함
check > log; echo "EXIT=$?"	;는 마지막 명령어의 상태를 만듦 — 항상 0
백그라운드 래퍼	완료 알림이 래퍼의 상태를 보고함

명령어가 없을 때, Prove는 건너뛰지 않으며 '다시 읽었다'가 아닙니다. goal.md에 명시된 대로 수용 체크를 정확히 다시 실행하고, 출력을 붙여넣고, 실패한 결과가 어떻게 보였을지 말하세요. 실패를 명시할 수 없다면 체크가 없는 것입니다.

모든 새로운 보호 장치는 수정 없이 실패하는 것을 관찰했음을 증명해야 합니다. 수정을 제거하고, 실행하고, 빨간색을 확인하고, 복원하세요. 작동하지 않는 보호 장치는 없는 것보다 나쁩니다: 해당 케이스가 처리되었음을 증명하는 것으로 읽힙니다. 코드 외부에서도 동일한 규칙 — 체크가 실패할 수 없다면 장식입니다.

그리고 작업이 무언가를 생성했을 때 — 설정, 스크립트, 유닛 파일, 생성된 서버 — 생성한 것을 실행하세요. 읽는 것은 아무것도 증명하지 않습니다. 한 캠페인에서 세 번, 결함은 페이지에서 보이지 않았지만 첫 번째 실행에서 명백했습니다. 생성된 MCP 서버는 올바르게 보였고 클라이언트를 중단시켰을 것입니다. JSON-RPC 알림은 응답을 받지 않아야 하기 때문입니다. 캐리어의 래퍼는 완벽하게 읽혔고 에이전트를 호출하지 않고 0으로 종료되었습니다. 단계가 &&로 연결되었기 때문입니다. launchd plist는 plutil -lint를 통과했지만, launchctl bootstrap + kickstart를 실행하고 작성한 내용을 읽은 후에야 실제로 실행 중임을 보여주었습니다. 생성하는 것은 수행하는 것이 아닙니다.

Verify — §3. 절대 건너뛰지 말고, 직접 수행하지 마십시오.

이 프로젝트가 작업을 수용하는 방식으로 전달하세요: 커밋 및 PR, 게시, 적용, 전달. 이름으로 스테이징하세요 — -A/-u/.는 절대 사용하지 마십시오. 로컬 전용 편집을 선택하고 -u는 새 파일을 놓칩니다. 그런 다음 실제로 전달되었는지 확인하세요: 로컬 실행이 녹색이라고 해서 배포된 것은 아니며, 병합된 PR이 실제 변경 사항이 적용된 것은 아닙니다.

기록 — §4. 그런 다음 goal.md를 업데이트하고 다음 반복을 시작하세요.

3. 작업을 수행하지 않은 사람과 검증하기

이것은 체크를 실행하는 것과 동일하지 않으며, 선택 사항이 아닙니다.

자신의 수정 사항은 두 번째로 큰 결함 원천입니다 — 측정된 한 캠페인의 후반 라운드에서 모든 발견의 58~68%가 그랬습니다. 하나의 저장소에서. 당신은 그것들을 볼 수 없습니다. 왜냐하면 그것들을 작성하는 것이 보는 것을 배제했기 때문입니다.

• 모든 반복: 작업을 수행하지 않은 적어도 하나의 하위 에이전트(subagent) 가 정확한 범위를 부여받고, 읽기 전용으로, 완료되었다는 주장을 반박하는 것이 임무입니다. 확인을 시도조차 하지 않은 검토자가 '확인됨'이라고 말한 것은 아무런 가치가 없습니다.