사람과 AI 에이전트 모두 n8n Docs를 읽습니다. 두 사용자 유형이 문서에 요구하는 바는 서로 다른 점보다 겹치는 점이 더 많습니다. 다만 에이전트에게는 문서를 효과적으로 파싱하고 탐색하기 위한 몇 가지 고유한 요구 사항이 있습니다.

이 페이지는 n8n Docs에서 에이전트 친화적이라는 말이 무엇을 뜻하는지, 그리고 왜 중요한지 설명합니다. 이 지침은 문서를 작성하는 기여자나 n8n Docs의 접근 방식에 관심 있는 모든 사용자에게 유용합니다.

n8n Docs에서 이것이 중요한 이유#

두 부류의 겹치는 독자가 브라우저 대신 에이전트를 통해 n8n Docs를 사용합니다.

• 사람들이 검색 대신 AI 에이전트에게 묻습니다. 문서 트래픽 중 점점 더 많은 부분이 사람이 사이트 내비게이션을 따라 페이지를 직접 보는 것이 아니라, AI 어시스턴트와 검색 에이전트가 질문에 답하려고 페이지를 가져오는 데서 발생합니다.
• 사람들이 코딩 에이전트로 n8n을 사용해 빌드합니다. 워크플로, 노드, 통합을 작성하는 사람들은 점점 더 AI 코딩 도구를 사용합니다. 이 도구들은 오래된 학습 데이터 대신 최신의 정확한 정보를 바탕으로 작업하기 위해 n8n Docs를 직접 가져옵니다.

"에이전트 친화적"의 의미#

이 기준은 네 가지 계층으로 나뉩니다.

기계가 읽을 수 있는 전달 방식#

에이전트에게는 전체 웹 페이지를 렌더링하지 않고 콘텐츠를 가져올 방법이 필요합니다. n8n Docs는 여러 경로를 제공합니다.

• Markdown: 모든 페이지를 렌더링된 HTML뿐 아니라 깔끔한 Markdown으로도 볼 수 있습니다.
• llms.txt: llms.txt와 llms-full.txt는 이 형식을 지원하는 에이전트를 위해 게시된 모든 페이지를 나열합니다.
• MCP 서버: MCP 서버가 문서를 MCP 클라이언트에 직접 제공합니다. n8n 문서 MCP 서버에 연결하기를 참고하세요.
• AI 검색: AI 기반 검색(Kapa.ai)이 문서, 블로그, 커뮤니티 포럼에서 직접 질문에 답합니다.
• Context7: Context7이 n8n Docs를 색인하므로 에디터 안의 코딩 에이전트가 빌드하는 동안 최신 문서를 가져올 수 있습니다.

사이트 전체의 일관성#

• 용어: n8n Docs는 같은 개념에 어디서나 같은 용어를 사용합니다. 이는 사람 사용자와 에이전트 모두의 혼란을 줄입니다. 용어 및 명칭을 참고하세요.
• 안정적인 URL: 페이지 이름을 바꿔도 URL은 안정적으로 유지되며, URL이 바뀔 때마다 리디렉션을 설정합니다.
• 기능 제공 여부: n8n 버전이나 플랜에 따라 달라지는 사실은 적용되는 범위에 배치합니다. 페이지나 섹션 전체에는 hint, 지나가듯 언급할 때는 문장 안, 표의 행에는 표 셀에 둡니다. 따라서 페이지의 일부분만 가져오는 에이전트도 올바른 맥락을 확인할 수 있습니다. 기능 제공 여부를 참고하세요.
• 검토 프로세스: 새 페이지와 수정 사항은 게시되기 전에 n8n Docs의 공개 GitHub 리포지터리에서 일관성과 기술적 정확성을 검토받습니다. 검토는 사람 검토자와 n8n Docs의 AI 검토자 cubic이 함께 수행합니다.

구조와 내비게이션#

