DESIGN.md

이 파일은 설계 진입점(design entrypoint)입니다. 간결하게 유지하고 docs/design-docs/ 아래의 더 상세한 파일들로 라우팅하는 데 사용하십시오.

목적

단일 채팅, 스프린트, 또는 리뷰어의 기억을 넘어 지속되어야 할 내구적인 제품 및 시스템 설계 결정을 기록합니다.

설계 문서(design doc)는 단순한 코드 주석이나 PR 설명과 달리, 결정이 내려진 이유와 맥락을 장기적으로 보존하여 미래의 에이전트(agent)와 인간이 동일한 실수를 반복하지 않도록 돕습니다.

읽어야 할 때

• 현재 설계 철학이 필요할 때
• 새로운 패턴을 도입하려 할 때
• 어떤 설계 결정이 확정되었고 어떤 것이 아직 열려 있는지 알아야 할 때

규범적 설계 문서

• docs/design-docs/index.md: 수락됨, 제안됨, 폐기됨 상태의 문서 색인
• docs/design-docs/core-beliefs.md: 프로젝트 전반에 걸친 에이전트 우선(agent-first) 신념

설계 규칙

• 설계 문서는 작고 현재 상태를 유지한다.
• 결정 영역당 하나의 문서를 선호한다.
• 변경이 설계 문서에 의존할 때 계획과 명세에서 설계 문서를 연결한다.
• 설계 규칙이 운영적으로 중요해지면 자동화된 검사로 승격하거나 ARCHITECTURE.md를 업데이트한다.