IBM Bob의 init 명령어와 커스텀 Docs Architect 모드를 사용하여 기능 개발, 코드 리뷰, 온보딩, 지속적인 유지보수 등 실제 개발 시나리오에서 기술 문서를 코드베이스와 동기화 상태로 유지하는 방법을 알아보세요.

소프트웨어 개발에서 문서는 종종 사후에 처리하는 일로 취급됩니다 — 코드가 "완료된" 후에 하는 일이죠. 하지만 실제로는 문서가 코드와 함께 지속적으로 발전해야 합니다. 이 튜토리얼에서는 IBM Bob을 사용한 실용적인 개발 워크플로우에서 AI 코드 문서화가 실제로 어떻게 작동하는지 보여드립니다.

이론에 집중하는 대신, Bob의 문서화 기능을 일상적인 개발 프로세스에 통합하는 방법을 살펴봅니다: 초기 프로젝트 설정부터 기능 개발, 코드 리뷰, 릴리스까지. /init 명령어를 사용하여 AI가 읽을 수 있는 컨텍스트를 구축하고, 개발의 각 단계에서 사람이 읽을 수 있는 문서를 생성하는 커스텀 Docs Architect 모드를 만들 것입니다.

달성하는 것

이 튜토리얼에서 다음을 배웁니다:

AI 코드 문서화를 개발 워크플로우의 일부로 설정하기

/init을 사용하여 AI가 읽을 수 있는 프로젝트 컨텍스트 만들고 유지하기

사용자 대상 문서를 생성하는 커스텀 Docs Architect 모드 구축하기

문서 업데이트를 기능 개발 사이클에 통합하기

코드 리뷰와 pull request를 통해 문서 유지하기

버전 컨트롤에서 코드 변경과 문서 동기화 상태 유지하기

사전 조건

이 튜토리얼을 완료하려면 다음이 필요합니다:

Bob IDE 설치됨.

문서화하고 싶은 Git 저장소. 로컬 프로젝트나 오픈 소스 저장소 모두 가능합니다.

AI 코드 문서화가 실제로 어떻게 작동하는가

전통적인 문서화 워크플로우는 코드 작성과 문서 작성을 분리합니다. 개발자들은 코드를 작성하고 나서 (아마도) 나중에 문서를 업데이트합니다. 이로 인해 문서가 뒤처지고, 부정확해지고, 결국 무시되는 격차가 생깁니다.

IBM Bob은 소프트웨어 개발 라이프사이클 전체를 지원하기 위해 만들어진 IDE입니다 — 그리고 이는 AI 코드 문서화를 포함합니다. Bob은 문서 생성을 코드 변경과 함께 발생할 수 있을 만큼 빠르게 만들어서, 문서가 뒤처지지 않고 최신 상태를 유지하게 합니다. 실제로 어떻게 작동하는지 살펴봅시다:

AI 문서화 워크플로우

AI가 코드베이스를 학습한다: /init 명령어가 저장소를 스캔하고 대형 언어 모델의 지식 베이스 역할을 하는 구조화된 요약인 AGENTS.md 파일을 생성한다

AI가 문서를 생성한다: Docs Architect 같은 커스텀 모드가 이 컨텍스트를 사용하여 사용자 대상 문서(README, 가이드, API 문서)를 생성한다

리뷰하고 개선한다: AI가 생성한 문서는 출발점이며, 검증하고 편집하고 코드와 함께 commit한다

AI가 동기화 상태를 유지한다: 코드 변경 후 /init을 다시 실행하면 AI의 이해가 업데이트되어 빠른 문서 업데이트가 가능해진다

이 워크플로우는 문서를 별도 작업으로 취급하는 대신 개발 프로세스에 통합합니다.

실제 시나리오

이 튜토리얼은 마주치게 될 실용적인 시나리오를 살펴봅니다:

새 프로젝트 시작: 처음부터 문서 설정하기

기능 추가: 개발하면서 문서 업데이트하기

코드 리뷰: pull request에서 문서 확인하기

온보딩: AI가 생성한 문서를 활용해 새 팀원 지원하기

유지보수: 코드베이스가 발전함에 따라 문서 최신 상태 유지하기

