문서 유지보수 에이전트

자동으로 오래된 문서, 끊긴 링크 및 더 이상 사용되지 않는 예제를 감지합니다. 주간 스캔 및 자동 PR로 문서를 최신 상태로 유지하세요.

문서는 자연스럽게 변합니다. API가 변경되고, 예제는 더 이상 사용되지 않으며, 링크가 끊어집니다. 문서를 코드와 동기화된 상태로 유지하는 것은 자동화에 완벽한 번거로운 작업입니다.

문서 유지보수 에이전트는 일정에 따라 실행되고 문서를 감시하며 사용자를 혼동시키기 전에 문제를 해결하는 PR을 엽니다.

에이전트가 수행하는 작업

매주 일정에 따라(또는 할당을 통해 온디맨드로) 문서 에이전트는:

오래된 문서 찾기 — 오래된 API, 더 이상 사용되지 않는 플래그 또는 제거된 함수에 대한 참조 감지
끊긴 링크 확인 — 내부 및 외부 링크를 크롤링; 404 플래그 지정
예제 검증 — 코드 조각을 실행하고 컴파일/실행되는지 확인
Changelog 업데이트 — 병합된 PR 제목을 초안 Changelog로 추출
PR 열기 — 결과를 검토용 명확한 섹션이 있는 하나의 PR로 통합

설정

필수 조건

활성 에이전트가 있는 AACWorkflow 작업 영역
문서 저장소(또는 주 저장소의 docs 폴더)
bash, Go 또는 Node.js가 설치된 에이전트 런타임

1단계: 문서 유지보수 에이전트 생성

Settings → Agents로 이동하여 New Agent 클릭
런타임과 공급자 선택
docs-audit 또는 doc-keeper로 이름 지정
이 시스템 프롬프트 추가:

Role: Documentation auditor
Task: Every week or on-demand:
1. Clone the repository
2. Find all .md and .mdx files
3. Check all links (internal with grep, external with curl)
4. Find code snippets and validate syntax
5. Look for TODOs, deprecated markers, or version mismatch
6. Summarize findings in a changelog-style report
7. Create a GitHub branch "docs/maintenance-<date>"
8. Open a PR with all findings grouped by category
9. Link the PR to workspace as "docs-audit"

Output format:
## Stale References
- api/v1/GetIssue() → moved to /v2/GetIssue
- Example in quickstart.md lines 45–50 uses old syntax

## Broken Links
- Internal: docs/guides/auth.mdx → "see [Setup Guide](/setup)" (guide removed)
- External: 3 links to archived.example.com (404)

## Code Examples
- JavaScript example in index.mdx fails to parse (syntax error line 12)

## Changelog
Merged PRs since last scan:
- feat: add workspace invites
- fix: pagination token bug
- docs: update API docs

2단계: 에이전트 예약

AACWorkflow에서 Settings → Automations로 이동하여 예약된 작업 생성:

Trigger: 매주(예: 월요일 오전 9시)
Task: docs-audit 에이전트에 할당
Template: docs-maintenance

또는 자신의 인프라에서 cron 작업 사용:

# 매주 월요일 오전 9시 문서 감시 실행
0 9 * * 1 curl -X POST https://aacworkflow.com/api/tasks \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"agent_id": "docs-audit", "title": "Weekly docs audit"}'

3단계: 저장소 액세스 구성

저장소에 .aacworkflow/config.yml 추가:

docs_audit:
  paths:
    - "docs/"
    - "README.md"
    - "CHANGELOG.md"
  exclude:
    - "docs/archived/"
    - "node_modules/"
  checks:
    - link-validation
    - code-snippet-syntax
    - version-references
    - deprecated-markers

예제 PR 출력

Title: docs: maintenance audit for 2025-06-22

Body:

## Stale References (3 items)
- Line 87 in docs/agent-setup.md: "Runtime v2" → should be "Runtime v3"
- docs/api/endpoints.md: Old Swagger URL → update to OpenAPI v3.1
- Quickstart: "Deploy to Heroku" section → remove (service EOL)

## Broken Links (7 items)
- docs/guides/docker.mdx: line 23 → /install/docker-compose (moved to /docker)
- External: https://old-api-docs.example.com → 404

## Code Examples (2 updated)
- Python snippet in examples/webhook.md uses old v1 client → fixed
- Go example missing error handling → added

## Changelog Fragment
### Merged since 2025-06-15
- feat(api): add workspace export endpoint
- fix: typo in API error messages
- docs: expand rate limiting guide

---
Review and merge to publish. Auto-close stale branches after merge.

팁 및 모범 사례

빠르게 병합합니다. 문서 PR은 마찰이 적어야 합니다. 한 시간 이내에 검토하고, 병합하고, 게시하세요. 에이전트는 차단 없이 매주 실행할 수 있습니다.

Changelog 자동화 — 병합된 PR 제목을 ## Unreleased 섹션으로 추출하여 릴리스 노트를 미리 준비하세요
예제 검증 — Docker 컨테이너를 사용하여 모든 것을 로컬에 설치하지 않고도 언어 전반에 걸쳐 코드 예제를 검증하세요
외부 링크 시간 초과 — 외부 링크 확인에 대해 5초 시간 초과를 설정하여 중단을 방지하세요
패턴 제외 — 보관된 문서를 감시 외부에 유지하세요(.aacworkflow/config.yml에 추가)
승인 게이트 — 문서 PR 자동 병합 전에 최소 하나의 인간 승인이 필요합니다