CodeOps AI Agent | AI Agent

목차 15개 섹션

기술 가이드
개발환경 구축
AI Model 선정
모델 설치와 실행
학습과 튜닝
Vector DB 구축
RAG 개발
시스템 연계
검증과 운영
분야별 모델 선정
전체 아키텍처
Project ABC
데이터와 도구
마일스톤/산출물
기술 스택

Technical Blueprint

실전 AI Agent 개발 체크리스트

아이디어 설명보다 실행 가능한 개발 문서를 우선합니다. 로컬 실행, API 계약, RAG 데이터, tool 호출, 검증 루틴, 운영 fallback을 먼저 고정해야 AI Agent가 데모에서 실제 서비스로 넘어갈 수 있습니다.

1. 개발환경과 실행 기준

README 첫 화면에 `npm install`, `docker compose up`, `npm run build`, health check 명령을 순서대로 적습니다.
Node.js 22 LTS, Python 3.11 이상, Git, Docker Desktop, VS Code 또는 Cursor를 기본 개발환경으로 고정합니다.
프론트엔드는 Next.js, Agent API는 FastAPI 또는 Cloudflare Worker, Vector DB는 Chroma 또는 pgvector 중 하나로 시작합니다.
`.env.example`에는 모델명, API key, DB URL, vector collection, timeout, observability endpoint를 실제 변수명으로 남깁니다.
첫 커밋부터 build, API 단위 테스트, 대표 curl, k6 smoke test를 통과 기준으로 둡니다.

2. 모델과 비용 기준

업무를 대화, 문서 질의응답, 코드 생성, 데이터 분석, tool calling 중 하나로 먼저 분류합니다.
운영 후보 모델은 품질만 보지 말고 월 비용, p95 latency, JSON schema 준수율, 장애 fallback 가능성을 함께 비교합니다.
로컬 우선 프로젝트는 `llama3.1:8b`, `llama3.2:3b`, `gemma2:9b`, `nomic-embed-text`처럼 실제 설치할 모델명과 예상 용량을 문서에 적습니다.
API 모델을 병행할 경우 provider adapter를 두고 `MODEL_PROVIDER`, `MODEL_NAME`, `MODEL_TIMEOUT_SECONDS`로 전환 가능하게 만듭니다.
모델 평가는 대표 질문 30~50개 golden set으로 정확성, 근거성, 환각률, 응답 지연, 실패 유형을 표로 남깁니다.

3. API 계약과 로컬 실행

처음 고정할 endpoint는 `/health`, `/v1/chat`, `/v1/rag/query`, `/v1/agent/run` 네 가지로 충분합니다.
모든 응답에는 `answer`, `citations`, `model`, `latency_ms`, `trace_id`, `warnings`를 같은 형태로 반환합니다.
브라우저는 모델 provider나 노트북 API를 직접 호출하지 않고, 서버 사이드 API facade만 호출하게 설계합니다.
로컬 모델은 Ollama 또는 Docker Compose로 실행하고, 모델 목록 조회와 첫 chat completion curl을 문서에 포함합니다.
timeout, retry, max tokens, temperature, streaming 여부는 코드에 박지 말고 환경 변수로 분리합니다.

4. 프롬프트와 응답 정책

system prompt에는 역할, 금지 행동, 근거 부족 시 답변 방식, tool 사용 조건을 짧게 고정합니다.
초기에는 fine-tuning보다 prompt template, RAG 문서 품질, tool schema, JSON 응답 형식을 먼저 개선합니다.
금지 답변, 근거 부족 답변, 사용자 확인이 필요한 답변 예시를 golden set에 포함합니다.
업무별 출력은 자유 문장이 아니라 `summary`, `evidence`, `next_actions`, `confidence`, `needs_review` 같은 schema로 관리합니다.
프롬프트 변경 시 golden set 통과율과 실패 유형을 이전 버전과 비교합니다.

5. RAG 데이터 구축

