Agent CLI writer
에이전트는 매뉴얼이 아니라 명령어에 손을 뻗습니다. 오직 문서에만 존재하는 규칙은 에이전트가 우연히 읽을 때만 따라집니다. 이에 대한 측정값은 references/evidence.md에 있습니다.
규칙: 도구의 모든 규칙은 도구 자체가 해당 규칙이 적용되는 순간에 말합니다. 도구가 출력하는 것, 거부하는 것, 쉽게 만드는 것이 바로 매뉴얼입니다.
에이전트가 도구로 하는 일
- 먼저 명령어를 찾습니다. 확실하지 않을 때만 매뉴얼을 열지만, 종종 확신하면서도 틀립니다.
- 이미 세운 계획을 확인하기 위해 읽습니다: 구문을 찾지, 규칙을 찾지 않습니다.
- 세션 사이에 모든 것을 잊고 매번 도구를 다시 학습합니다.
- 한 번에 여러 호출을 보냅니다.
- 도구가 출력한 모든 문자에 대해 이후 모든 요청에서 다시 비용을 지불합니다.
- 저렴하게 기다릴 수 없습니다: 폴링하거나 슬립하며, 각 폴링은 유료 요청입니다.
- 바로 앞에 있는 답변이 말하는 것을, 이전 문서가 말한 것보다 더 신뢰성 있게 수행합니다.
방법
열두 가지 검사와 각각을 확인하는 방법. tool은 가상의 명령어입니다.
- 사용 시점에 가르치십시오. 명령어에 대한 응답은 방금 취한 경로의 비용을 알리고 더 나은 경로를 명명합니다.
확인: 알려진 잘못된 사용법이 있는 모든 동사는 자체 출력에서 이를 알려야 합니다.$ tool machine new created m-41 (60분 후 자동 중지) 참고: 이 머신에서 수동으로 시작한 작업은 실행 기록을 남기지 않습니다. 추적이 필요한 작업의 경우: tool job start --from <dir> -- <cmd> - 거절은 교훈입니다. 무엇이 거부되었는지, 이유, 그리고 호출자의 자신의 인수를 채운 정확한 다음 명령어를 말하십시오. 모든 문제를 하나의 답변에 제시하십시오. 0이 아닌 종료 코드로 종료하면서 아무 말도 하지 마십시오. 사용법 오류는 해당 하위 명령어 하나의 올바른 형식만 출력합니다.
확인: 메시지 없이 종료되는 경로가 없어야 함; 모든 거절은tool: 거부: `job wait j-7`은 이 턴을 최대 40분 동안 보류합니다. 다음: tool job show j-7 (현재 상태) tool job start … --notify (종료 시 알림)next:를 포함해야 함. - 도구 안에 매뉴얼을 담으십시오.
tool rules는 운영 규칙 전체를 버전 코드로 끝내며 출력합니다. 에이전트가 수동으로 구동하는 동사는 현재 코드(TOOL_RULES=<code>)를 설정하지 않은 비대화형 호출자를 한 줄로 거부합니다. 시스템 인터페이스 역할을 하는 동사는 열려 있습니다. 코드는 규칙이 변경될 때 변경됩니다. 확인: 명령어 이름만 제공된 새로운 에이전트는 무언가를 생성, 변경 또는 삭제하는 첫 번째 호출 전에 규칙을 컨텍스트에 가지고 있어야 합니다. - 올바른 경로를 쉬운 경로로 만드십시오. "X를 선호하십시오"를 작성하기 전에 X가 전체 작업을 수행하도록 하십시오: 에이전트가 실제로 가지고 있는 입력을 받아들이고, 즉시 반환하며, 기록을 유지하십시오. 에이전트는 차단하거나, 기록을 삭제하거나, 입력을 받을 수 없는 권장 명령어를 우회합니다. 선호도가 아니라 결과를 명시하십시오: "Y는 기록을 남기지 않습니다"는 "X를 선호하십시오"가 작동하지 않는 곳에서 작동합니다. 확인: 문서의 각 "선호"에 대해, 회피된 경로가 선호되는 경로에 비해 제공하는 것이 무엇인지 명명하고 그 격차를 해소하십시오.
- 하나의 명령어로 "내 상태는 무엇이며, 왜 그런가"에 답하십시오.
tool status는 몇 줄 안에: 내 것이 무엇인지, 실행 중인 것은 무엇인지, 마지막 작업이 어떻게 끝났고 왜 그런지, 다음에 무엇을 할지. 에이전트가 도구의 저장소나 로그를 직접 읽는 것은 상태에 사실이 누락되었음을 의미합니다. 확인: 실제 트랜스크립트에서 그러한 읽기 횟수를 세십시오; 가장 흔한 세 가지 질문은 상태에 속해야 합니다. - 긴 작업: 시작, 반환, 알림. 약 1분 이상:
start는 즉시 핸들을 반환합니다;show <handle>은 작업자나 호출자가 사라진 후에도 타임라인, 종료 코드 및 마지막 줄을 제공합니다; 종료는 결과와 이유와 함께 호출자에게 전달됩니다. 메시지는 에이전트가 지금 바로 행동할 수 있는 새로운 정보를 제공할 때만 자격이 있습니다: 주기적인 "계속 진행"은 없습니다. 확인: 기본적으로 60초 이상 차단되는 것은 없음; 모든 작업은 결과, 이유 및 다음 단계가 포함된 기록과 종료 알림이 있어야 함. - 적게 출력하십시오. 기본 출력은 한 화면에 맞습니다: 약 40줄 또는 2,000자. 더 많은 내용은 경로가 출력된 파일이나
--full뒤로 이동합니다. 배너, 진행 애니메이션 없음; 세션당 한 번 지시 사항. 잘린 출력은 그 사실과 나머지가 있는 위치를 알려야 합니다. 확인: 실제 일주일 동안 명령어당 반환된 문자 수를 측정하고 세 가지 가장 큰 합계에 예산을 할당하십시오. - 두 명의 독자: 사람과 프로그램. 터미널의 텍스트. 파이프되거나
--json이 있는 경우: JSON 라인만, 안정적인 필드 이름, 하나의 최종 요약. 종료 코드는 결과입니다: 0 완료, 그리고 거부, 잘못된 사용법, 시간 초과, 실행되지 않음에 대한 별도 코드. 진단은 표준 오류로. 확인:tool <verb> | cat구문 분석 가능;--help는 모든 종료 코드를 나열함. - 반복해도 안전하고, 즉시 안전합니다. 명령어를 두 번 실행하면 작업이 두 번 수행되지 않거나 이미 수행되었음을 알립니다. 한 에이전트가 동시에 두 번 호출하면 서로의 쓰기를 잃지 않습니다: 잠금을 걸거나, 두 번째를 말로 거부합니다. 파괴적인 동사는 명시적 플래그가 필요하고
--dry-run을 제공합니다. 확인: 테스트는 모든 쓰기 동사를 한 번에 두 번 실행합니다. - 제한하고 기록을 남기십시오. 기본 시간 제한; 도구가 생성하는 것은 자동으로 만료됨;
list는 남은 항목을 표시함;cleanup은 이 호출자가 만든 것을 제거함; 한 가지 일의 비용은 하나의 명령어입니다. 모든 작업은 누가, 언제, 도구의 빌드와 함께 기록됩니다;tool version은 이를 명명합니다. 확인: 호출자를 실행 중간에 종료하십시오; 무제한으로 실행되는 것은 없으며, 기록은 무슨 일이 일어났는지 말해줍니다. - 하나의 사물에 하나의 이름. 명령어, 출력, 오류 및 문서에서 동일한 명사; 명사 전반에 걸쳐 하나의 동작에 하나의 동사. 알 수 없는 플래그와 추가 인수는 거부되며 무시되지 않습니다. 확인: 도구가 출력하는 명사를 나열하십시오; 각 개념은 정확히 하나의 명사를 가져야 합니다.
- 비밀은 밖으로 나가지 않습니다. 명령줄에 절대, 에코되지 않음, 기록에 절대: 파일, 표준 입력 또는 환경에서 가져오며, 출력에서 마스킹됨.
도구 매뉴얼 작성
매뉴얼은 설명합니다; 도구는 강제합니다. 구속력 있는 것은 매뉴얼에만 존재하지 않습니다.
- 설명: 도구가 하는 일과 언제 로드해야 하는지, 작업이 사용할 단어로, 동사를 명명하여.
- 순서: 먼저 구속력 있는 규칙, 각각 그 결과와 함께; 그 다음 목표와 명령어에 대한 하나의 짧은 표; 그 다음 실패와 해야 할 일.
- 크기: 최대 150줄, 줄당 100자를 넘지 않음. 에이전트는 긴 줄이 잘린 파일을 출력하고 모든 넓은 테이블 행의 끝을 잃습니다.
- 표: 표 셀 내부에 구속력 있는 내용 없음.
새로운 에이전트에서 증명하십시오
도구나 매뉴얼을 본 적이 없는 새로운 세션에 실제 작업과 명령어 이름을 제공하십시오:
- 모든 호출, 그 출력 및 종료 코드를 기록하십시오.
- 계산: 도움말 조회, 실패한 호출, 실패한 호출의 반복, 폴링, 저장소 또는 로그의 직접 읽기, 반환된 문자 수.
- 0보다 큰 모든 카운트는 에이전트의 결함이 아니라 도구의 결함입니다. 메시지나 경로를 수정한 다음 다른 새로운 세션에서 다시 실행하십시오.
- 매뉴얼을 로드한 상태에서 한 번 더 실행하십시오: 더 나빠져서는 안 되며, 매뉴얼이 도구와 모순되어서는 안 됩니다.
새로운 에이전트가 도움말 조회 없이, 추측해야 했던 실패한 호출 없이, 폴링 없이, 저장소 직접 읽기 없이 작업을 완료하면 완료됩니다.
실패 모드
매뉴얼 전용 규칙 (도구가 이를 명시하지 않음) · 침묵 실패 (0이 아닌 종료, 말 없음) · 다음 단계 없는 이유 (이유와 명령어 없음) · 전체 도움말 덤프 · 선호되지만 더 나쁨 (권장 경로가 다른 경로가 가진 것을 결여함) · 상태 격차 (에이전트가 저장소를 읽음) · 차단기 (명령어가 턴을 보류) · 잔소리 (새로운 내용 없는 주기적 메시지) · 가서 확인 알림 (무언가 일어났다고 말하지만, 무엇인지는 말하지 않음) · 텍스트 벽 · 조용한 잘림 · 쓰기 손실 (한 번에 두 번 호출, 하나의 결과) · 두 개의 이름 · 잔여물 (만료되는 것 없음).