제품 개발에서의 캡슐과 AI 에이전트

캡슐 활용: 개발 자동화를 위한 AI 에이전트 통합

제품 개발에서 AI 에이전트는 엄격한 컨텍스트 구조가 필요합니다. 캡슐은 전문 지식을 미니멀리스트 형식으로 제공하며, 바로 사용 가능한 도구를 통해 예측 가능한 코드와 아키텍처 아티팩트 생성을 보장합니다. 이는 순차적 작업 중 발생하는 혼란스러운 아키텍처 진화를 제거합니다.

에이전트 모드와 구조의 역할

에이전트는 프로토타이핑과 제품 개발에 사용됩니다. 프로토타이핑에서는 제약 없이 빠른 결과에 초점을 맞춥니다. 제품 개발에서는 유지보수성, 가독성, 확장성과 같은 비기능적 요구사항이 필수적입니다.

구조가 없으면 에이전트는 임의적인 선택을 하여 서비스 일관성을 잃습니다. 캡슐은 세 가지 구성 요소로 이 문제를 해결합니다:

• 전문 지식: 추측 없이 패키징된 경험.
• 미니멀리즘: 컨텍스트 창을 위한 불필요한 정보 없이 핵심만 담음.
• 바로 사용 가능한 도구: 에이전트를 위한 메서드, 스킬, 인터페이스.

추가 프로젝트 컨텍스트는 AGENTS.md와 CLAUDE.md에 저장됩니다 — 스타일 가이드, 커밋 형식 등.

MCP 서버를 통한 지식 전달

전문 지식은 두 가지 도구를 가진 MCP 서버를 통해 에이전트에 전달됩니다:

• 프레임워크 문서: 원칙, 서비스 구조, BaseMethod 패턴, DI 컨테이너, 이벤트.
• archland.json 문서: 형식, 채우기 규칙, C4 다이어그램 생성.

분리는 토큰을 절약합니다: 에이전트는 관련 도구를 요청합니다. 문서는 에이전트 지향적입니다 — 명령형 스타일, 규칙, 알고리즘.

nsc-toolkit 프레임워크 문서 예시:

# nsc-toolkit 프레임워크: 코드 생성 가이드

이 문서는 올바른 코드 자동 생성을 위한 규칙과 템플릿 세트로 구성됩니다.

## 프레임워크 코어: 메서드 클래스 (BaseMethod)

구현 규칙:
- service.schema.json에서 복사된 정적 설정 속성을 선언합니다.
- 핵심 로직은 handler 메서드에서 구현됩니다.
- @inject 데코레이터를 사용하여 생성자를 통해 의존성을 주입합니다.
- 로깅에는 this.logger를 사용합니다.
- 이벤트 생성에는 this.emitter를 사용합니다.

규칙: service.schema.json의 각 RPC 호출에 대해 메서드를 생성합니다.
규칙: 컨테이너에는 현재 사용 중인 의존성만 바인딩해야 합니다.

archland.json 알고리즘:

각 서비스에 대한 생성 알고리즘:

1단계. 기본 정보:
  - service.schema.json 읽기 → 이름, 설명
  - 경로 작성: describePath, folderPath

2단계. DI 컨테이너 분석:
  - service.ts 읽기
  - 각 container.bind()에 대해 Dependency 객체 생성
  - 유형 및 외부 여부를 위한 태그 분석

3단계. 메서드 분석:
  - methods/의 각 클래스에 대해:
    설명을 위해 service.schema.json 읽기
    의존성 호출 및 이벤트 생성을 위한 코드 분석

4단계. 구독 분석:
  - processing/의 각 클래스에 대해:
    inversion.types.ts에서 DI 키 결정
    소스 서비스를 결정하기 위해 start() 메서드 분석

5단계. 모든 데이터를 단일 archland.json 객체로 수집

실습: ListOrders 메서드 추가

시나리오: @services/order 서비스에서 사용자 주문 목록을 조회하는 메서드를 HTTP API에 노출합니다.

개발자는 데이터 형식을 설명합니다. 에이전트는 service.schema.json에 스키마를 생성합니다:

"ListOrders": {
  "action": "ListOrders",
  "description": "사용자 주문 목록 조회",
  "request": {
    "type": "object",
    "properties": {
      "credentials": {
        "type": "object",
        "properties": {
          "user_id":  { "type": "string" },
          "space_id": { "type": "string" }
        },
        "required": ["user_id", "space_id"]
      }
    },
    "required": ["credentials"]
  },
  "response": {
    "type": "object",
    "properties": {
      "result": {
        "type": "object",
        "properties": {
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "order_id":   { "type": "string" },
                "product_id": { "type": "string" },
                "quantity":   { "type": "number" },
                "created_at": { "type": "string" }
              },
              "required": ["order_id", "product_id", "quantity", "created_at"]
            }
          }
        }
      }
    },
    "required": ["result"]
  }
}

에이전트 프롬프트:

@services/order 서비스에 새로운 ListOrders 메서드를 생성하세요.
메서드는 credentials에서 user_id를 받습니다.
반환: 주문 목록, 각 주문에는 order_id, product_id, quantity, created_at 필드가 있습니다.
@services/gate의 @services/gate/routes/orders.ts 엔드포인트 세트에 메서드를 노출하세요.

에이전트 작업 순서:

• CLAUDE.md 읽기 → MCP 문서 요청.
• service.schema.json에 스키마 추가.
• 템플릿을 사용한 코드 생성 실행.
• @inject, 포트를 사용한 비즈니스 로직 구현.
• 패턴에 따른 HTTP 엔드포인트 추가.
• 규칙에 따른 커밋 형성.

시간: 10분. 템플릿은 유사 작업에 재현 가능합니다.

아키텍처 앨범 생성

프롬프트: archland.json과 프로젝트의 아키텍처 앨범을 생성하세요.

에이전트는 MCP에서 문서를 검색하고, 서비스를 순회하며, 스키마, DI, 메서드, 구독을 분석합니다. 문제 영역의 C4 다이어그램과 함께 archland.json에 데이터를 수집합니다. 이 과정은 문서의 알고리즘에 기반하여 결정적입니다.

핵심 요약

• 캡슐은 제품 개발에서 에이전트를 위한 구조를 제공합니다.
• MCP 서버는 미니멀리스트 도구를 통해 전문 지식을 전달합니다.
• 문서는 명령형입니다: 에이전트를 위한 규칙, 알고리즘, 템플릿.
• 작업 자동화: 코드 생성, HTTP 엔드포인트, 아키텍처 앨범을 10분 내에.
• 예측 가능성: 혼란스러운 변경 없이 일관된 아키텍처.

— Editorial Team