Agent IDE 개발 지침을 Markdown(.md) 파일로 작성하는 방법
소프트웨어 개발을 진행할 때, 명확한 개발 지침을 문서화하는 것은 매우 중요합니다. 특히, 여러 개발자가 협업하는 프로젝트에서는 개발 원칙과 코드 스타일을 통일하기 위해 Markdown(.md) 파일을 활용하는 것이 일반적입니다. 이번 포스팅에서는 Agent IDE를 사용할 때 개발 지침을 효과적으로 작성하는 방법을 소개합니다.
1. Markdown(.md) 파일을 사용하는 이유
✅ 가볍고 간편한 문서 포맷
Markdown은 단순한 텍스트 기반 포맷으로, HTML처럼 복잡한 태그 없이도 쉽게 문서를 작성할 수 있습니다.
✅ 다양한 플랫폼에서 지원
GitHub, GitLab, Notion 등 협업 도구에서 널리 사용되며, IDE에서도 미리보기가 가능합니다.
✅ 버전 관리 용이
코드와 함께 저장하고 버전 관리(Git)를 할 수 있어, 문서의 변경 이력을 쉽게 추적할 수 있습니다.
2. 개발 지침을 Markdown으로 작성하는 기본 구조
Agent IDE에서 사용할 개발 지침 문서를 작성할 때는 아래와 같은 구조를 따르는 것이 좋습니다.
# 프로젝트 개발 지침
## 1. 코드 스타일
- 변수명은 `camelCase`를 사용합니다.
- 함수명은 동사로 시작하며, 명확한 역할을 표현합니다.
## 2. 디렉터리 구조📂 프로젝트 루트
┣ 📂 src # 소스 코드
┣ 📂 docs # 문서 파일
┣ 📂 tests # 테스트 코드
┗ README.md # 프로젝트 소개 문서
## 3. 커밋 메시지 규칙
- `[feat] 새로운 기능 추가`
- `[fix] 버그 수정`
- `[docs] 문서 수정`
## 4. 코딩 컨벤션
- 줄 끝에는 세미콜론(;)을 붙입니다.
- 들여쓰기는 공백 2칸을 사용합니다.위와 같은 형식을 사용하면 개발자들이 쉽게 문서를 이해하고, 일관된 코드 스타일을 유지할 수 있습니다.
3. Agent IDE에서 Markdown 파일을 작성하는 방법
📌 1) Markdown 지원 여부 확인
Agent IDE가 Markdown 미리보기 기능을 제공하는지 확인합니다. 대부분의 최신 IDE에서는 .md 파일을 열면 바로 미리보기를 지원합니다.
📌 2) Markdown 파일 생성하기
Agent IDE에서 새 파일을 생성한 후, 파일명을 development-guide.md와 같이 설정합니다.
📌 3) 기본 템플릿 추가
아래와 같이 기본 템플릿을 작성해 놓으면, 새로운 프로젝트를 시작할 때 편리하게 활용할 수 있습니다.
# 프로젝트 개발 가이드
## 📌 환경 설정
- Node.js 18 이상 버전 사용
- ESLint, Prettier 설정 필요
## 📌 코드 스타일
- 변수명은 `camelCase`
- 클래스명은 `PascalCase`📌 4) Git과 연동하여 문서 관리
Markdown 파일을 GitHub 또는 GitLab에 업로드하면, 다른 팀원들과 쉽게 공유하고 협업할 수 있습니다.
git add development-guide.md
git commit -m "[docs] 개발 지침 문서 추가"
git push origin main이처럼 Git을 활용하면 개발 문서를 효율적으로 관리할 수 있습니다.
4. 개발 지침 문서 작성 시 주의할 점
📌 1) 너무 방대한 문서를 작성하지 않기
→ 핵심 사항만 정리하여 가독성을 높이는 것이 중요합니다.
📌 2) 최신 내용으로 업데이트 유지
→ 프로젝트 진행 상황에 따라 개발 지침을 업데이트하세요.
📌 3) 예제 코드 포함하기
→ 코드 스타일을 쉽게 이해할 수 있도록 예제 코드를 추가하세요.
🔥 마무리
Markdown을 사용하여 Agent IDE 개발 지침을 정리하면, 협업이 더욱 원활해지고 코드 품질을 유지하는 데 큰 도움이 됩니다. 기본적인 문법과 작성 팁을 활용하여, 프로젝트에 맞는 개발 가이드를 만들어보세요!
💡 여러분은 개발 지침 문서를 어떻게 관리하고 계신가요? 댓글로 공유해 주세요! 😊
그럼 다음회 부터 본격적으로 Agentic IDE로 StoryBook을 사용해서 component를 작성해 보도록 하겠습니다.