문서 원본, chunk, embedding, metadata, ingestion version을 분리해 저장하고 재색인 명령을 README에 적습니다.
처음에는 문서 10개로 시작해 chunk 크기, overlap, metadata, 검색 결과를 눈으로 확인합니다.
검색 API는 `query`, `top_k`, `filters`, `min_score`를 명시하고 source id, title, page, score, chunk text를 반환합니다.
RAG 답변에는 citation을 필수로 두고, citation이 없으면 “근거 부족” 응답으로 fallback합니다.
문서 변경 감지, 증분 색인, 삭제 문서 tombstone, embedding version 변경 시 재색인 기준을 미리 정합니다.

6. Agent workflow 구현

workflow는 intent 분류, retrieval 필요 여부 판단, tool 호출, 답변 생성, 검증, fallback 순서로 나눕니다.
LangGraph를 쓰는 경우 각 node의 입력/출력 schema와 실패 시 다음 node를 문서화합니다.
Agent가 호출할 tool은 읽기 전용부터 시작하고, 쓰기 작업은 사람 승인 단계 뒤에 둡니다.
tool 호출에는 timeout, retry, rate limit, audit log, user permission check를 기본으로 붙입니다.
최종 답변은 근거, 다음 행동, 확인 필요 여부를 분리해 UI가 그대로 렌더링할 수 있게 반환합니다.

7. 시스템 연계와 보안

Agent는 DB를 직접 조회하지 않고 `stock_search`, `portfolio_summary`, `log_search`, `policy_check` 같은 제한된 tool API만 호출합니다.
외부 API와 내부 DB adapter에는 권한, rate limit, timeout, retry, 감사 로그를 기본으로 둡니다.
API key, JWT, session id, user id, request id의 책임 위치를 클라우드와 로컬 API 사이에서 명확히 나눕니다.
민감 정보는 prompt와 로그에 그대로 남기지 않고 masking 또는 별도 secure store로 분리합니다.
사용자 요청, tool 호출, 모델 응답, 최종 답변은 trace id로 연결해 장애 분석과 품질 개선에 활용합니다.

8. 검증과 운영 전환

Golden set으로 정답성, 근거성, 정책 위반, 출력 형식 준수율을 측정하고 변경 전후 결과를 비교합니다.
운영 전 최소 기준은 health check, smoke test, k6 p95 latency, API error rate, RAG hit rate, fallback rate입니다.
금융/교육/운영 자동화처럼 위험도가 높은 영역은 LLM 판단과 deterministic rule 검사를 반드시 분리합니다.
OpenTelemetry, Prometheus, Grafana 또는 최소 structured log로 latency, token usage, tool failure, retrieval hit rate를 관측합니다.
초기 배포는 읽기 전용 Agent와 사람 승인 기반 workflow로 시작하고, 충분한 검증 후 자동 실행 범위를 넓힙니다.

Model Selection

분야별 AI 모델 선정과 설치/활용

Coding 프로젝트에서 바로 POC를 시작할 수 있도록 추천 API 모델, 로컬 모델, 임베딩 모델과 설치/활용 기준을 정리합니다.

로컬/온프레미스 대안

Qwen2.5-Coder 7B, Qwen3 4B, Llama 3.2 3B

Embedding 모델

text-embedding-3-large 또는 code-search 특화 embedding 모델

실제 선택 모델과 Docker 설치 기준

1TB SSD, RAM 16GB 노트북에서는 Qwen2.5-Coder 7B를 Coding AI Agent 기본 로컬 모델로 선택합니다. 일반 tool calling과 짧은 업무 Agent는 Qwen3 4B를 함께 평가하고, 초저사양 fallback은 Llama 3.2 3B로 둡니다.

노트북 개발은 Ollama 로컬 설치 또는 Docker CPU 모드로 시작합니다. 파일 수정은 모델이 직접 하지 않고 patch planner와 승인 workflow를 거칩니다.

권장 서버 스펙

