어떤 IDE에서든 Graftcode의 AI 코딩 규칙 설정 방법

코딩 어시스턴트는 개발 워크플로우에서 중요해지고 있습니다. 개발자들은 Claude Code, Cursor, GitHub Copilot, Windsurf 같은 도구를 사용하여 코드를 생성하고 수동으로 처리되던 작업을 자동화합니다.

문제는 이러한 도구들이 일반적으로 공통적인 개발 패턴을 따른다는 것입니다. 애플리케이션과 서비스를 연결하라는 요청을 받으면, 대부분의 현대 소프트웨어가 구축되는 방식인 REST API, 컨트롤러, 라우트(routes), 통합 계층 등을 생성하는 경우가 많습니다.

이 블로그 게시물에서는 Graftcode가 이 문제를 어떻게 해결하는지 배울 것입니다. Graftcode는 백엔드 메서드를 애플리케이션과 AI 에이전트가 API를 다루거나 REST 엔드포인트를 구축하거나 로직을 중복할 필요 없이 직접 호출할 수 있는 설치 가능한 패키지로 노출하는 도구입니다.

본 게시물은 해당 명령어가 무엇을 하는지, Graftcode 툴체인의 나머지 부분(Gateway, Grafts, 그리고 Graftcode Vision)에 어떻게 통합되는지, 그리고 실제 코드를 맡기기 전에 실제로 작동하는지 확인하는 방법을 안내합니다.

학습할 내용

이 게시물을 끝까지 읽으면 다음을 할 수 있게 됩니다:

• Graftcode가 무엇이며 어떤 문제를 해결하는지 설명할 수 있습니다.
• 단 하나의 명령어로 프로젝트에 Graftcode의 AI 에이전트 규칙을 설치할 수 있습니다.
• Gateway, Grafts, 그리고 규칙들이 어떻게 함께 작동하는지 이해합니다.
• Graftcode Gateway를 사용하여 모듈을 호스팅하고 이를 호출하는 Graft를 설치할 수 있습니다.
• AI 에이전트에게 모든 것이 올바르게 연결되었는지 확인하기 위한 첫 번째 안전한 프롬프트를 제공할 수 있습니다.

Graftcode란 무엇인가요?

Graftcode는 백엔드 함수와 메서드를 REST API를 수동으로 구축하거나, HTTP 클라이언트 코드를 작성하거나, 사용자 지정 SDK(Software Development Kit)를 생성할 필요 없이 다른 런타임에서 호출할 수 있게 해주는 도구입니다. Graftcode는 백엔드를 엔드포인트들의 집합으로 취급하는 대신, 애플리케이션이 패키지 관리자를 통해 설치하고 백엔드 메서드를 직접 호출하는 데 사용할 수 있는 강한 타입(strongly typed)의 Graft 패키지를 생성합니다.

Graftcode는 Gateway를 사용하여 선택된 백엔드 클래스와 메서드를 노출하고, 이를 Graft라고 불리는 패키지를 생성하여 애플리케이션에 직접 설치할 수 있게 합니다.

Graftcode 채택은 다음을 목표로 합니다:

• 애플리케이션 간에 REST, gRPC, Thrift 또는 기타 API 기반 통합과 같은 통신 계층을 수동으로 연결할 필요성을 줄입니다.
• 코드베이스 내의 통합 코드를 큰 폭으로 절감합니다.
• 읽어야 할 보일러플레이트(boilerplate)가 적어지기 때문에 AI 지원 개발이 더 쉬워지고, 이는 토큰 사용량 감소와 코드 리뷰 간소화로 이어집니다.
• 노출된 모든 메서드가 MCP 도구(tool)로 사용 가능하게 하여 AI 에이전트가 이를 직접 호출할 수 있게 합니다.
• 모듈을 독립적으로 개발하고, 노출하며, 재조합할 수 있는 모듈형 모놀리스(modular monoliths)를 지원합니다.

매번 세션을 시작할 때마다 코딩 에이전트에게 설명해야 할 움직이는 부분이 정말 많습니다.

Graftcode의 주요 구성 요소 (Major Components)

전제 조건 (Prerequisites)