시나리오 1: 초기 프로젝트 문서화

최소한의 문서만 있는 저장소를 인수받았다. 새로운 팀원들이 코드베이스를 이해하는 데 어려움을 겪고 있고, 신속하게 포괄적인 문서를 만들어야 한다.

워크스페이스 설정

IBM Bob IDE에서 저장소를 열기.
Bob 채팅 인터페이스 열기: Option + Command + B (macOS) 또는 Ctrl + Alt + B (Windows)

/init으로 AI가 읽을 수 있는 컨텍스트 생성

첫 번째 단계는 Bob에게 프로젝트에 대한 지식을 제공하는 것입니다. Agent 모드로 전환하고 실행:

/init

Bob이 저장소를 스캔하고 생성합니다:

저장소 루트의 AGENTS.md (메인 프로젝트 컨텍스트)
.bob/rules-code/AGENTS-code.md (Agent 모드 전용 컨텍스트)
.bob/rules-plan/AGENTS-plan.md (Plan 모드 전용 컨텍스트)
.bob/rules-ask/AGENTS-ask.md (Ask 모드 전용 컨텍스트)

이 파일들에는 다음이 포함됩니다:

코드 구조 및 주요 디렉토리
기술 스택 및 의존성
build, test, lint 명령어
코드 패턴 및 규칙

왜 중요한가: 이 AGENTS.md 파일들은 Bob이 모든 대화에서 참조하는 지식 베이스 역할을 합니다. 매번 코드베이스 전체를 재분석하는 대신, Bob은 프로젝트에 대한 영구적인 컨텍스트를 가집니다.

생성된 컨텍스트 검토

AGENTS.md를 열고 Bob이 발견한 것을 검토:

cat AGENTS.md

프로젝트의 구조화된 요약이 보입니다. Bob이 중요한 세부사항(비즈니스 규칙, 배포 규칙, 팀 관행)을 놓쳤다면, AGENTS.md를 편집하여 추가하세요. 이 파일은 커스터마이즈하도록 설계되었습니다.

Docs Architect 모드 만들기

이제 사용자 대상 문서를 생성하는 커스텀 모드를 만듭니다. 이 모드는 AGENTS.md 컨텍스트를 사용하여 AI가 아닌 사람을 위한 문서를 만들 것입니다.

Bob 패널의 settings 아이콘을 클릭하여 설정 열기.
Modes 탭 선택.
+ 아이콘을 클릭하여 새 모드 생성.
다음 값 입력:

필드	값
Name	Docs Architect
Slug	docs-architect
Role Definition	You are a documentation architect and writer who creates user-facing documentation. You work alongside AGENTS.md files (created by /init) which provide AI-readable technical context. Your role is to create human-readable documentation that complements, not duplicates, the AGENTS.md content. You focus on user needs: getting started guides, conceptual overviews, tutorials, and onboarding materials. Include code snippets with clear explanations. Add JSDoc comments (JavaScript) or Javadoc (Java) and docstrings where helpful to improve code quality.
When to use	Use this mode for writing and maintaining user-facing documentation such as READMEs, onboarding guides, and API docs. Not for writing or modifying application code.
Available Tools	Read, Edit

Mode-specific Custom Instructions 필드에 다음을 복사하여 붙여넣기:

When documenting a project:
1. Review AGENTS.md files to understand project structure and technical details
2. Create user-facing documentation (READMEs, getting started guides, tutorials)
3. Avoid duplicating technical details from AGENTS.md (build commands, code patterns)
4. Focus on user workflows, conceptual overviews, and practical code examples
5. Include code blocks with clear explanations
6. Add docstrings and JSDoc comments to improve code quality

Generate:
- README.md explaining project purpose and navigation
- CONTRIBUTING.md with onboarding steps for new contributors
- Getting started guide with code snippets
- Conceptual documentation explaining architectural decisions

저장을 클릭.

Bob은 Docs Architect 모드 설정이 포함된 custom_modes.yaml 파일을 .bob에 만듭니다. 이 파일을 직접 편집하여 향후 변경 사항을 적용할 수 있습니다.

초기 문서 생성

Docs Architect 모드로 전환하고 프롬프트 입력:

