600줄로 만드는 AI 에이전트
이 저장소는 600줄의 TypeScript 코드로 직접 AI 코딩 에이전트를 만들어보는 튜토리얼 프로젝트예요. 마치 레고 블록을 조립하듯이, 파일을 읽고, 코드를 수정하고, 명령어를 실행하는 작은 AI 비서를 처음부터 차근차근 만들 수 있어요. 실제로 동작하는 코드와 함께 설명이 제공되어서, AI 에이전트의 내부 동작 원리를 쉽게 이해할 수 있습니다.
이 레포, 나한테 필요한가?
사람 검수 전
- 무엇인가
- 이 저장소는 600줄의 TypeScript 코드로 직접 AI 코딩 에이전트를 만들어보는 튜토리얼 프로젝트예요.
- 마치 레고 블록을 조립하듯이, 파일을 읽고, 코드를 수정하고, 명령어를 실행하는 작은 AI 비서를 처음부터 차근차근 만들 수 있어요.
- 실제로 동작하는 코드와 함께 설명이 제공되어서, AI 에이전트의 내부 동작 원리를 쉽게 이해할 수 있습니다.
[README-001]- 할 수 있는 일
- AI 코딩 에이전트 [README-001]
- 진입 조건
- 중급자용 · TypeScript [분석]
- 먼저 확인
- 실행하려면 OpenAI 호환 API 키가 필요하며, 키 없이는 로컬 실행이 불가능합니다. [README-001]
이걸로 실제로 할 수 있는 일
기능명보다 사용자가 완성할 수 있는 작업과 결과를 우선해 정리했습니다.
AI 코딩 에이전트
파일을 읽고, 코드를 수정하고, 명령어를 실행하는 AI 비서를 직접 만들어볼 수 있습니다.
교육용 튜토리얼 사이트
코드와 설명이 함께 제공되는 인터랙티브 웹사이트를 통해 학습할 수 있습니다.
커스텀 AI 도구
자신만의 도구 호출(tool-calling) 로직을 추가하여 확장할 수 있습니다.
기능보다 중요한 건
내 상황과의 적합성.
공식 기능과 시작 조건을 바탕으로 한 AI 판단입니다. 도입 전 원문과 실제 환경에서 다시 확인하세요.
- AI 에이전트의 내부 동작 원리를 학습하고 싶은 경우
- 600줄 내외의 간결한 코드로 코딩 에이전트를 직접 구현해보고 싶은 경우
- TypeScript와 LLM API를 활용한 도구 호출(tool-calling) 패턴을 배우고 싶은 경우
- 이미 완성된 AI 에이전트 프레임워크가 필요한 경우 (이 프로젝트는 교육용입니다)
- 프로덕션 환경에서 바로 사용할 수 있는 AI 에이전트가 필요한 경우
기술과 도입 조건
자동 감지된 기술 스택, 문서 상태와 유지보수 메모를 한곳에 모았습니다.
TypeScript 5.6 · Node.js 22+ · Vitest 2.1 · tsx 4.19 · OpenAI 호환 API
README에 설치 및 실행 가이드가 명확히 제공됨 온라인 튜토리얼 사이트가 별도로 운영됨
최근 1일 이내 push 기록이 있습니다. 유지보수 품질과 응답 속도는 별도 확인이 필요합니다.
가장 짧은 시작 경로
- 01설치
npm install로 의존성을 설치합니다.
- 02실행
NANOPI_API_KEY 환경 변수를 설정하고 npm run dev로 실행합니다.
GitExplain 자동 분석은 설치 명령을 직접 실행해 검증한 결과가 아닙니다.
아래 내용을 Codex 같은 코딩 에이전트에 붙여 넣으면 공식 문서를 다시 확인한 뒤 내 환경에 맞는 설치를 안내합니다.
너는 내 로컬 개발 환경에서 오픈소스 저장소를 안전하게 설명하고 설치하는 시니어 엔지니어야.
저장소: https://github.com/saladday/pi-from-scratch
GitExplain 요약: 이 저장소는 600줄의 TypeScript 코드로 직접 AI 코딩 에이전트를 만들어보는 튜토리얼 프로젝트예요. 마치 레고 블록을 조립하듯이, 파일을 읽고, 코드를 수정하고, 명령어를 실행하는 작은 AI 비서를 처음부터 차근차근 만들 수 있어요. 실제로 동작하는 코드와 함께 설명이 제공되어서, AI 에이전트의 내부 동작 원리를 쉽게 이해할 수 있습니다.
주요 언어: TypeScript
난이도 메모: 중급자용
해야 할 일:
1. 먼저 저장소의 최신 README, 설치 문서, manifest를 읽고 현재 기본 브랜치 기준으로 설명해줘.
2. 이 저장소가 무엇이고 내가 무엇을 만들 수 있는지 비개발자도 이해할 수 있게 짧게 설명해줘.
3. 내 운영체제와 기존 개발 환경을 먼저 질문한 다음, 가장 안전한 설치 방법을 단계별로 제시해줘.
4. 명령을 실행하기 전 각 명령이 바꾸는 것과 예상 결과를 알려줘. 파괴적인 명령은 자동 실행하지 마.
5. 필요한 API 키나 비밀 값은 채팅이나 코드에 직접 적게 하지 말고 환경 변수와 .env 예시로 안내해줘.
6. 설치 후 최소 예제를 실행해 성공 여부를 확인하고, 실패하면 오류 원인과 되돌리는 방법을 알려줘.
7. GitExplain 요약과 공식 문서가 다르면 공식 문서를 우선하고 차이를 명시해줘.
GitExplain이 정리한 시작 메모:
1. 설치: npm install로 의존성을 설치합니다.
2. 실행: NANOPI_API_KEY 환경 변수를 설정하고 npm run dev로 실행합니다.도입 전에 놓치기 쉬운 점
실행하려면 OpenAI 호환 API 키가 필요하며, 키 없이는 로컬 실행이 불가능합니다.
[HIGH · README-001]Node.js 22 이상이 필요하며, 이전 버전에서는 호환성 문제가 발생할 수 있습니다.
[MEDIUM · README-001]근거 원장
이 표는 원문이 어떤 분석 항목에 연결됐는지를 보여주며, 사실 정확도를 보증하는 점수는 아닙니다.