노트북 개발: SSD 1TB, RAM 16GB, CPU-only 기준으로 3B~7B Q4 모델을 권장합니다. 동시에 브라우저, IDE, DB, Docker를 모두 띄우면 응답이 느려질 수 있습니다.
권장 여유 공간: 모델 3~6GB, 임베딩 1~2GB, 코드 인덱스와 vector DB 5~20GB, Docker/캐시 여유 30GB 이상을 잡습니다.
대형 monorepo는 전체 저장소를 한 번에 넣지 말고 관련 디렉터리만 인덱싱하며, context는 4K~8K 토큰부터 시작합니다.

용량과 저장소

Qwen2.5-Coder 7B Q4 모델은 대략 4~5GB급으로 시작하고, Qwen3 4B는 약 2~3GB급, Llama 3.2 3B는 약 2GB급으로 잡습니다.
nomic-embed-text 같은 로컬 임베딩 모델은 약 1GB 내외로 보고, pgvector/Chroma 인덱스는 저장소 규모에 따라 5~20GB를 배정합니다.
저장소 원본, 벡터 인덱스, 테스트 실행 결과, patch draft를 분리 저장하고 secret scan 결과는 감사 로그로 남깁니다.

Docker 설치 명령

Ollama Docker CPU: `docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama`
코딩 모델: `docker exec -it ollama ollama pull qwen2.5-coder:7b`
일반 Agent/임베딩: `docker exec -it ollama ollama pull qwen3:4b` 및 `docker exec -it ollama ollama pull nomic-embed-text`
앱 설정: `LLM_BASE_URL=http://localhost:11434/v1`, `CODE_MODEL=qwen2.5-coder:7b`, `AGENT_MODEL=qwen3:4b`, `EMBEDDING_MODEL=nomic-embed-text`

설치 후 검증

`curl http://localhost:11434/api/tags`로 설치된 모델을 확인하고, 작은 저장소 1개에서 파일 20~50개만 먼저 인덱싱합니다.
샘플 이슈 5개, 실패 테스트 로그 5개, PR diff 5개로 원인 분석 정확도와 수정 계획 품질을 평가합니다.
`npm run build`, 단위 테스트, Playwright smoke test가 통과하기 전에는 PR 초안을 완료 상태로 표시하지 않습니다.
비밀키 노출, 위험 파일 삭제, 과도한 변경 범위, dependency lockfile 변경을 정책 테스트로 차단합니다.

선정 이유

Coding Agent는 자연어 응답보다 코드 구조 이해, multi-file reasoning, 테스트 실패 원인 분석, diff 생성 안정성이 중요합니다.
초기 POC는 고성능 API 모델로 정확도를 확보하고, 사내 코드 보안 요구가 있으면 coder 계열 로컬 모델을 별도 평가합니다.
코드 수정은 모델 단독 자동 적용보다 계획, 패치, 테스트, 리뷰 단계를 분리해야 회귀와 보안 위험을 줄일 수 있습니다.

설치와 구성

API형은 `.env`에 `LLM_MODEL=gpt-4.1`, `CODE_FAST_MODEL=gpt-4.1-mini`, `EMBEDDING_MODEL=text-embedding-3-large`처럼 분석/수정/요약 모델을 분리합니다.
로컬형은 vLLM 또는 Ollama로 coder 모델을 실행하고, 저장소 파일 접근은 `repo_search`와 `code_reader` tool로만 제한합니다.
코드 인덱싱은 파일 경로, 언어, symbol, import graph, 테스트 파일 매핑을 metadata로 저장하고 chunk는 함수/클래스 단위로 나눕니다.

활용 방식

`repo_search`로 관련 파일을 찾고, `code_reader`가 필요한 파일만 읽은 뒤 모델이 변경 계획과 위험 파일을 먼저 제시합니다.
`patch_planner`는 수정 후보를 만들고 `test_runner`가 관련 테스트를 실행한 뒤 실패 로그를 다시 모델에 전달합니다.
PR 리뷰는 correctness, security, performance, test coverage, maintainability 기준으로 구조화된 코멘트를 생성합니다.