I've run /init to establish project context. Please create comprehensive documentation for this project:

1. Review AGENTS.md to understand the project structure
2. Create a README.md with:
   - Project overview and purpose
   - Quick start guide with code examples
   - Project structure explanation
   - Links to additional documentation
3. Create CONTRIBUTING.md with:
   - Development setup instructions
   - How to run tests
   - How to submit a pull request
   - Code style guidelines
4. Identify gaps in the codebase that need better documentation (missing docstrings, unclear functions)

Focus on making the technical details from AGENTS.md accessible to new developers.

Bob이 문서 파일을 생성합니다. 정확성을 검토하고, 편집하고, commit:

git add AGENTS.md .bob/ README.md CONTRIBUTING.md
git commit -m "docs: initial project documentation with AI assistance"

결과: 수 시간이 아닌 수 분 만에 최소한의 문서에서 포괄적인 문서로 전환되었습니다.

시나리오 2: 새 기능 문서화

새 기능을 방금 구현했습니다. 코드는 작동하지만 README, 기여 가이드, API 문서는 여전히 프로젝트의 이전 상태를 설명하고 있습니다. 이것이 문서가 가장 흔히 뒤처지는 지점입니다 — 기능은 완성되었지만 문서가 따라오지 못했습니다.

Bob을 사용하여 이 격차를 좁히는 방법입니다.

Bob의 도움으로 기능 작성

개발하는 동안 Bob이 구현을 도울 수 있도록 Agent 모드로 전환합니다. Bob은 시나리오 1에서 실행한 /init으로부터 이미 프로젝트 컨텍스트를 가지고 있어, 코드 구조, 의존성, 규칙을 이해합니다 — 이는 처음부터 시작하는 것보다 제안을 훨씬 더 관련성 있게 만듭니다.

코드 완성, 리팩터링, 기존 코드베이스에 대한 질문을 위해 Bob을 활용하며 평소대로 기능을 작성합니다.

/init을 다시 실행하여 AI 컨텍스트 업데이트

기능이 구현되면 Bob의 컨텍스트는 오래되었습니다 — 새 코드가 존재하기 전에 생성되었기 때문입니다. 업데이트합니다:

/init

Bob이 저장소를 다시 스캔하고 변경된 것을 반영하도록 AGENTS.md를 업데이트합니다 — 새 모듈, 업데이트된 의존성, 감지된 새 코드 패턴.

업데이트가 변경 사항을 캡처했는지 확인:

git diff AGENTS.md .bob/

diff가 새 기능을 보여주면, Bob은 정확한 문서를 생성할 준비가 된 것입니다. 중요한 것이 누락되었다면, 계속하기 전에 AGENTS.md를 수동으로 편집하세요.

새 기능에 대한 문서 생성

이제 Docs Architect 모드로 전환합니다. AGENTS.md를 방금 업데이트했으므로, Bob은 새 기능의 정확한 그림을 가지고 있어 추측이 아닌 실제 구현을 반영하는 문서를 생성할 수 있습니다.

Bob에게 업데이트가 필요한 것을 프롬프트:

I've added a new feature to the project. Please update the documentation:

1. Add a section to README.md explaining:
   - What the feature does
   - How to configure and use it
   - A code snippet showing basic usage
2. Update CONTRIBUTING.md if the development workflow has changed
3. Create a dedicated docs page that covers:
   - How the feature works
   - Relevant API endpoints or interfaces
   - Code examples for common use cases
   - Code explanations for non-obvious logic
   - Troubleshooting tips

Include code blocks with clear explanations. Add docstrings to any functions that lack them.

생성된 문서의 정확성을 검토 — 코드 예제가 실제로 구현과 일치하는지 확인 — 그런 다음 모든 것을 함께 commit:

git add src/ AGENTS.md .bob/ README.md CONTRIBUTING.md docs/
git commit -m "feat: add [feature name] with documentation"

결과: 기능과 문서가 함께 개발되어 같은 pull request에 commit됩니다.

시나리오 3: 문서 확인을 포함한 코드 리뷰

팀원이 새 API 엔드포인트를 추가하는 pull request를 제출합니다. 문서가 업데이트되었는지 확인해야 합니다.

