AI-DECLARATION.md

개요

AI를 활용한 코드 작성은 이제 거스를 수 없는 현실이 되었으며, 이는 우리에게 큰 편리함을 주기도 하지만 동시에 새로운 고민거리를 안겨주기도 합니다. 여기서 중요한 것은 코드 자체가 아니라 투명성과 명확성입니다. 적어도 이 명세는 이러한 전제를 바탕으로 합니다. 우리가 제안하는 바는 아주 단순합니다. 프로젝트 저장소에 으레 다른 파일들을 포함하듯이 구조화된 AI-DECLARATION.md 파일도 함께 추가하자는 것입니다. 이를 통해 AI를 어떻게 사용했는지 투명하고 명확하게 밝히고, 더 나아가 이러한 실천을 개발 생태계의 보편적인 문화로 정착시키고자 합니다.

이는 향후 LLM이나 기타 코드 생성 도구의 사용을 막으려는 것이 아닙니다. 오히려 그 반대로, 이를 올바르게 활용할 수 있도록 돕는 장치입니다. 코드의 어느 부분이 AI로 작성되었는지 투명하게 밝히면, AI 코드에 의구심을 갖는 사람이라도 해당 부분만 집중적으로 살펴보고 교차 검증할 수 있습니다. 또한, 코드 작성자 입장에서는 자신의 코드 작성 역량뿐만 아니라 기획력과 기타 소프트 스킬까지도 동시에, 그리고 명확하게 보여줄 수 있습니다.

명세

AI-DECLARATION.md 파일은 구조화된 데이터를 정의하기 위해 YAML 프런트매터를 사용하며, 그 아래 마크다운 본문에는 사람이 직접 읽고 맥락을 이해할 수 있도록 ## Notes(참고 사항) 섹션을 반드시 포함해야 합니다. 최소한 version (버전), level (단계) 프런트매터 필드와 ## Notes 섹션이 있어야 합니다.

필요하다면 개발 processes(과정)별 개별 단계를 명시할 수 있습니다. 이 때, 전역 level은 명시된 단계 중 가장 높은 단계로 지정되어야 합니다. 목록에 명시되지 않은 과정은 암묵적으로 none으로 간주됩니다. 또한 특정 components(파일 경로 또는 디렉터리)별로 단계를 명시하는 것도 가능합니다.

이 명세는 version, level, processes, components를 공식 규격으로 정의합니다.

단계 (level)

• none어떠한 시점에서도 AI 도구를 사용하지 않음.
• hintAI 자동 완성 또는 인라인 추천만 사용. 사람이 모든 코드를 작성하며, AI는 이따금 코드의 한 줄이나 블록을 완성함.
• assist사람이 주도함. 특정 작업(함수 구현, 코드 동작 설명, 테스트 초안 작성 등)에 대해 필요할 때마다 AI가 사용되지만, AI가 전반적인 작업을 이끌지는 않음.
• pair작업 전반에 걸쳐 사람과 AI가 적극적으로 협업함. 기여도는 대략 비슷함.
• copilot사람이 기획하고 검토하는 동안 AI가 코드를 구현함. 사람이 완성할 결과물을 정의하고 검증하지만, 코드 작성의 대부분은 AI가 수행함.
• auto최소한의 지시만으로 AI가 자율적으로 작동함. 사람이 큰 틀에서 방향을 잡거나 결과물을 승인할 수는 있지만, 코드를 직접 작성하거나 세밀하게 지시하지는 않음.

과정 (processes)

• design아키텍처, 시스템 설계 및 의사결정.
• implementation프로덕션 코드 작성.
• testing테스트 코드 작성, 테스트 계획 수립 및 품질 보증(QA).
• documentation문서, 주석, README 및 변경 로그 작성.
• review코드 리뷰 및 풀 리퀘스트(PR) 피드백.
• deploymentCI/CD 구성, 인프라 및 릴리스 스크립트 작성.

예시

아래에서 다양한 상황에 따른 예시를 확인할 수 있습니다.

---
version: "0.1.1"
level: none
---

## Notes

- 어떠한 AI 도구도 사용하지 않았습니다.

---
version: "0.1.1"
level: auto
---

## Notes

- Claude Code를 사용하여 애플리케이션 전체를 개발했습니다.

---
version: "0.1.1"
level: auto
processes:
  design: auto
  testing: copilot
---

## Notes

- AI가 아키텍처 결정과 테스트 코드 생성을 주도했습니다. 모든 결과물은 사람이 검토했습니다.

---
version: "0.1.1"
level: auto
components:
  src/helpers: auto
---

## Notes

- helpers 디렉터리 내의 코드는 전적으로 AI가 생성했습니다. 그 외의 모든 코드는 사람이 직접 작성했습니다.

배지

프로젝트의 README 파일에 배지를 추가하면 AI-DECLARATION 단계를 한눈에 보여줄 수 있습니다. 단, 배지는 편의를 위한 시각적 도구일 뿐이므로 명세를 올바르게 준수하려면 반드시 본 프로젝트에 AI-DECLARATION.md 파일을 포함해야 합니다.

• Copy
• Copy
• Copy
• Copy
• Copy
• Copy

자주 묻는 질문