주의점

비밀키, 인증 토큰, 고객 데이터가 prompt에 포함되지 않도록 secret scanner와 파일 제외 규칙을 먼저 적용합니다.
대규모 자동 변경, 의존성 업그레이드, 마이그레이션 스크립트 실행은 사람 승인 후 진행합니다.

Reference Architecture

전체 아키텍처 설계

AI Agent는 화면, 오케스트레이션, 도구 연계, 데이터 검색, 평가/운영 계층을 분리해야 변경과 검증이 쉬워집니다.

Presentation Layer

Next.js UI
Agent 실행 상태
근거/출처 표시
사용자 피드백 수집

Agent Orchestration

Prompt policy
Tool routing
Memory/session
Structured output

Tool & Integration

업무 API adapter
DB 조회 tool
문서 검색 tool
정책 검사 tool

Data & Retrieval

PostgreSQL
pgvector
문서 chunking
embedding/reranking

Evaluation & Ops

Golden set
Playwright
k6
OpenTelemetry/Prometheus

Project ABC

실제 프로젝트 진행을 위한 ABC

A는 구조 설계, B는 AI Agent 구현, C는 검증 기준입니다. 이 순서로 진행하면 데모가 아니라 운영 가능한 Agent로 확장하기 쉽습니다.

A. Architecture

저장소 검색, 코드 읽기, 테스트 실행, 패치 계획, PR 리뷰를 독립 tool로 분리합니다.
Agent는 이슈 이해, 영향 범위 검색, 수정 계획, 패치 초안, 테스트 결과 분석, 리뷰 초안 순서로 동작합니다.
코드 접근은 allowlist 경로와 read-only 기본 모드로 시작하고, 실제 파일 수정은 승인 단계를 둡니다.

B. Build

샘플 저장소 1개와 이슈 10개, 실패 테스트 로그 10개를 준비해 AI Agent 평가 세트를 만듭니다.
Tree-sitter 또는 언어별 parser로 함수/클래스 단위 인덱스를 만들고 관련 테스트 파일 매핑을 저장합니다.
초기 UI는 이슈 입력, 관련 파일 목록, 수정 계획, 테스트 결과, PR 리뷰 초안 패널로 구성합니다.

C. Check

수정 후 `npm run build`, 단위 테스트, Playwright smoke test를 실행해 회귀를 확인합니다.
비밀키 노출, 위험한 파일 삭제, 과도한 변경 범위를 정책 테스트로 차단합니다.
이슈 해결률, 테스트 통과율, 리뷰 코멘트 유효성, 평균 수정 시간을 핵심 지표로 봅니다.

Project Spec

데이터와 Agent 도구

데이터

Git repository
Issue/PR 설명
테스트 실패 로그
코딩 컨벤션 문서

Agent Tools

repo_search
code_reader
test_runner
patch_planner
pr_review

AI Agent 범위

이슈 요약과 영향 범위 분석
관련 파일/함수 검색
수정 계획 생성
테스트 케이스와 PR 리뷰 초안 작성

검증 기준

빌드 성공률
테스트 회귀 차단
보안 취약 패턴 차단
리뷰 코멘트 정확도

Execution

진행 마일스톤과 산출물

진행 마일스톤

샘플 저장소/이슈 세트 구성
코드 검색 인덱스 생성
Agent tool-call 연결
테스트 실행 연동
PR 리뷰 UI 구현

산출물

CodeOps Agent UI
코드 검색 API
테스트 실행 adapter
PR 리뷰 템플릿
코딩 Agent 평가 세트

Stack

기술 스택

Next.jsFastAPILangGraphTree-sitterGitHub APIPlaywright

실전 AI Agent 개발 체크리스트

1. 개발환경과 실행 기준