/init이 실행되었는지 확인

git diff main feature-branch -- AGENTS.md .bob/

AGENTS.md에 변경 사항이 없다면 개발자가 /init을 실행하지 않은 것입니다. 다음을 요청합니다:

AI 컨텍스트를 업데이트하기 위해 /init 실행
사용자 대상 문서를 업데이트하기 위해 Docs Architect 사용

누락된 문서 생성

PR을 리뷰하고 있다면, 직접 문서를 생성할 수 있습니다:

git checkout feature-branch

Bob에서 /init을 실행하고 Docs Architect 모드로 전환:

I'm reviewing a pull request that adds new API endpoints. Please update the documentation:

1. Review the new endpoints in src/api/
2. Update README.md with a brief mention of the new endpoints
3. Update docs/api.md with:
   - Endpoint descriptions
   - Request/response examples with code blocks
   - Authentication requirements
   - Error codes
4. Add JSDoc comments to the endpoint handlers if missing

Focus on making the API easy to understand for other developers.

문서 업데이트를 commit:

git add AGENTS.md .bob/ README.md docs/api.md src/api/
git commit -m "docs: add documentation for new API endpoints"
git push

결과: 문서가 코드 리뷰 프로세스의 일부이지, 사후 처리 사항이 아닙니다.

시나리오 5: 장기적인 문서 유지보수

프로젝트가 수 개월째 개발 중입니다. 코드가 상당히 변경되었고 문서가 벌어지기 시작했습니다.

문서 드리프트 감지

무엇이 변경되었는지 보기 위해 /init 실행:

/init

diff 검토:

git diff AGENTS.md .bob/

큰 변경은 상당한 코드 진화를 나타냅니다. 이것이 사용자 대상 문서가 업데이트되어야 한다는 신호입니다.

체계적으로 문서 업데이트

Docs Architect를 사용하여 문서 갱신:

I've run /init and noticed significant changes to the project structure. Please review and update the documentation:

1. Review AGENTS.md changes to understand what's different
2. Update README.md to reflect current project structure
3. Update CONTRIBUTING.md if development workflow has changed
4. Identify any new features that lack documentation
5. Remove documentation for deprecated features
6. Update code examples to match current API

Focus on accuracy—make sure documentation matches the current codebase.

유지보수 일정 수립

정기 워크플로우에 문서 업데이트 추가:

월간: /init 실행 및 변경 사항 검토
릴리스 전: 모든 문서 업데이트
주요 리팩터링 후: 영향받은 문서 재생성
코드 리뷰에서: /init이 실행되었는지, 문서가 업데이트되었는지 확인

CI에서 문서 위생을 강제하고 싶은 팀을 위해, AGENTS.md와 .bob/가 최신 상태인지 확인하는 pull request 검사를 추가합니다. 검사는 브랜치에 대해 /init을 실행하고, 출력이 commit된 것과 다를 경우 실패합니다 — 개발자가 PR을 열기 전에 AI 컨텍스트 업데이트를 잊었다는 신호입니다. 이를 베스트 프랙티스 섹션의 PR 템플릿 체크리스트와 결합하여 문서 업데이트를 리뷰 프로세스의 필수 부분으로 만드세요.

결과: 정기적인 유지보수를 통해 문서가 코드와 동기화 상태를 유지합니다.

AI 코드 문서화 워크플로우 베스트 프랙티스

/init을 개발 프로세스에 통합하기

/init을 워크플로우의 정기적인 부분으로 만드세요:

새 모듈이나 기능 추가 후 실행

주요 리팩터링 후 실행

pull request 생성 전에 실행

활성 프로젝트에 대해 월간 실행

AI 컨텍스트와 사용자 문서를 함께 commit하기

AGENTS.md 파일은 항상 사용자 대상 문서와 함께 commit하세요:

git add AGENTS.md .bob/ README.md docs/
git commit -m "docs: update for [feature/change]"

이는 버전 관리 시스템에서 두 레이어를 동기화 상태로 유지하고, Markdown 소스 파일에서 API 문서를 생성하는 Mintlify 같은 도구를 위해 저장소를 자기 문서화하게 만듭니다.

