EtienneLescot/n8n-as-code

VS Code / Cursor Agent · n8n 환경 (Environments) · n8n-manager · GitOps · AI 기술 (Skills) · TypeScript 워크플로우 (Workflows)

실시간 n8n 컨텍스트를 가진 에이전트를 통해 에디터에서 n8n 워크플로우를 빌드, 편집, 배포 및 디버깅하세요.

n8n 버전 호환성— n8n-as-code에 포함된 노드 스키마 (node schema)는 n8n의 최신 안정 버전을 기준으로 구축되었습니다. 최상의 생성 및 검증 결과를 위해 n8n 인스턴스를 최신 상태로 유지하세요.

n8n-as-code는 저장소 (repository)를 완전한 n8n 개발 워크스페이스 (workspace)로 변환합니다:

기능 (Capability)	의미 (What it means)
에디터 네이티브 워크플로우 작업 (Editor-native workflow work)	VS Code, Cursor 또는 터미널 (terminal)에서 n8n 워크플로우를 탐색, 열기, 편집, 검증 및 동기화합니다.
에이전트 준비 컨텍스트 (Agent-ready context)	AI 에이전트가 실제 n8n 워크플로우에서 안전하게 작업할 수 있도록 근거 있는 지침, 스키마 (schemas), 예시 및 노드 지식을 생성합니다.
GitOps 스타일 동기화 (GitOps-style sync)	워크플로우를 명시적으로 풀 (pull) 및 푸시 (push)하고, 차이점 (diffs)을 검토하며, 충돌을 해결하고, 워크플로우 소스를 버전 관리 (version control) 시스템에 유지합니다.
TypeScript 워크플로우 작성 (TypeScript workflow authoring)	워크플로우를 사람과 에이전트가 편집하기 더 쉬운 읽기 가능한 .workflow.ts 파일로 변환합니다.
실시간 n8n 작업 (Live n8n operations)	선택된 n8n 환경 (environment)에 대해 워크플로우를 검증하고, 자격 증명 (credentials)을 검사하며, 테스트를 실행하고, 워크플로우를 활성화하며, 실행 (executions)을 조사합니다.

이 저장소는 워크플로우 파일, 생성된 에이전트 컨텍스트, 그리고 워크스페이스 안전 구성 (workspace-safe configuration)을 저장합니다. 비밀 값 (Secrets) 및 머신 로컬 런타임 상태 (machine-local runtime state)는 로컬에 유지됩니다.

• VS Code 마켓플레이스 (Marketplace) 또는 Open VSX에서 확장을 설치하세요.
• 폴더 또는 .code-workspace를 엽니다.
• 확장 아이콘을 클릭한 다음 톱니바퀴 아이콘을 클릭하여 워크스페이스를 구성하세요.
• n8n 환경 (n8n environment)을 생성하거나 선택하세요.
• 통합된 에이전트 워크벤치 (Agent Workbench) 또는 선택한 에이전트를 사용하여 워크플로우를 풀 (pull)하거나 생성하세요.

구성 UI는 CLI와 동일한 모델을 사용합니다: 워크스페이스 환경 (workspace environments)은 저장소 컨텍스트 (repository context)이며, 로컬 관리 인스턴스 (local managed instances)는 머신 리소스 (machine resources)입니다.

/plugin marketplace add https://github.com/EtienneLescot/n8n-as-code
/plugin install n8n-as-code@n8nac-marketplace

그다음 Claude에게 원하는 워크플로 (workflow)를 요청하세요. n8n-architect 스킬은 필요에 따라 워크스페이스 (workspace) 설정, n8n 컨텍스트 (context), 검증 (validation) 및 동기화 (sync) 단계를 처리합니다.

리포지토리 (repository)의 skills 디렉토리에서 스킬을 설치하세요:

그다음 에이전트 (agent)에게 원하는 워크플로를 요청하세요. 이 스킬은 에이전트가 나머지 작업을 처리하는 데 필요한 n8n 스키마 (schemas), 예시 (examples), 검증 규칙 (validation rules) 및 워크스페이스 명령 (workspace commands)을 제공합니다.

만약 에이전트가 명시적인 스킬 경로를 요청하면, skills/n8n-architect를 사용하세요.

기존 n8n URL에 대한 워크스페이스 환경을 생성합니다:

npx --yes n8nac env add Dev --base-url https://n8n.example.com --workflows-path workflows/dev
printf '%s' "$N8N_API_KEY" | npx --yes n8nac env auth set Dev --api-key-stdin
npx --yes n8nac env use Dev
...

또는 로컬 관리형 인스턴스 (local managed instance)를 연결합니다:

n8n-manager instance list
npx --yes n8nac env add Local --managed-instance <id> --workflows-path workflows/local
npx --yes n8nac env use Local

그다음 워크플로를 명시적으로 동기화합니다:

npx --yes n8nac list
npx --yes n8nac pull <workflow-id>
npx --yes n8nac push workflows/dev/my-workflow.workflow.ts --verify
...

