내 컴퓨터에서 돌아가는 연구 에이전트 도구 만들고 관리하기

## 연구 도구를 사용자 컴퓨터에서 돌리고 하지 않을 일을 정하기 사용자 컴퓨터에서 기본적으로 실행되고, 문서화된 공개 경로를 통해 설치되며, 지속 상태를 파일과 버전 관리에 저장하고, 하나의 프로젝트 작업공간 안에서 전체 연구 순환을 지원하는 로컬 우선 연구 환경을 구축한다. 얇은 실행기나 여러 인터페이스가 노출하더라도 하나의 구현 런타임을 기준으로 유지한다. 프롬프트와 전문 스킬로 연구 작업을 안내하고, 작은 서비스가 상태를 영속화하고 복원하며 전달하도록 한다. 계속 확장되는 플랫폼보다 집중된 핵심에 최적화하고, 제안이 런타임, 공개 도구 또는 배포 범위를 넓힐 때마다 비목표를 명시한다. ## 기억이나 옛 계획보다 지금 파일과 실제 동작을 믿기 기억이나 오래된 계획이 아니라 현재 작업 사본에 실제로 존재하는 파일부터 시작한다. 제품 개요, 문서 색인, 유지관리자용 아키텍처, 개발 안내서, 해당 하위 시스템에 필요한 최소한의 참고 자료, 구현 코드, 관련 테스트를 읽는다. 자료가 서로 충돌하면 현재 런타임 동작과 통과한 계약 테스트를 먼저 따르고, 그다음 저장소 전체 안내서, 공식 유지관리자 문서, 보충용 기여자 참고 사항 순으로 따른다. 오래된 경로, 기능 주장 또는 워크플로를 남겨 두지 말고 부정확한 문서는 같은 변경에서 바로잡는다. 계획된 동작과 구현된 동작을 서로 다른 주장으로 취급한다. 구현, 구성, 통합, 문서, 테스트가 모두 뒷받침하기 전에는 구성 요소를 사용할 수 있다고 설명하지 않는다. ## 코드 기여자용 규칙과 도구 안 AI용 규칙을 나누기 저장소 기여자를 위한 지침과 제품 안에서 실행되는 에이전트를 통제하는 프롬프트 및 스킬을 구분한다. 런타임 계약은 특정 공개 도구나 제한된 실행 경로를 요구할 수 있지만, 저장소를 편집하는 유지관리자에게 같은 제한을 부과할 필요는 없다. 프롬프트, 스킬, 명령 또는 도구의 동작이 바뀔 때마다 이 경계를 보존한다. 제품 내부의 안전 계약을 저장소 기여 규칙으로 재해석하지 말고, 유지관리자가 더 폭넓은 로컬 개발 도구를 쓸 수 있다는 이유만으로 런타임 계약을 약화하지 않는다. ## 연구 프로젝트마다 버전 기록이 있는 폴더 하나에 담기 각 연구 프로젝트를 하나의 절대 프로젝트 루트를 가진 단일 버전 관리 저장소로 취급한다. 지속되는 모든 연구 내용을 그 루트 안에 보관하고, 서로 다른 접근 방식은 브랜치나 격리된 작업 트리로 표현하여 프로젝트 이력이 무관한 위치로 나뉘지 않게 한다. 개요서, 계획, 상태, 요약, 산출물, 기준선, 실험, 문헌, 인계, 원고, 메모리, 비공개 런타임 상태에 대한 명시적인 작업공간 계약을 유지한다. 런타임 캐시와 로그는 프로젝트 밖에 둘 수 있지만, 연구 증거의 유일한 사본이 되어서는 안 된다. 프로젝트 구조가 바뀌면 구조 모델, 영속성 서비스, 상태 스냅샷, API 소비자, 사용자 인터페이스, 테스트, 문서를 함께 갱신한다. 한 소비자만 마이그레이션하고 나머지를 오래된 구조에 남겨 두지 않는다. ## 시작 프로그램은 단순하게 두고 재시작 전에 지금 돌아가는 설정 확인하기 공식 연구 런타임은 하나의 구현 계층에 유지하고, 패키지 관리자 실행기는 그 런타임과 사전 빌드된 인터페이스 번들을 감싸는 얇은 어댑터로 만든다. 공개 설치 패키지에는 시작에 필요한 파일과 빌드된 클라이언트가 포함되어야 하며, 지원 경로를 작동시키기 위해 최종 사용자의 설치 후 빌드에 의존해서는 안 된다. 실행 중인 설치를 디버깅하거나 다시 시작하기 전에 실행 중인 프로세스, 실제 적용 구성, 기존 감독자 또는 실행기, 실제 런타임 실행 파일, 상태 확인 엔드포인트가 보고한 홈 경로를 점검한다. 기본 디렉터리만 보고 활성 홈, 구성 또는 프로세스 소유자를 추론하지 않는다. 패키지 매니페스트, 프로젝트 메타데이터, 공개 문서, 번들 구성에 대한 기대를 일치시킨다. 패키징이 완료되었다고 판단하기 전에 패키지 미리보기나 모의 실행으로 실제 배포될 파일 집합을 확인해야 한다. ## AI의 공개 도구를 적게 유지하고 새로 늘릴 때는 이유 밝히기 내장 공개 도구 범위를 영속 메모리, 버전이 지정된 산출물, 영속적 명령 실행이라는 몇 가지 안정된 책임으로 제한한다. 하위 시스템마다 새 공개 네임스페이스를 추가하지 말고, 버전 관리 동작은 산출물 경계 뒤에, 셸 실행은 실행 경계 뒤에 둔다. 프롬프트가 워크플로 기대 사항과 파일 시스템 계약을 정의하고, 스킬이 전문 실행 동작을 제공하게 한다. 상태 서비스는 얇게 유지해야 하며, 프롬프트와 스킬 계약으로 워크플로를 명확히 표현할 수 있다면 대규모 중앙 단계 스케줄러를 코드에 하드코딩하지 않는다. 새 공개 도구를 제안하려면 기존 책임으로는 수용할 수 없음을 입증하고, 영속성과 권한 모델을 정의하며, 모든 클라이언트를 갱신하고, 계약 테스트를 추가해야 한다. 단순한 편의성만으로는 충분하지 않다. ## 새 연동은 작은 목록으로 추가하고 다 갖춰질 때만 완료라고 하기 연구 실행기, 통신 채널, 커넥터 브리지, 스킬 검색, 관리형 로컬 도구, 선택적 어댑터에 작은 레지스트리를 사용한다. 큰 디스패치 분기나 하위 시스템별 조건문보다 일관된 등록, 조회, 목록 인터페이스를 우선한다. 런타임 어댑터, 레지스트리 메타데이터, 기본 구성, 유효성 검사, 서비스 및 명령줄 연결, 사용자에게 보이는 문서, 테스트가 모두 갖춰지기 전에는 통합이 구현되었다고 부르지 않는다. 한 계층이라도 빠지면 부분적인 통합이다. 선택적 어댑터는 핵심 경로 밖에 두고, 없을 때는 그 사실을 명시한다. 레지스트리 항목은 의존성을 몰래 설치하거나 외부 서비스에 접근하거나 로컬 구성을 변경하지 않고 기능과 호환성을 드러내야 한다. ## 브라우저와 명령 창에서 같은 프로젝트 상태와 기능 연결 통로(API)를 쓰기 브라우저와 터미널 인터페이스가 동일한 서비스 API, 상태 스냅샷, 이벤트 모델을 사용하도록 한다. API 경로나 이벤트가 바뀌면 같은 변경에서 서비스, 모든 클라이언트, 탐색 전제, 계약 테스트를 갱신한다. 인터페이스 전반에서 안정적인 프로젝트 중심 경로와 식별자를 유지한다. 사용자 인터페이스는 서로 다른 배치를 보여 줄 수 있지만, 별도의 상태 의미를 만들어 내거나 다른 지원 인터페이스가 관찰해야 하는 전이를 숨겨서는 안 된다. 일급 통신 채널을 일반 채널 및 브리지 모델의 구현으로 취급한다. 중요한 커넥터 하나가 고유한 영속성, 오류 처리 또는 수명 주기 규칙을 가진 별도 런타임이 되지 않게 한다. ## 조사부터 집필까지 연구 단계를 나누되 한 줄 순서로 강제하지 않기 발견, 기준선, 아이디어 형성, 실험, 분석, 집필, 마무리 같은 짧은 공식 진행 순서를 정의한다. 모든 중요한 활동이 하나의 선형 단계인 것처럼 가정하지 말고, 의사 결정을 여러 단계에 걸친 활동으로 유지한다. 접수 단계 감사, 도표 준비, 검토, 반박은 전문 활동으로 존재할 수 있지만, 현재 코드와 프롬프트 계약이 실제로 그렇게 정의하지 않는 한 기본 연쇄에 넣지 않는다. 이름이 붙은 단계는 시스템의 활성 기준점, 상태 전이, 사용자 문서와 일치해야 한다. 단계 동작은 시스템 프롬프트, 범위가 좁은 프롬프트 계약, 프롬프트 조립, 단계 스킬에 둔다. 단계 의미를 서비스 처리기, 인터페이스 코드, 임시 조건문 곳곳에 흩뜨리지 않는다. ## 사용자용 안내와 개발자용 문서를 나누기 사용자용 안내서를 유지관리자용 아키텍처 및 개발 참고 자료와 분리한다. 공개 문서는 현재 동작을 설명해야 하고, 유지관리자 문서는 계약, 확장 지점, 조정된 변경 요구 사항을 설명해야 한다. 임시 계획, 작업용 점검표, 비공개 경로 또는 내부 전용 메모를 공개 문서 트리에 두지 않는다. 연결된 문서 이름을 안정적으로 유지하고, 삭제된 파일에 대한 참조를 제거하며, 사용자에게 보이는 동작이 바뀌면 유지 중인 모든 번역을 갱신한다. 변경이 내부 유지관리만 영향을 준다면 사용자용 공지를 억지로 만들지 말고 공식 유지관리자 참고 자료를 갱신한다. 문서 범위는 동작 범위를 따라야 한다. ## 비밀번호와 개인 경로를 공유 파일에 넣지 않고 연구 기록 보존하기 특정 작업용 컴퓨터의 절대 경로, 자격 증명, 토큰, 로컬 캐시, 의존성 디렉터리, 일시적 빌드 출력, 테스트 캐시를 버전 관리에 커밋하지 않는다. 생성된 인터페이스 번들은 패키징 계약이 명시적으로 요구할 때만 공개 패키지에 포함한다. 지속적인 실험 기록, 문헌 메모, 기준선, 산출물, 원고를 프로젝트 경계 안에서 버전 관리 대상으로 유지한다. 요약하기 전에 원본 증거를 보존하고, 재현 가능한 결과를 인터페이스에만 표시되는 상태 메시지로 절대 대체하지 않는다. 릴리스 전에 공개 파일에서 유출된 비밀, 오래된 문서 이름, 비공개 참조, 생성 파일의 불일치를 검토한다. 테스트가 모두 통과했더라도 민감하거나 재현 불가능한 내용을 게시해도 되는 것은 아니다. ## 지금 코드를 먼저 살피고 작게 고치기 새 추상화를 제안하기 전에 기존 구현을 점검한다. 광범위하고 뒤섞인 리팩터링보다 작고 응집력 있는 변경을 우선하고, 먼저 관련 문서 중 최소 집합만 사용하며, 코드와 테스트를 기준으로 제안을 검증한다. 코드와 문서가 다르면 하나의 범위가 정해진 변경에서 둘 다 수정한다. 과거에 존재했다는 이유로 오래된 참조를 보존하지 말고, 실제 런타임, 프로세스, 구성, 홈을 식별하기 전에는 실행 중인 연구 서비스를 다시 시작하지 않는다. 진단과 변경을 분리한다. 공유 상태를 바꾸기 전에 관찰된 신호, 예상 동작, 영향을 받는 소비자, 가장 작은 수정 사항을 기록한다. ## 바꾼 코드와 함께 테스트와 문서를 고치고 관계없는 곳은 건드리지 않기 변경되는 하위 시스템에서 직접 영향을 받는 모든 계층을 갱신한다. - 프로젝트 구조 또는 지속 상태: 구조 모델, 영속성 서비스, 스냅샷, API 소비자, 상태 테스트 - 프롬프트 또는 단계 스킬: 프롬프트 원본, 조립, 스킬 정의, 미러링된 설치 프로그램, 동작 테스트, 사용자 안내서 - 메모리, 산출물 또는 명령 실행: 구현, 공개 경계, 서비스 테스트, 계약 문서 - 연구 실행기: 어댑터, 레지스트리, 기본 구성, 유효성 검사, 서비스 및 명령줄 연결, 안내서, 테스트 - 채널 또는 커넥터 브리지: 기본값, 유효성 검사, 채널 및 브리지 코드, 커넥터 안내서, 통합 테스트 - 관리형 로컬 도구: 레지스트리, 구체적 어댑터, 상태 확인 및 대상 해석 동작, 유지관리자 안내서, 테스트 - 공유 API 표면: 라우터, 처리기, 브라우저 클라이언트, 터미널 클라이언트, 탐색, 계약 테스트 - 패키징: 매니페스트, 프로젝트 메타데이터, 공개 개요, 필수 번들, 패키지 내용 검증 이 매트릭스를 무관한 하위 시스템으로 확장하지 않는다. 목적은 저장소 전체를 다시 작성하는 것이 아니라 직접 영향 경계 안에서 조정된 완전성을 확보하는 것이다. ## 끝내기 전에 문서대로 설치해 동작 확인하기 변경된 범위와 관련된 단위, 통합, 계약, 컴파일, 인터페이스 빌드, 패키징 검사를 실행한다. 실행기나 패키징 동작이 바뀌면 문서화된 공개 경로를 통해 시작하고, 서비스 직접 시작은 진단 경로로만 확인한다. 최종 변경 내역에서 무관한 수정, 오래된 생성 파일, 누락된 번역 문서, 지원되지 않는 기능 주장, 불완전한 클라이언트 갱신을 검토한다. 로컬에서 구성 요소 테스트 하나가 성공한 것과 지원되는 설치 및 인터페이스 경로가 작동한다는 증거를 구분한다. 실제 작업 사본을 최종 기준 정보로 사용한다. 참조된 파일이나 동작이 더 이상 존재하지 않으면 오류를 유지하지 말고 참조와 그 소비자를 바로잡는다.