README 첫 화면에 `npm install`, `docker compose up`, `npm run build`, health check 명령을 순서대로 적습니다.
Node.js 22 LTS, Python 3.11 이상, Git, Docker Desktop, VS Code 또는 Cursor를 기본 개발환경으로 고정합니다.
프론트엔드는 Next.js, Agent API는 FastAPI 또는 Cloudflare Worker, Vector DB는 Chroma 또는 pgvector 중 하나로 시작합니다.
`.env.example`에는 모델명, API key, DB URL, vector collection, timeout, observability endpoint를 실제 변수명으로 남깁니다.
첫 커밋부터 build, API 단위 테스트, 대표 curl, k6 smoke test를 통과 기준으로 둡니다.

2. 모델과 비용 기준

업무를 대화, 문서 질의응답, 코드 생성, 데이터 분석, tool calling 중 하나로 먼저 분류합니다.
운영 후보 모델은 품질만 보지 말고 월 비용, p95 latency, JSON schema 준수율, 장애 fallback 가능성을 함께 비교합니다.
로컬 우선 프로젝트는 `llama3.1:8b`, `llama3.2:3b`, `gemma2:9b`, `nomic-embed-text`처럼 실제 설치할 모델명과 예상 용량을 문서에 적습니다.
API 모델을 병행할 경우 provider adapter를 두고 `MODEL_PROVIDER`, `MODEL_NAME`, `MODEL_TIMEOUT_SECONDS`로 전환 가능하게 만듭니다.
모델 평가는 대표 질문 30~50개 golden set으로 정확성, 근거성, 환각률, 응답 지연, 실패 유형을 표로 남깁니다.

3. API 계약과 로컬 실행

처음 고정할 endpoint는 `/health`, `/v1/chat`, `/v1/rag/query`, `/v1/agent/run` 네 가지로 충분합니다.
모든 응답에는 `answer`, `citations`, `model`, `latency_ms`, `trace_id`, `warnings`를 같은 형태로 반환합니다.
브라우저는 모델 provider나 노트북 API를 직접 호출하지 않고, 서버 사이드 API facade만 호출하게 설계합니다.
로컬 모델은 Ollama 또는 Docker Compose로 실행하고, 모델 목록 조회와 첫 chat completion curl을 문서에 포함합니다.
timeout, retry, max tokens, temperature, streaming 여부는 코드에 박지 말고 환경 변수로 분리합니다.

4. 프롬프트와 응답 정책

system prompt에는 역할, 금지 행동, 근거 부족 시 답변 방식, tool 사용 조건을 짧게 고정합니다.
초기에는 fine-tuning보다 prompt template, RAG 문서 품질, tool schema, JSON 응답 형식을 먼저 개선합니다.
금지 답변, 근거 부족 답변, 사용자 확인이 필요한 답변 예시를 golden set에 포함합니다.
업무별 출력은 자유 문장이 아니라 `summary`, `evidence`, `next_actions`, `confidence`, `needs_review` 같은 schema로 관리합니다.
프롬프트 변경 시 golden set 통과율과 실패 유형을 이전 버전과 비교합니다.

5. RAG 데이터 구축

문서 원본, chunk, embedding, metadata, ingestion version을 분리해 저장하고 재색인 명령을 README에 적습니다.
처음에는 문서 10개로 시작해 chunk 크기, overlap, metadata, 검색 결과를 눈으로 확인합니다.
검색 API는 `query`, `top_k`, `filters`, `min_score`를 명시하고 source id, title, page, score, chunk text를 반환합니다.
RAG 답변에는 citation을 필수로 두고, citation이 없으면 “근거 부족” 응답으로 fallback합니다.
문서 변경 감지, 증분 색인, 삭제 문서 tombstone, embedding version 변경 시 재색인 기준을 미리 정합니다.

6. Agent workflow 구현

workflow는 intent 분류, retrieval 필요 여부 판단, tool 호출, 답변 생성, 검증, fallback 순서로 나눕니다.
LangGraph를 쓰는 경우 각 node의 입력/출력 schema와 실패 시 다음 node를 문서화합니다.
Agent가 호출할 tool은 읽기 전용부터 시작하고, 쓰기 작업은 사람 승인 단계 뒤에 둡니다.
tool 호출에는 timeout, retry, rate limit, audit log, user permission check를 기본으로 붙입니다.
최종 답변은 근거, 다음 행동, 확인 필요 여부를 분리해 UI가 그대로 렌더링할 수 있게 반환합니다.