promote를 사용하여 워크플로 소스 (workflow source)를 한 환경의 workflowsPath에서 다른 환경으로 이동하세요. 단일 워크플로에 대해 워크플로 경로를 전달하거나, 경로를 생략하면 중첩된 폴더를 포함하여 소스 환경의 모든 *.workflow.ts 파일을 프로모션 (promote)합니다. 프로모션은 대상 프로젝트의 메타데이터 (metadata)를 다시 작성하고, 자격 증명 (credentials) 및 지원되는 'Execute Workflow' 참조를 재매핑하며, n8nac-promotion.json에 안정적인 소스-대상 바인딩 (source-to-target bindings)을 기록합니다. 또한 --no-push가 설정되지 않는 한 기본적으로 푸시 (push)를 수행합니다. --dry-run은 정확한 생성/업데이트 계획을 위해 탐색 (discovery)을 수행하지만, 파일을 작성하거나 푸시하거나 프로모션 설정을 업데이트하지는 않습니다.

n8nac env list
n8nac env add Dev --base-url <url> --workflows-path workflows/dev
n8nac env add Local --managed-instance <id> --workflows-path workflows/local
...

이 리포지토리가 n8n에 연결되는 방식을 설명하는 모든 작업에는 n8nac env를 사용하세요.

n8nac workspace status --json
n8nac env status --json

env status --json을 사용하여 활성 환경의 준비 상태에 대한 신뢰할 수 있는 정보(source of truth)를 확인하세요.

n8n-manager instance list
n8n-manager instance create
n8n-manager instance start <id>
...

n8n-manager는 로컬 관리 인스턴스 및 머신 로컬 작업에만 사용하세요. 이를 워크스페이스의 신뢰할 수 있는 정보(source of truth)로 사용하지 마십시오.

n8nac env use Dev
n8nac list
n8nac pull <workflow-id>
...

동기화는 명시적입니다. 사용자가 요청하지 않는 한 아무것도 푸시(push)되거나 풀(pull)되지 않습니다.

Skills 레이어는 에이전트에게 노드 스키마(node schemas), 문서(docs), 예제(examples), 템플릿(templates), 검증 규칙(validation rules) 및 안전한 워크플로우 작업(safe workflow operations)과 같은 근거 있는 n8n 지식을 제공합니다.

npx --yes n8nac skills search "send slack message when google sheet is updated"
npx --yes n8nac skills node-info slack
npx --yes n8nac skills validate workflows/dev/my-workflow.workflow.ts

import { workflow, node, links } from '@n8n-as-code/transformer';
@workflow({ id: 'abc123', name: 'Slack Notifier', active: true })
export class SlackNotifierWorkflow {
...

n8nac convert workflow.json --format typescript
n8nac convert-batch workflows/ --format typescript

패키지 (Package)	기능	설치 (Install)
VS Code Extension	사이드바, 캔버스, 통합된 Agent Workbench 및 n8n 환경을 제공하는 에디터 경험	Marketplace
n8nac	워크스페이스 환경, 동기화, 검증, AI 컨텍스트 및 자동화를 위한 CLI	npx n8nac
Agent Skills	에이전트를 위한 휴대 가능한 AI 기술 및 내장된 n8n 지식	repo skills directory
@n8n-as-code/n8nac	프롬프트 컨텍스트 및 휴대 가능한 기술을 포함한 OpenClaw 플러그인	openclaw plugins install @n8n-as-code/n8nac
@n8n-as-code/transformer	JSON을 TypeScript 워크플로우로 변환하거나 그 반대로 변환	npm i @n8n-as-code/transformer

VS Code/Cursor 확장 프로그램: 시각적 워크플로우 워크스페이스 및 통합된 Agent Workbench. : 리포지토리 수준의 환경 신뢰할 수 있는 정보(source of truth). n8nac env : 준비 상태 및 통합 워크스페이스 마이그레이션. n8nac workspace

: 로컬 관리 인스턴스 (local managed instances), Docker 라이프사이클 (lifecycle), 터널 (tunnels), 그리고 머신 로컬 비밀값 (machine-local secrets). n8n-manager

Skills and MCP: 에이전트 (agents)를 위한 근거 있는 n8n 지식.

기여를 환영합니다.

• 프로젝트를 포크 (Fork) 하세요.

• 브랜치 (branch)를 생성하세요:
  git checkout -b feature/amazing

• 테스트를 실행하세요:
  npm test

• 풀 리퀘스트 (Pull Request)를 오픈하세요.

MIT License — 자유롭게 사용, 수정 및 배포 가능합니다.

제3자 커뮤니티 워크플로우 메타데이터 (workflow metadata) 및 다운로드 가능한 워크플로우 파일은 각각의 상위 라이선스 (upstream licenses)를 따릅니다.

n8n-as-code는

n8n이 존재하기 때문에 존재합니다.

이 프로젝트의 기반이 되는 워크플로우 자동화 플랫폼을 구축하고 유지 관리해 주시는 n8n 팀과 커뮤니티에 감사드립니다.