provider-docs

provider-docs 개요

provider-docs가 하는 일

provider-docs 스킬은 Terraform Provider용 Terraform Registry 문서를 생성, 수정, 검증하는 데 도움을 줍니다. 일반적인 문장 재작성 도구가 아니라, schema 설명과 tfplugindocs 템플릿을 바탕으로 정확한 문서를 만들어야 하는 provider 작성자와 기술 문서 작성자를 위해 만들어졌습니다.

어떤 경우에 가장 잘 맞는가

provider 동작을 바꾸고 문서도 그에 맞게 유지해야 할 때 provider-docs 스킬을 사용하세요. provider configuration, resources, data sources, ephemeral resources, list resources, functions, guides처럼 문서와 구현이 함께 움직여야 하는 경우에 특히 유용합니다. 코드와 생성된 Registry 출력이 사실상의 단일 진실 원천인 Technical Writing 워크플로에 잘 맞습니다.

무엇이 다른가

이 스킬은 HashiCorp 스타일 구조에 맞게 최적화되어 있습니다. schema 기반 필드 설명, 기대되는 docs/ 레이아웃의 템플릿 파일, 그리고 릴리스 흐름을 고려한 Registry 게시까지 염두에 둡니다. 핵심 가치는 코드에 무엇을 넣고 템플릿에는 무엇을 둘지, 그리고 생성 문서를 어떻게 실제로 배포 가능한 상태로 유지할지에 대한 시행착오를 줄여주는 데 있습니다.

provider-docs 스킬 사용 방법

설치하고 올바른 파일을 불러오기

npx skills add hashicorp/agent-skills --skill provider-docs로 설치하세요. 첫 번째 맥락 파악을 위해서는 SKILL.md, references/hashicorp-provider-docs.md, agents/openai.yaml을 읽어보는 것이 좋습니다. 저장소 구조가 명확하지 않다면, 무엇이든 수정하기 전에 agents/와 references/ 폴더부터 살펴보세요.

대략적인 작업을 바로 쓸 수 있는 프롬프트로 바꾸기

provider-docs install 단계는 시작점일 뿐입니다. 이 스킬은 정확히 어떤 Terraform 객체를 다루는지, 그리고 기대하는 문서 결과가 무엇인지 프롬프트에 명시할 때 가장 잘 작동합니다. 예를 들어, “새 timeout 인자를 추가한 뒤 foo resource와 bar data source의 provider-docs 사용 문서를 업데이트하고, schema 설명과 docs/*.md.tmpl 예제가 구현과 일치하도록 해줘”처럼 요청하는 편이 좋습니다. 단순히 “문서 써줘”라고 하는 것보다 훨씬 낫습니다. 이 스킬은 코드 변경을 구체적인 Registry 대상에 매핑할 수 있기 때문입니다.

repo 우선 워크플로를 따르기

먼저 schema 설명을 정리하고, 그다음 docs/ 아래의 대응 템플릿 파일을 갱신한 뒤, tfplugindocs로 문서를 생성하세요. 저장소가 그렇게 연결되어 있다면 go generate ./...를 우선하는 편이 좋습니다. 이 순서가 중요한 이유는, 생성되는 Registry 페이지가 템플릿을 확정하기 전에 schema 텍스트가 정확해야 하기 때문입니다.

게시 전에 확인할 것

각 템플릿 경로가 실제 provider 객체와 맞는지 확인하세요: docs/index.md.tmpl, docs/resources/<name>.md.tmpl, docs/data-sources/<name>.md.tmpl, docs/ephemeral-resources/<name>.md.tmpl, docs/list-resources/<name>.md.tmpl, docs/functions/<name>.md.tmpl, docs/guides/<name>.md.tmpl. 또한 릴리스 태그가 v 규칙을 따르는지, terraform-registry-manifest.json이 유효한지도 확인해야 합니다. Registry 렌더링은 이 두 가지 모두에 의존합니다.

provider-docs 스킬 FAQ

provider-docs는 생성 문서에만 쓰는 건가요?

대체로 그렇습니다. provider-docs 스킬은 schema 설명과 템플릿에서 문서를 생성할 때 가장 강합니다. 일회성 마케팅 페이지나 일반적인 제품 설명이 필요하다면, 보통의 프롬프트가 더 적합합니다.

Terraform 전문가여야 하나요?

반드시 그렇지는 않지만, 문서를 움직이는 provider 객체 이름과 코드 변경 내용은 알아야 합니다. 적절한 resource, data source, function을 정확히 지정할 수 있다면, 문서 업데이트에서는 초보자도 충분히 활용할 수 있습니다.

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

Terraform Registry 출력과 무관한 문서에는 provider-docs를 사용하지 마세요. 또한 provider 구현이 아직 흔들리고 있어서 schema가 곧 다시 바뀔 상황이라면 지금은 적합하지 않습니다. 이런 경우에는 인터페이스가 안정된 뒤, 최종 형태를 기준으로 provider-docs 가이드를 생성하는 편이 낫습니다.

일반 프롬프트와 비교하면 어떤가요?

일반 프롬프트는 초안을 작성할 수는 있지만, provider-docs는 provider 문서를 실제로 배포 가능하게 만드는 Registry 워크플로, 파일 레이아웃, 릴리스 제약을 더 잘 지킵니다. 그래서 초안 텍스트에서 tfplugindocs 출력으로 넘어갈 때 재작업이 줄어듭니다.

provider-docs 스킬 개선 방법

목표만 말하지 말고 구현 사실을 함께 주기

가장 좋은 provider-docs 활용은 구체적인 입력에서 시작합니다. 어떤 provider 객체가 바뀌었는지, 새 인자나 동작이 무엇인지, 기본값이나 computed 값이 바뀌었는지, 어떤 예제를 업데이트해야 하는지를 함께 알려주세요. “foo resource에 기본값 3인 retry_count 필드를 추가하고 문서화해줘”는 “문서를 개선해줘”보다 훨씬 유용합니다.

흔한 실패 패턴을 경계하기

가장 큰 위험은 보기에는 그럴듯하지만 schema 동작과 맞지 않는 템플릿 문장을 쓰는 것입니다. 필드가 required인지, optional인지, computed인지, 또는 조건부로 설정되는지라면 schema 설명과 예제 맥락에서 이를 분명히 밝혀야 합니다. 그 일치가 있어야 생성 문서가 신뢰할 수 있습니다.

생성 결과를 기준으로 반복 개선하기

첫 번째 패스 이후에는 렌더링된 Registry 미리보기를 확인하고, 템플릿 파일만 보지 말고 provider 코드와 직접 비교하세요. 표현이 모호하면 먼저 schema 설명을 다듬고, 예제가 오해를 부르면 템플릿을 조정하고, 섹션이 빠졌다면 내용을 다시 쓰기 전에 docs/ 경로와 객체 이름부터 점검하세요.