7. 시스템 연계와 보안

Agent는 DB를 직접 조회하지 않고 `stock_search`, `portfolio_summary`, `log_search`, `policy_check` 같은 제한된 tool API만 호출합니다.
외부 API와 내부 DB adapter에는 권한, rate limit, timeout, retry, 감사 로그를 기본으로 둡니다.
API key, JWT, session id, user id, request id의 책임 위치를 클라우드와 로컬 API 사이에서 명확히 나눕니다.
민감 정보는 prompt와 로그에 그대로 남기지 않고 masking 또는 별도 secure store로 분리합니다.
사용자 요청, tool 호출, 모델 응답, 최종 답변은 trace id로 연결해 장애 분석과 품질 개선에 활용합니다.

8. 검증과 운영 전환

Golden set으로 정답성, 근거성, 정책 위반, 출력 형식 준수율을 측정하고 변경 전후 결과를 비교합니다.
운영 전 최소 기준은 health check, smoke test, k6 p95 latency, API error rate, RAG hit rate, fallback rate입니다.
금융/교육/운영 자동화처럼 위험도가 높은 영역은 LLM 판단과 deterministic rule 검사를 반드시 분리합니다.
OpenTelemetry, Prometheus, Grafana 또는 최소 structured log로 latency, token usage, tool failure, retrieval hit rate를 관측합니다.
초기 배포는 읽기 전용 Agent와 사람 승인 기반 workflow로 시작하고, 충분한 검증 후 자동 실행 범위를 넓힙니다.

분야별 AI 모델 선정과 설치/활용

Coding 프로젝트에서 바로 POC를 시작할 수 있도록 추천 API 모델, 로컬 모델, 임베딩 모델과 설치/활용 기준을 정리합니다.

로컬/온프레미스 대안

Qwen2.5-Coder 7B, Qwen3 4B, Llama 3.2 3B

Embedding 모델

text-embedding-3-large 또는 code-search 특화 embedding 모델

실제 선택 모델과 Docker 설치 기준

노트북 개발은 Ollama 로컬 설치 또는 Docker CPU 모드로 시작합니다. 파일 수정은 모델이 직접 하지 않고 patch planner와 승인 workflow를 거칩니다.

권장 서버 스펙

노트북 개발: SSD 1TB, RAM 16GB, CPU-only 기준으로 3B~7B Q4 모델을 권장합니다. 동시에 브라우저, IDE, DB, Docker를 모두 띄우면 응답이 느려질 수 있습니다.
권장 여유 공간: 모델 3~6GB, 임베딩 1~2GB, 코드 인덱스와 vector DB 5~20GB, Docker/캐시 여유 30GB 이상을 잡습니다.
대형 monorepo는 전체 저장소를 한 번에 넣지 말고 관련 디렉터리만 인덱싱하며, context는 4K~8K 토큰부터 시작합니다.

용량과 저장소

Qwen2.5-Coder 7B Q4 모델은 대략 4~5GB급으로 시작하고, Qwen3 4B는 약 2~3GB급, Llama 3.2 3B는 약 2GB급으로 잡습니다.
nomic-embed-text 같은 로컬 임베딩 모델은 약 1GB 내외로 보고, pgvector/Chroma 인덱스는 저장소 규모에 따라 5~20GB를 배정합니다.
저장소 원본, 벡터 인덱스, 테스트 실행 결과, patch draft를 분리 저장하고 secret scan 결과는 감사 로그로 남깁니다.

Docker 설치 명령

