고성능 AI 에이전트를 위한 프로젝트 구조 설계
AI 에이전트는 명확하고 일관된 프로젝트 구조에서 가장 잘 작동합니다. 초기에 핸드헬드 없이도 아키텍처를 이해하고, 테스트를 실행하며 환경과 상호작용할 수 있도록 하드웨어 기반의 프레임워크를 설정하는 것이 중요합니다. 이 원칙은 클라우드 코드, 커서 등 다양한 도구에 적용됩니다.
핵심 규칙 구성
프로젝트 루트에 단일 파일을 시작하세요 — CLAUDE.md 또는 사용 중인 에이전트에 맞는 대체 파일입니다. 디렉터리 구조, 주요 명령어, 일반적인 개발 지침을 정리하세요. 구현 세부사항은 피하세요. 코드 자체가 문서화 역할을 해야 합니다.
예시 기본 파일:
## 구조
├── src/ — 서비스 코드
├── tests/ — 테스트 스위트
├── migrations/ — Alembic 데이터베이스 마이그레이션
└── notebooks/ — 즉석 스크립트
## 명령어
- 테스트: `pytest tests/ -x`
- 린터: `ruff check . --fix`
- 마이그레이션: `alembic upgrade head`
- 실행: `docker compose up`이 구조는 아키텍처 설명이나 반복적인 작업에 대한 반복적 설명을 제거합니다. 코드 표준은 매뉴얼이 아닌 스크립트로 강제합니다.
에이전트가 실수를 할 경우, 맥락을 분석하세요. 메서드 중복이나 클래스 위치 오류가 발생하면 모듈형 규칙 파일을 추가하세요.
``
something-cool/
├── CLAUDE.md # 일반 규칙
├── src/
│ ├── auth/
│ │ ├── CLAUDE.md # SSO 규칙
│ │ └── ...
│ ├── billing/
│ │ ├── CLAUDE.md # 계약 기반 변경 사항
│ │ └── ...
``
설정이 불완전한 징후:
- 에이전트가 모듈을 수동으로 탐색함.
- 의존성이나 등록에 기본적인 오류 발생.
스킬을 통한 환경 통합
에이전트는 코드 외에도 로그, 메트릭, 데이터베이스와 상호작용합니다. 스킬을 활용해 외부 서비스를 통합하세요. 함수를 정의하고 실행 가능한 스크립트를 제공하세요.
스킬 구조:
.claude/
└── skills/
├── logs/
│ ├── SKILL.md
│ └── search_logs.py
├── metrics/
│ ├── SKILL.md
│ └── query_grafana.py
├── database/
│ ├── SKILL.md
``
로그용 예시 `SKILL.md`:
name: logs
description: 애플리케이션 로그 검색 및 분석
allowed-tools: Bash, Read
다음 스크립트를 사용하여 로그를 검색하세요:
python .claude/skills/logs/search_logs.py --query "error" --since "1h"
python .claude/skills/logs/search_logs.py --trace-id "abc123"
이제 에이전트는 독자적으로 인사이트를 수집하고 문제를 진단할 수 있습니다.
### 다중 리포지토리 및 팀 호환성
공개 마켓플레이스나 내부 솔루션을 통해 스킬을 프로젝트 간 공유하세요. 이는 동료들이 쉽게 참여할 수 있도록 장벽을 낮춥니다.
팀 내 여러 에이전트를 일치시키기 위해 **rulesync**라는 CLI 도구를 사용하세요. 하나의 소스에서 25개 이상의 도구용 지침 파일을 자동 생성합니다.
Rulesync 구조:
.rulesync/rules/
├── overview.md # root: true
├── auth.md # globs: ["src/auth/**"]
└── billing.md # globs: ["src/billing/**"]
``
프론트마터 포함 마크다운 파일:
---
root: false
globs: ["src/auth/**"]
targets: "*"
description: SSO 통합 규칙
---
규칙 내용 여기에 작성생성 명령:
rulesync generate --targets "claudecode"rulesync generate --targets "cursor"rulesync generate --targets "copilot"
결과: CLAUDE.md, .cursorrules, copilot-instructions.md가 올바른 위치에 배치됩니다.
감시를 위한 백그라운드 에이전트
스타일, 구조, 죽은 코드를 모니터링하기 위해 백그라운드 에이전트를 추가하세요.
``
claude -p "스타일 점검: 이름 규칙, 구조, 죽은 코드" \
--allowedTools "Read,Grep,Glob"
``
이로써 코드 리뷰를 자동화할 수 있습니다.
핵심 요약
- 모듈형 규칙: 하위 디렉터리에
CLAUDE.md를 두어 맥락적 명확성을 확보하세요. - 환경 스킬: 로그, 메트릭, DB 접근을 위한 스크립트와 지침 제공.
- Rulesync: 다중 에이전트 일관성을 위한 단일 소스.
- 진화: 오류 발생 시 규칙을 확장하세요.
- 최소주의: 구현 세부사항은 제외하고, 구조와 명령어에 집중하세요.
— Editorial Team
아직 댓글이 없습니다.