• 터미널: Windows의 경우 PowerShell, 또는 Linux/macOS의 표준 셸
• 노출하려는 모듈 또는 라이브러리: Graftcode가 지원하는 런타임(.NET, Java, Python, Ruby, Node.js, 또는 PHP)으로 작성된 것
• 연결을 호출하는 측면을 위한 패키지 관리자 (npm, NuGet, pip 등, 클라이언트 언어에 따라 다름)
• 프로젝트 파일을 읽는 AI 코딩 에이전트: Graftcode Rules는 현재 Cursor, Claude Code, Claude Desktop, VS Code, Windsurf 및 기타 호환 IDE를 포함하여 선택된 에이전트형 IDE와 코딩 도우미를 지원합니다. 생성된 규칙은 일반 프로젝트 파일로 저장되며, 지원되는 도구가 코드 생성을 위해 읽고 사용할 수 있습니다.

1단계: Graftcode의 AI 규칙 설치 (Step 1: Install Graftcode's AI Rules)

에이전트가 작업할 프로젝트 루트 디렉토리에서 사용 중인 OS에 맞는 명령어를 실행하세요. 이 명령어들은 Graftcode의 메인 GitHub 저장소에 게시된 정확한 명령어입니다.

PowerShell:

iwr grft.dev/get | iex

Linux / macOS:

curl -fsSL grft.dev/get | sh

대안: wget 사용:

wget -qO- grft.dev/get | sh

Graftcode의 저장소에서는 이러한 규칙들이 프로젝트에서 어떻게 설정되는지 보여줍니다. AI 에이전트는 프롬프트만으로 모듈형 모놀리스(modular monolith)부터 분산 시스템(distributed system)까지 Graftcode를 기반으로 구축할 수 있으며, 이는 새로운 프로젝트 시작, 기존 애플리케이션 마이그레이션, 또는 기존 애플리케이션 확장 등 어떤 경우에도 가능합니다.

개발자들은 Graftcode 개념을 프롬프트에 반복적으로 설명하는 대신, 생성된 규칙에 의존하여 아키텍처 가이던스를 받을 수 있습니다. 이는 코딩 에이전트가 특히 더 크고 복잡한 시스템에서 더욱 일관되고 정확한 구현을 하도록 돕습니다.

만약 신뢰하기 전에 정확히 무엇이 설치되는지 확인하고 싶다면, 원시 규칙(raw rule) 및 명령어 파일은 Graftcode의 저장소 내 /rules 디렉터리에서 공개적으로 확인할 수 있습니다. Graftcode는 이 파일들이 Claude와 같은 에이전트가 코드를 생성하거나 리팩토링할 때 Graftcode를 이해하고 올바르게 사용할 수 있게 해준다고 설명합니다.

2단계: Graftcode 규칙 설치하기

생성된 규칙들은 코딩 에이전트에게 Graftcode 애플리케이션이 어떻게 구조화되어야 하는지 가르칩니다. 이 규칙들은 모듈 노출(exposing modules), Grafts 사용, Graftcode Gateway 작업, 그리고 전통적인 API 중심 아키텍처가 아닌 Graftcode 패턴을 사용하여 애플리케이션을 구축하는 방법에 대한 지침을 제공합니다.

설치되면, 이 규칙들은 프로젝트의 일부가 되어 지원되는 코딩 어시스턴트가 코드를 생성하거나 수정할 때 사용할 수 있게 됩니다.

2a: Graftcode Gateway 로컬 실행하기

모듈을 노출하고 이를 Graftcode를 통해 사용 가능하게 하려면, Graftcode Gateway를 실행해야 합니다.

graftcode-gateway 저장소에는 설치 과정과 런타임 옵션이 문서화되어 있습니다. 규칙들이 코딩 에이전트가 이 설정을 자동으로 진행하도록 안내할 수 있지만, 내부적으로 무슨 일이 일어나고 있는지 이해하는 것이 유용합니다.

1. 라이브러리 패키징하기
2. 출력 폴더로 이동하기
3. Graftcode Gateway 다운로드하기 (Gateway 설치 방법은 이 가이드를 참조하세요)

Windows 설치

iwr https://grft.dev/get | iex

Linux / macOS 설치

curl -fsSL https://grft.dev/get | sh

또는 wget 사용

wget -qO- https://grft.dev/get | sh

Gateway(gg)가 준비되면, 이를 빌드된 모듈에 연결합니다:

gg --modules ./MyService.dll

2b단계: 컨테이너에서 Gateway 실행하기

생성된 규칙은 또한 지원되는 코딩 어시스턴트가 Graftcode Gateway를 포함하는 Dockerfile 및 컨테이너화된 개발 환경을 생성하도록 지시할 수 있습니다.

이는 개발자가 로컬 컴퓨터에 Gateway를 수동으로 설치하고 실행하는 것에 국한되지 않음을 의미합니다. 프로젝트에 따라 에이전트는 필요한 컨테이너 구성을 생성하고 애플리케이션 환경의 일부로 Docker 내부에서 Gateway를 실행할 수 있습니다.

이 기능은 컨테이너화된 개발 워크플로우를 표준화하거나 여러 환경에 걸쳐 재현 가능한 설정을 원하는 팀에게 특히 유용합니다.

고급 Gateway 구성

더 많은 제어를 위해, Gateway는 여러 플래그(flags)를 허용합니다. Graftcode Vision이 활성화된 .NET Core 모듈을 호스팅하는 저장소의 전체 예시는 다음과 같습니다:

./gg --runtime netcore --modules /path/to/your.dll --GV --port 8888 --httpPort 8889 --mcpBaseClass Mynamespace.MyClass

이어서 플래그 테이블, 런타임 테이블, 그리고 GG_DEBUG 섹션은 기존과 동일하게 유지합니다.

또한, GG_DEBUG 환경 변수도 있는데, 이는 Gateway를 통과하는 원시 바이트 배열(raw byte arrays)에 대한 콘솔 로깅을 활성화합니다. 연결 문제를 디버깅하는 동안 정확히 무엇이 잘못되고 있는지 확인해야 할 때 유용합니다.

3단계: 에이전트가 Graft 통합을 생성하도록 하기

서비스가 Graftcode Gateway를 통해 실행되면, 다음 단계는 클라이언트를 이 서비스에 연결하는 것입니다. 지원되는 코딩 에이전트는 필요한 경우 필수 Graft 패키지를 설치하는 것을 포함하여, 설치된 규칙을 사용하여 이 통합을 자동으로 생성할 수 있습니다.

npm install --registry https://grft.dev/YOUR_PROJECT_ID @graft/your-service-name

어떤 메서드를 호출하기 전에, Graft가 실행 중인 Gateway 인스턴스를 가리키도록 구성해야 합니다:

import { GraftConfig } from "@graft/your-service-name";

GraftConfig.host = "ws://localhost:8080/ws";

호스트 값은 서비스를 노출하는 Gateway 인스턴스를 가리켜야 합니다. 다른 포트를 사용하거나 Project Key 배포를 사용하는 경우, Graftcode Vision 또는 배포 구성에서 제공하는 주소를 사용하세요.

import { EnergyPriceCalculator } from "@graft/your-service-name";

const price = await EnergyPriceCalculator.GetPrice();

Graftcode는 또한 해당 클라이언트를 최신 상태로 유지하는 것도 처리합니다. 노출된 API가 변경되면, 다른 모든 의존성 업데이트에서 표시되는 방식과 동일하게, 패키지 관리자에게 Graft의 새 버전이 사용 가능하다는 알림을 보냅니다.

4단계: AI 에이전트가 작업을 수행하도록 맡기기

규칙을 설치하고 2단계와 3단계에서 Gateway 및 Graft를 마련했다면, 모든 것을 에이전트에게 맡길 수 있습니다.

• Graftcode는 애플리케이션이 API 통합 코드를 수동으로 작성하는 대신 생성된 Grafts를 통해 백엔드 메서드를 호출할 수 있도록 합니다.
• 설치 과정은 매우 간단합니다: Windows에서는 iwr grft.dev/get | iex를, Linux/macOS에서는 curl -fsSL grft.dev/get | sh를 실행하면 코딩 에이전트에게 이 모델을 가르치는 AI 에이전트 규칙이 설치됩니다.
• 동일한 설치 명령어는 모듈을 실제로 호스팅하는 gg 바이너리를 다운로드하기 위한 Gateway 자체의 설정 단계에서도 나타납니다.
• gg는 여러 런타임을 지원하며 Graftcode Vision 및 MCP(Multi-Cloud Platform) 지원과 같은 기능을 제공합니다.
• 클라이언트는 일반 패키지 관리자를 통해 생성된 Graft를 설치하고 노출된 메서드를 직접 호출합니다.

규칙을 설치한다고 해서 Graftcode가 내부적으로 작동하는 방식이 바뀌는 것은 아닙니다. Gateway가 여전히 메서드를 호스팅하고, Graft가 여전히 이를 호출하며, Hypertube가 여전히 이 둘을 연결(bridge)합니다.

변화하는 것은 그 모델이 유용해지기 전에 누가 그것을 이해해야 하는가입니다. 개발자가 문서를 읽고 에이전트에게 수동으로 브리핑하는 대신, 에이전트는 Graftcode가 게시하는 동일한 지침을 읽고 다음에 코드를 두 조각 연결하라고 요청할 때 이를 적용합니다.