Ollama Docker CPU: `docker run -d -v ollama:/root/.ollama -p 11434:11434 --name ollama ollama/ollama`
코딩 모델: `docker exec -it ollama ollama pull qwen2.5-coder:7b`
일반 Agent/임베딩: `docker exec -it ollama ollama pull qwen3:4b` 및 `docker exec -it ollama ollama pull nomic-embed-text`
앱 설정: `LLM_BASE_URL=http://localhost:11434/v1`, `CODE_MODEL=qwen2.5-coder:7b`, `AGENT_MODEL=qwen3:4b`, `EMBEDDING_MODEL=nomic-embed-text`

설치 후 검증

`curl http://localhost:11434/api/tags`로 설치된 모델을 확인하고, 작은 저장소 1개에서 파일 20~50개만 먼저 인덱싱합니다.
샘플 이슈 5개, 실패 테스트 로그 5개, PR diff 5개로 원인 분석 정확도와 수정 계획 품질을 평가합니다.
`npm run build`, 단위 테스트, Playwright smoke test가 통과하기 전에는 PR 초안을 완료 상태로 표시하지 않습니다.
비밀키 노출, 위험 파일 삭제, 과도한 변경 범위, dependency lockfile 변경을 정책 테스트로 차단합니다.

선정 이유

Coding Agent는 자연어 응답보다 코드 구조 이해, multi-file reasoning, 테스트 실패 원인 분석, diff 생성 안정성이 중요합니다.
초기 POC는 고성능 API 모델로 정확도를 확보하고, 사내 코드 보안 요구가 있으면 coder 계열 로컬 모델을 별도 평가합니다.
코드 수정은 모델 단독 자동 적용보다 계획, 패치, 테스트, 리뷰 단계를 분리해야 회귀와 보안 위험을 줄일 수 있습니다.

설치와 구성

API형은 `.env`에 `LLM_MODEL=gpt-4.1`, `CODE_FAST_MODEL=gpt-4.1-mini`, `EMBEDDING_MODEL=text-embedding-3-large`처럼 분석/수정/요약 모델을 분리합니다.
로컬형은 vLLM 또는 Ollama로 coder 모델을 실행하고, 저장소 파일 접근은 `repo_search`와 `code_reader` tool로만 제한합니다.
코드 인덱싱은 파일 경로, 언어, symbol, import graph, 테스트 파일 매핑을 metadata로 저장하고 chunk는 함수/클래스 단위로 나눕니다.

활용 방식

`repo_search`로 관련 파일을 찾고, `code_reader`가 필요한 파일만 읽은 뒤 모델이 변경 계획과 위험 파일을 먼저 제시합니다.
`patch_planner`는 수정 후보를 만들고 `test_runner`가 관련 테스트를 실행한 뒤 실패 로그를 다시 모델에 전달합니다.
PR 리뷰는 correctness, security, performance, test coverage, maintainability 기준으로 구조화된 코멘트를 생성합니다.

주의점

비밀키, 인증 토큰, 고객 데이터가 prompt에 포함되지 않도록 secret scanner와 파일 제외 규칙을 먼저 적용합니다.
대규모 자동 변경, 의존성 업그레이드, 마이그레이션 스크립트 실행은 사람 승인 후 진행합니다.

전체 아키텍처 설계

AI Agent는 화면, 오케스트레이션, 도구 연계, 데이터 검색, 평가/운영 계층을 분리해야 변경과 검증이 쉬워집니다.

Presentation Layer

Next.js UI
Agent 실행 상태
근거/출처 표시
사용자 피드백 수집

Agent Orchestration

Prompt policy
Tool routing
Memory/session
Structured output

Tool & Integration

업무 API adapter
DB 조회 tool
문서 검색 tool
정책 검사 tool

Data & Retrieval

PostgreSQL
pgvector
문서 chunking
embedding/reranking

Evaluation & Ops

Golden set
Playwright
k6
OpenTelemetry/Prometheus

실제 프로젝트 진행을 위한 ABC

A는 구조 설계, B는 AI Agent 구현, C는 검증 기준입니다. 이 순서로 진행하면 데모가 아니라 운영 가능한 Agent로 확장하기 쉽습니다.

A. Architecture

