Skip to content

README_ko.md

Latest commit

 

History

History
171 lines (121 loc) · 9.65 KB

README_ko.md

File metadata and controls

171 lines (121 loc) · 9.65 KB

AI-DECLARATION.md

AI-DECLARATION: copilot

개요

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)

이 레벨들은 코드 생성뿐만 아니라 코드 리뷰와 같은 관련 활동들까지 포괄하는 것을 목표로 합니다. 이들은 Human, AI, task와 같은 엔티티들과 더불어, act 및 prompt라는 동사들의 조합으로 정의됩니다.

  • none: AI의 개입 없이 사람이 단독으로 작업을 수행함.
  • hint: 사람이 작업을 수행하고, AI는 수동적으로 제안을 제시함.
  • assist: 사람이 지시하고, AI가 작업의 일부를 수행함.
  • pair: 사람이 지시하고, 사람과 AI가 동등하게 작업을 수행함. 사람은 내부 구조를 명확히 이해하고 있음.
  • copilot: 사람이 지시하고 AI가 전체 작업을 수행하며, 승인이나 명확한 지시를 위해 사람에게 질문함.
  • auto: 사람이 지시하고, AI가 자율적으로 작업을 수행하여 완료함.

과정 (processes)

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

스키마

아래의 YAML 스키마는 AI-DECLARATION.md 파일의 구조를 형식적으로 규정합니다. 선언 파일을 검증하거나 관련 도구를 개발할 때 이 스키마를 사용하세요.

type: object
required: [version, level]
definitions:
  level:
    type: string
    enum: [none, hint, assist, pair, copilot, auto]
properties:
  version:
    type: string
    pattern: "^[0-9]+\\.[0-9]+\\.[0-9]+$"
  level:
    $ref: "#/definitions/level"
  processes:
    type: object
    propertyNames:
      enum: [design, implementation, testing, documentation, review, deployment]
    additionalProperties:
      $ref: "#/definitions/level"
  components:
    type: object
    additionalProperties:
      $ref: "#/definitions/level"
additionalProperties: false

예시

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

기본

가장 단순한 형태의 AI-DECLARATION.md에는 version, level, 그리고 ## Notes 섹션이 있어야 합니다.

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

이 파일은 [AI-DECLARATION.md](https://ai-declaration.md/ko/0.1.1) 명세를 바탕으로 작성되었습니다.

## Notes

- 어떠한 AI 도구도 사용하지 않았습니다.
---
version: "0.1.1"
level: auto
---

이 파일은 [AI-DECLARATION.md](https://ai-declaration.md/ko/0.1.1) 명세를 바탕으로 작성되었습니다.

## Notes

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

processes 사용

개발 단계별 AI 참여도를 더 세밀하게 선언하려면 processes를 사용하세요. 전역 level은 하위 단계 중 가장 높은 단계로 지정해야 합니다. 명시되지 않은 과정은 암묵적으로 none으로 간주됩니다.

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

이 파일은 [AI-DECLARATION.md](https://ai-declaration.md/ko/0.1.1) 명세를 바탕으로 작성되었습니다.

## Notes

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

components 사용

특정 파일이나 디렉터리에 대한 AI 참여도를 선언하려면 components를 사용하세요.

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

이 파일은 [AI-DECLARATION.md](https://ai-declaration.md/ko/0.1.1) 명세를 바탕으로 작성되었습니다.

## Notes

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

배지

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

  • AI-DECLARATION: none
  • AI-DECLARATION: hint
  • AI-DECLARATION: assist
  • AI-DECLARATION: pair
  • AI-DECLARATION: copilot
  • AI-DECLARATION: auto

자주 묻는 질문

선언 파일에 거짓말을 적으면 어떻게 되나요?

그렇게 한다면 이 선언이 존재하는 이유 자체가 무의미해지겠죠? 이 제안의 핵심은 우리 모두가 신뢰할 수 있는 일종의 사회적 계약을 맺는 것입니다. 프로젝트 저장소에 AI-DECLARATION.md가 있다면, 누구나 이를 믿고 의지할 수 있는 단일 진실의 원천(Single Source of Truth)으로 삼게 하자는 것이 목표입니다.

이 파일을 자동으로 생성하는 도구를 개발해도 될까요?

물론입니다. 얼마든지 만들어주세요! 저는 이 명세 파일을 자동으로 생성하는 도구뿐만 아니라 파싱 도구 등 관련 생태계가 널리 구축되기를 기대합니다. 언젠가는 저도 직접 도구를 개발하겠지만, 생태계 확장을 위한 여러분의 모든 기여는 언제나 큰 환영입니다.

번역 작업에 기여하고 싶은데 어떻게 하나요?

물론입니다! 언제든 부탁드립니다. 저장소를 포크한 뒤 README_ko.md처럼 README_<언어코드>.md 형식으로 파일을 추가해 주세요. 그런 다음 PR을 올려주시면 제가 이어서 처리하겠습니다.

명세의 내용을 수정하거나 추가 제안을 하고 싶습니다.

이 프로젝트가 오픈소스인 이유가 바로 그것입니다! 이 명세서는 개발자분들의 소중한 피드백과 PR을 통해 자연스럽게 진화해 나갈 것입니다. 언제든 편하게 오셔서 함께 논의해 봅시다.

README에 배지를 달았는데도 꼭 파일을 포함해야 하나요?

네, 진실의 원천으로서 AI-DECLARATION.md 파일 자체를 포함할 것을 권장합니다. README에 추가하는 배지는 단지 방문자에게 (A) 프로젝트 내에 명세 파일이 존재한다는 사실과 (B) 프로젝트의 AI 사용 단계를 한눈에 가볍게 보여주는 보조 수단일 뿐입니다.

로고에는 어떤 의미가 담겨 있나요?

䷼은 61번째 괘인 ‘중부(中孚)’를 나타냅니다 (유니코드: U+4DFC). 이는 주역의 64괘 중 하나로, 각 효는 음(끊어진 선) 또는 양(이어진 선)으로 이루어져 있습니다. (출처)