• 페이지 길이: n8n Docs는 콘텐츠를 에이전트가 잘리지 않고 가져올 수 있을 만큼 짧고 초점이 분명한 페이지로 나눕니다. 검색과 문서 어시스턴트는 ##/### 헤딩을 기준으로 콘텐츠를 청크로 나누어 한 번에 한 섹션씩 가져옵니다. 너무 작은 페이지나 섹션은 관련 없는 이웃 내용과 합쳐집니다. 하나의 주제를 작은 페이지 여러 개로 지나치게 나누면 답변 품질이 눈에 띄게 떨어집니다. 페이지 길이와 세분화를 참고하세요.
• 독립적인 섹션: 각 섹션은 "위에서 언급했듯이" 같은 정보에 의존하지 않고 그 자체로 완결됩니다. 에이전트는 페이지 전체가 아니라 청크나 섹션 하나만, 때로는 헤딩만 가져올 수 있습니다. 각 섹션을 독립적으로 작성하기를 참고하세요.
• 답변 우선 도입부: 각 페이지는 H1 바로 다음에 쉬운 말로 쓴 한 문장짜리 답변으로 시작합니다. AI 어시스턴트와 검색 화면은 이 한 줄만 인용으로 보여 주는 경우가 많으므로, 구체적인 도입부는 인용 비율과 답변 정확도를 모두 높입니다. 한 문장 답변으로 시작하기를 참고하세요.
• 상호 링크: 페이지는 선행 조건, 다음 단계, 관련 주제를 명시적으로 링크하므로 에이전트가 URL을 추측하지 않고 경로를 따라갈 수 있습니다. 서로 링크된 페이지는 주제 클러스터를 이루며, AI 검색은 이를 깊이 있는 콘텐츠의 신호로 읽고 독립된 페이지보다 훨씬 더 많이 인용합니다. 관련 페이지, 선행 조건, 다음 단계로 링크하기를 참고하세요.

콘텐츠와 예시#

• 이미지보다 텍스트: 지침은 이미지가 아니라 파싱하기 쉬운 텍스트로 작성합니다. 에이전트와 스크린 리더는 그림 자체가 아니라 이미지의 대체 텍스트와 파일 경로만 받습니다. 스크린샷은 독자가 페이지의 글을 통해 이미 아는 내용을 확인하는 데만 쓸 수 있으며, 스크린샷만으로 의미를 전달해서는 안 됩니다. 이미지를 참고하세요.
• 실제 예시: n8n Docs는 코드, 표현식, 구성 화면이 있는 기능에 실제 예시를 제공하려고 노력합니다. 에이전트는 예시를 그대로 복사하고 보이지 않는 내용은 추론할 수 없으므로, 일반적인 경우와 제대로 동작하지 않는 경우를 모두 다룹니다. 기능마다 실제 예시 보여 주기를 참고하세요.
• 탭 콘텐츠: 사람은 탭 하나만 보지만 에이전트는 모든 탭을 읽으므로 탭 콘텐츠는 적고 짧게 유지합니다. 탭 콘텐츠를 참고하세요.

스타일 가이드와의 관계#

이 페이지는 근거를 설명합니다. 기여 가이드는 기여 프로세스를 다루고, 스타일 가이드에는 따라야 할 구체적인 규칙이 있습니다. 페이지 길이, 독립적인 섹션, 내부 링크, 기능 제공 여부, 이미지, 탭 콘텐츠를 포함한 여러 규칙은 문서가 사람뿐 아니라 에이전트에게도 잘 동작하도록 하기 위해 존재합니다. 기여한다면 스타일 가이드를 직접 따르세요. 규칙 뒤에 있는 근거를 알고 싶거나 새로운 내용을 규칙으로 추가할 가치가 있는지 따져 볼 때 이 페이지로 돌아오세요.

아직 발전 중인 부분#

모든 지침에 확정된 답이 있는 것은 아닙니다. n8n Docs는 무엇이 문서를 에이전트 친화적으로 만드는지 지속적으로 테스트하고 연구하며, 이 기준을 충족하는 데 도움이 되는 새로운 시스템을 개발하고 있습니다. 에이전트 친화성은 문서화 실무에서 빠르게 변하는 분야이며, 이 페이지도 실무가 성숙함에 따라 바뀔 것입니다.

관련 리소스#

• n8n Docs 기여 가이드
• n8n Docs 스타일 가이드
• 용어 및 명칭