AI가 생성한 문서를 초안으로 취급하기

AI 기반 코드 문서화 도구는 시작점을 생성하지, 최종 결과물을 만들지 않습니다. 항상:

정확성 검토

코드 예제가 작동하는지 확인

기술적 세부 사항 검증

어조와 스타일 조정

AI가 놓칠 수 있는 컨텍스트 추가

정밀도를 위해 컨텍스트 멘션 사용하기

문서의 특정 부분을 업데이트할 때 @ 멘션 사용:

@src/auth @docs/authentication.md Update the authentication documentation to reflect the new OAuth flow

이는 Bob이 관련 코드와 문서에 집중하는 데 도움이 됩니다.

코드 리뷰에 문서 포함하기

pull request 템플릿에 문서 체크 추가:

## Documentation Checklist
- [ ] Ran `/init` to update AGENTS.md
- [ ] Updated README if user-facing changes
- [ ] Updated API docs if endpoints changed
- [ ] Added code examples for new features
- [ ] Verified all code snippets work

독스트링으로 코드 품질 유지하기

독스트링과 JSDoc 주석을 추가하기 위해 Bob 사용:

@src/api Review all functions in this directory and add JSDoc comments to any that lack them. Include parameter types, return types, and usage examples.

이는 코드 품질과 문서 모두를 향상시킵니다.

일반적인 시나리오 트러블슈팅

문서가 코드와 일치하지 않음

문제: 생성된 문서가 존재하지 않는 기능을 설명하거나 최근 변경 사항을 놓칩니다.

해결책:

AI 컨텍스트를 업데이트하기 위해 /init 실행

Bob이 감지한 것을 보기 위해 AGENTS.md 변경 사항 검토

Docs Architect로 영향받은 문서 재생성

코드 예제가 작동하는지 수동으로 확인

/init이 중요한 컨텍스트를 놓침

문제: AGENTS.md에 비즈니스 규칙이나 배포 규칙 같은 프로젝트 특정 세부 사항이 부족합니다.

해결책: /init이 감지할 수 없었던 컨텍스트를 추가하기 위해 AGENTS.md를 수동으로 편집합니다. 이 파일은 커스터마이즈하도록 설계되었습니다.

문서 업데이트가 너무 오래 걸림

문제: 대규모 프로젝트의 문서 재생성은 시간이 많이 걸립니다.

해결책: 특정 섹션을 업데이트하기 위해 컨텍스트 멘션 사용:

@docs/api.md @src/api/users.ts Update only the user API documentation to reflect the new endpoints

팀원들이 문서 업데이트를 잊음

문제: pull request에 문서 업데이트가 누락됩니다.

해결책:

PR 템플릿에 문서 체크 추가

/init이 실행되었는지 확인하는 CI 체크 설정

문서 리뷰를 코드 리뷰 프로세스의 일부로 만들기

AI가 잘못된 코드 예제를 생성함

문제: 문서의 코드 스니펫이 작동하지 않거나 더 이상 사용되지 않는 API를 사용합니다.

해결책:

생성된 코드 예제는 항상 테스트

현재 코드를 가리키기 위해 컨텍스트 멘션 사용: @src/api/current-implementation.ts

정확성을 강조하기 위해 Docs Architect 모드 지침 업데이트

다음 단계

IBM Bob을 사용하여 AI 코드 문서화가 실제로 어떻게 작동하는지 배웠습니다. 다음 방법을 보았습니다:

개발 워크플로우에 /init 통합하기

커스텀 모드를 사용하여 사용자 대상 문서 생성하기

기능 개발과 코드 리뷰를 통해 문서 유지하기

코드 변경과 문서를 동기화 상태로 유지하기

이 워크플로우를 프로젝트에 적용하기

/init으로 시작: 현재 프로젝트에서 실행

모드 만들기: 팀의 필요에 맞게 Docs Architect 커스터마이즈

개발하면서 문서화: 코드 변경과 함께 문서 업데이트

PR에서 리뷰: 문서를 코드 리뷰의 일부로 만들기

정기적으로 유지: 월간 /init 실행 예약

코드베이스와 문서를 동기화 상태로 유지하기

이 페이지에서