저장소 검색, 코드 읽기, 테스트 실행, 패치 계획, PR 리뷰를 독립 tool로 분리합니다.
Agent는 이슈 이해, 영향 범위 검색, 수정 계획, 패치 초안, 테스트 결과 분석, 리뷰 초안 순서로 동작합니다.
코드 접근은 allowlist 경로와 read-only 기본 모드로 시작하고, 실제 파일 수정은 승인 단계를 둡니다.

B. Build

샘플 저장소 1개와 이슈 10개, 실패 테스트 로그 10개를 준비해 AI Agent 평가 세트를 만듭니다.
Tree-sitter 또는 언어별 parser로 함수/클래스 단위 인덱스를 만들고 관련 테스트 파일 매핑을 저장합니다.
초기 UI는 이슈 입력, 관련 파일 목록, 수정 계획, 테스트 결과, PR 리뷰 초안 패널로 구성합니다.

C. Check

수정 후 `npm run build`, 단위 테스트, Playwright smoke test를 실행해 회귀를 확인합니다.
비밀키 노출, 위험한 파일 삭제, 과도한 변경 범위를 정책 테스트로 차단합니다.
이슈 해결률, 테스트 통과율, 리뷰 코멘트 유효성, 평균 수정 시간을 핵심 지표로 봅니다.

데이터와 Agent 도구

데이터

Git repository
Issue/PR 설명
테스트 실패 로그
코딩 컨벤션 문서

Agent Tools

repo_search
code_reader
test_runner
patch_planner
pr_review

AI Agent 범위

이슈 요약과 영향 범위 분석
관련 파일/함수 검색
수정 계획 생성
테스트 케이스와 PR 리뷰 초안 작성

검증 기준

빌드 성공률
테스트 회귀 차단
보안 취약 패턴 차단
리뷰 코멘트 정확도

COD CodeOps AI Agent AI Agent 프로젝트

실전 AI Agent 개발 체크리스트

1. 개발환경과 실행 기준

2. 모델과 비용 기준

3. API 계약과 로컬 실행

4. 프롬프트와 응답 정책

5. RAG 데이터 구축

6. Agent workflow 구현

7. 시스템 연계와 보안

8. 검증과 운영 전환

분야별 AI 모델 선정과 설치/활용

추천 API 모델

로컬/온프레미스 대안

Embedding 모델

실제 선택 모델과 Docker 설치 기준

권장 서버 스펙

용량과 저장소

Docker 설치 명령

설치 후 검증

선정 이유

설치와 구성

활용 방식

주의점

전체 아키텍처 설계

Presentation Layer

Agent Orchestration

Tool & Integration

Data & Retrieval

Evaluation & Ops

실제 프로젝트 진행을 위한 ABC

A. Architecture

B. Build

C. Check

데이터와 Agent 도구

데이터

Agent Tools

AI Agent 범위

검증 기준

진행 마일스톤과 산출물

진행 마일스톤

산출물

기술 스택

COD CodeOps AI Agent AI Agent 프로젝트

실전 AI Agent 개발 체크리스트

1. 개발환경과 실행 기준

2. 모델과 비용 기준

3. API 계약과 로컬 실행

4. 프롬프트와 응답 정책

5. RAG 데이터 구축

6. Agent workflow 구현

7. 시스템 연계와 보안

8. 검증과 운영 전환

분야별 AI 모델 선정과 설치/활용

추천 API 모델

로컬/온프레미스 대안

Embedding 모델

실제 선택 모델과 Docker 설치 기준

권장 서버 스펙

용량과 저장소

Docker 설치 명령

설치 후 검증

선정 이유

설치와 구성

활용 방식

주의점

전체 아키텍처 설계

Presentation Layer

Agent Orchestration

Tool & Integration

Data & Retrieval

Evaluation & Ops

실제 프로젝트 진행을 위한 ABC

A. Architecture

B. Build

C. Check

데이터와 Agent 도구

데이터

Agent Tools

AI Agent 범위

검증 기준