netlify-config

netlify-config 개요

netlify-config의 용도

netlify-config skill은 netlify.toml을 작성하고 조정할 때 참고하는 실전용 레퍼런스입니다. 빌드, 리다이렉트, 리라이트, 헤더, deploy context, 환경 변수, functions, edge functions를 Netlify 문법을 헷갈리지 않고 설정해야 할 때 netlify-config skill을 사용하세요.

누가 사용하면 좋은가

이미 Netlify에 무엇을 시키고 싶은지는 알고 있지만, 그 내용을 정확하고 안정적으로 표현해야 하는 빌더에게 가장 잘 맞습니다. netlify-config guide는 특히 리다이렉트 순서, catch-all 라우팅, context별 설정처럼 사소한 차이로 배포 결과가 쉽게 틀어지는 작업에서 유용합니다.

왜 유용한가

이 skill은 실제 deploy 동작에 영향을 주는 설정 요소에 집중합니다. 파일 위치, TOML 구조, 규칙 매칭, 그리고 condition이나 force 규칙 같은 Netlify 전용 옵션이 여기에 해당합니다. 그냥 프롬프트로 해결할지 netlify-config skill을 쓸지 고민 중이라면, 아이디어를 넓히는 것보다 정확성이 더 중요할 때 이 skill이 더 적합합니다.

netlify-config skill 사용 방법

skill 설치 및 불러오기

skills 워크플로에서 netlify-config install 흐름을 사용한 뒤, 시작점으로 skills/netlify-config/SKILL.md를 여세요. 이 리포지토리에서는 현재 이 skill을 단일 파일 레퍼런스로 제공하므로, 따로 찾아야 할 보조 스크립트나 부속 리소스는 없습니다.

목표를 쓸 수 있는 프롬프트로 바꾸기

netlify-config를 가장 잘 활용하는 방법은 막연한 요청이 아니라 구체적인 배포 목표에서 시작하는 것입니다. 좋은 입력에는 사이트 유형, 수정 중인 파일, 필요한 결과가 들어가야 합니다. 예를 들면: “프로덕션에서는 /docs/*가 /docs/index.html로 rewrite되도록 netlify.toml을 업데이트하되, 모든 deploy context에서 /api/*는 백엔드로 계속 proxy되게 해 주세요.”

먼저 읽을 부분부터 정하기

먼저 build settings와 redirects 예제를 보고, 그다음 변경 내용에 맞는 섹션을 확인하세요. headers, deploy contexts, functions, edge functions가 여기에 해당합니다. 실제로 netlify-config를 Deployment에 쓸 때 가장 빠른 방법은 원하는 라우팅 동작을 가장 비슷한 예제에 매핑한 뒤, 문법을 처음부터 지어내지 말고 그 예제를 기준으로 조정하는 것입니다.

결과 품질을 높이는 팁

현재 파일 경로, framework 출력 디렉터리, 그리고 이미 존재하는 충돌 규칙을 함께 알려 주세요. rewrite가 필요한지, redirect가 필요한지, proxy가 필요한지도 명시해야 합니다. 이 선택에 따라 올바른 status 값이 달라지고 force가 필요한지도 결정됩니다. monorepo에서 작업 중이라면 base directory를 분명히 적어 config가 정확한 위치에 들어가도록 하세요.

netlify-config skill FAQ

netlify-config는 netlify.toml만 위한 건가요?

네, netlify-config skill은 netlify.toml과 그 배포 동작을 중심으로 합니다. 문제가 더 넓은 Netlify 호스팅 전략에 걸쳐 있더라도, 핵심이 config 문법이나 rule 설계라면 이 skill이 여전히 도움이 됩니다.

일반 프롬프트로 충분한 경우는 언제인가요?

“Netlify redirects는 어떻게 동작하나요?”처럼 대략적인 아이디어만 필요할 때는 일반 프롬프트로도 충분합니다. 하지만 deploy-ready한 답이 필요하고, 특히 routing precedence, rewrites, context별 설정처럼 작은 문법 실수가 빌드를 깨뜨릴 수 있는 상황에서는 netlify-config skill이 더 낫습니다.

초보자도 쓰기 쉬운가요?

배포 목표를 평이한 언어로 설명할 수 있다면 그렇습니다. 큰 장벽은 skill 자체의 난이도가 아니라 입력이 불완전하다는 점입니다. 초보자는 현재 build command, publish folder, 그리고 바꾸고 싶은 path pattern을 함께 주면 더 좋은 결과를 얻습니다.

언제 사용하지 말아야 하나요?

아직 플랫폼을 고르는 중이거나, 변경 사항이 redirects, headers, build settings 중 어디에 들어가야 하는지 모른다면 netlify-config를 쓰지 마세요. 이 skill은 configuration용이지, 일반적인 Netlify 설명서나 사이트 아키텍처 조언자가 아닙니다.

netlify-config skill 개선 방법

정확한 라우팅 문제를 제공하기

netlify-config skill의 가장 강한 결과는 정확한 path 예시에서 나옵니다. “redirect를 고쳐 주세요”라고만 하지 말고, 이전 경로, 대상 경로, 원하는 status code, 예외 사항까지 같이 주세요. 그래야 skill이 301, 302, 200, 404 중 무엇을 써야 할지 애매하지 않게 판단할 수 있습니다.

배포 context와 제약 조건을 포함하기

Deployment용 netlify-config에서는 context가 중요합니다. production 전용 동작인지, preview deploy에서 다르게 처리해야 하는지, environment-specific variables가 있는지에 따라 정답이 달라집니다. 규칙이 전체에 적용돼야 하는지 아니면 특정 deploy context에서만 적용돼야 하는지 밝히고, 기존 CMS, SPA, API 제약도 함께 적어 주세요.

조언만 말고 최종 파일을 요청하기

유용한 netlify-config guide 요청은 바로 붙여 넣을 수 있는 정확한 netlify.toml snippet과, 파일 내 어디에 넣어야 하는지에 대한 짧은 설명까지 포함해야 합니다. 이렇게 하면 왕복 질문을 줄이고, 배포 전에 순서 오류를 더 쉽게 잡을 수 있습니다.

첫 배포 테스트 결과를 바탕으로 반복하기

첫 config를 작성한 뒤에는 실제 path 동작을 테스트하고, Netlify가 실제로 서빙하는 결과에 맞춰 다듬으세요. 자주 생기는 실패 원인에는 rule shadowing, force = true 누락, redirects와 rewrites를 혼동하는 문제가 있습니다. 다음 프롬프트에는 의도한 동작이 아니라 관찰된 동작을 적어야 합니다.