설계 (canon)
설계는 나중 세션이 아무에게도 묻지 않고 이유(결정, canon/decisions/D-n.md)와 유지되어야 할 사항(규칙, canon/rules/<domain>/BR-n.md)을 읽을 수 있을 때 완료됩니다. 이 대화 안에만 존재하는 설계는 사라집니다.
1. 모드 선택
| 모드 | 읽을 파일 | 초점 |
|---|---|---|
architecture | references/mode-architecture.md, references/architecture-patterns.md | 계층, 경계, C4, 마이그레이션 |
api | references/mode-api.md, references/api-design.md | 엔드포인트/명령, 오류, 인증, 페이지네이션 |
database | references/mode-database.md, references/database-design.md | 스키마, 인덱스, 마이그레이션, 접근 패턴 |
system | references/mode-system.md, references/system-design.md | SLA, 실패 모드, 용량 |
module | references/mode-module.md | 책임, 깊이(삭제 테스트), 결합점, 의존성 분류 |
필요한 모드의 파일만 읽으십시오. 설계가 해당 주제를 다루는 경우 교차 참조(references/cross-cutting/: 권한 부여, 오류 처리, 멱등성, 세션 식별)를 참조하십시오.
2. 설계 전
canon context <path|domain|C-n>: 현재 전체 도메인, 규칙, 승인된 결정 및 진행 중인 변경 사항을 확인합니다. 설계는 활성 규칙이나 승인된 결정과 모순되어서는 안 됩니다. 모순이 필요한 경우 이를 명시하고 동일한 변경에서 수정하십시오.canon search <topic>: 동일한 질문에 대한 이전 결정 및 메모를 검색합니다. 확장하거나 대체(--supersedes D-n)하고, 조용히 재작성하지 마십시오.- 새로 발명하기 전에 1~3개의 성숙한 제품이나 라이브러리가 동일한 문제를 어떻게 해결하는지 살펴보십시오.
- 구조를 제안하기 전에 변경하려는 기존 코드(심볼, 호출자)를 읽으십시오.
3. 설계
- 옵션을 나열하기 전에 문제를 구성하십시오: 이 설계가 답해야 할 질문은 무엇이며, 제공해야 할 시나리오는 무엇입니까? 기존 설계를 평가할 때 결함 목록은 입력일 뿐 프레임이 아닙니다. 결함 목록에서만 구축된 계획은 패치일 뿐 설계가 아닙니다.
- 최소 두 가지 실제 옵션과 그 트레이드오프, 권장 사항을 제시하십시오. 실제 옵션은 서로 다른 설계를 의미하며, 동일한 설계를 조금 더 또는 덜 수행하는 것("3가지 수정" 대 "10가지 수정")은 하나의 옵션입니다. 옵션이 세 개 이상이거나 여러 차원이 있는 경우 → 메모리 기반의 장단점 목록 대신 차원별로 추론을 작성하십시오.
- 권장 사항을 제시하기 전에, 문제와 옵션은 보지만 권장 사항은 보지 않는 하위 에이전트가 한 번 도전하도록 하십시오. 질문: 문제 자체가 잘못 구성되었는지, 진정으로 다른 설계가 누락되었는지, 각 옵션이 어떤 시나리오에서 실패합니까? 제기된 사항을 처리한 후 권장하십시오. 인터페이스를 변경하지 않는 단일 모듈 내의 작은 설계에 대해서만 이 단계를 건너뛰고, 건너뛴 이유와 함께 명시하십시오.
- 라이브러리, 버전 또는 API를 제안하기 전에 현재 공식 문서를 확인하십시오.
- 논쟁보다 더 빨리 답을 얻을 수 있는 질문(이 상태 머신이나 데이터 모델이 사용에 견딜 수 있는지, 몇 가지 화면 레이아웃 중 어떤 것이 효과적인지)은 먼저 canon-prototype 스킬로 해결합니다. 설계는 프로토타입이 보여준 내용을 인용합니다.
- 모호한 목표를 먼저 정량화하십시오("빠른" → Y rps에서 p99 X ms 미만).
- 설계가 제공하는 모든 시나리오는 처리해야 할 비즈니스 수준의 실패(한도 초과, 결제 거부, 플로우 중간에 권한 취소, 업스트림 중단)와 이를 크고 복구 가능하게 실패하는 방법을 최소한 하나 명명합니다. "적용 가능한 실패 모드 없음"은 주장되어야 하지 가정되어서는 안 됩니다.
- 각 옵션의 복잡성을 해당 시나리오가 발생했을 때의 비용과 비교하고, 각 시나리오에 대해 한 가지 질문을 하십시오: 정상 운영이 이 시리즈오로 이어집니까? canon의 경우 여러 세션이 동시에 작업하고 배포하는 것은 정상적인 사용입니다. 테스트가 이를 어떻게 재현할 수 있는지는 결정하지 않습니다. 비정상적인 설정이나 조치가 필요한 상황(시스템 명령어를 래핑한 사용자, 아무도 사용하지 않는 기본이 아닌 백엔드, 단계 중간에 특정 프로세스 종료, 보안 경계를 넘지 않는 악의적인 입력)은 알려진 한계(결정의
后果또는 규칙에 한 줄)가 되며 새로운 메커니즘이 아닙니다. 데이터 손실, 보안 및 프로젝트 약속 위반(canon의 경우canon/product.md의 P1~P7)은 예외입니다. - 초안을 모드의 렌즈에 대해 스스로 검토하십시오. 병렬 검토 하위 에이전트(렌즈당 하나, 모드 파일 참조)는 선택 사항입니다. 각각은 제로 컨텍스트에서 시작하여 수만 개의 토큰을 소비하므로, 영향 범위가 큰 경우(모듈 간, 공개 API, 데이터 마이그레이션, 보안)에만 사용하십시오.
품질 게이트 (모두 통과하거나, 통과하지 못하는 것과 그 이유를 명시해야 함)
| 모드 | 게이트 |
|---|---|
architecture | 모든 비기능 요구사항에 측정 가능한 아키텍처 응답; 모든 긴장에 근거가 있는 결정; 고위험 완화 방안; 롤백이 포함된 마이그레이션 단계 |
api | 모든 작업에 오류 명시; 모든 작업에 인증 요구사항 명시; 보안 이슈 해결 또는 근거와 함께 수락; 페이지네이션 및 속도 제한 명시 |
database | 모든 외래 키에 인덱스; 모든 테이블이 접근 패턴으로 정당화; 모든 스키마 변경에 무중단 마이그레이션; 금액에 float 사용 금지; 타임스탬프에 시간대 포함 |
system | SLA 목표(처리량, p99, 가용성); 완화되지 않은 단일 장애점 없음; 모든 구성 요소에 실패 모드 및 성능 저하; 1×/10×/100× 용량 |
module | 의존성 순환 없음; 모듈당 하나의 명확한 책임; 모든 모듈이 삭제 테스트 통과; 단일 어댑터가 있는 결합점 없음; 블랙박스로 테스트할 수 있는 공개 표면; 의존성 주입 가능 |
횡단 관심사 (매번 평가; 명시된 이유 없이 건너뛰지 않음)
| 관심사 | 적용 시점 | 수행 작업 |
|---|---|---|
| 보안 | 사용자 입력, 인증, 저장소, 외부 호출 | 데이터 흐름 추적, 위협 및 완화 방안 목록 작성 |
| 동시성 | 공유 상태, 여러 세션 또는 프로세스 | 정상 사용 중 이를 깨뜨릴 수 있는 인터리빙과 원자성을 보장하는 요소 명명; 드문 경우는 데이터 손실이 없다면 알려진 한계 |
| 성능 | 지연 시간에 민감한 경로, 대량 데이터 | 예산 설정 및 설계가 이를 충족함을 입증 |
| 관찰 가능성 | 새 구성 요소 | 기록되는 내용, 실패를 감지하는 방법 |
| 데이터 프라이버시 | PII 또는 기타 사용자 데이터 | 민감도 분류; 저장 및 전송 중 암호화; 보존 기간 및 삭제; 읽거나 변경하는 사람에 대한 감사 추적 |
4. 설계 기록
- 결정: 각 실제 선택에 대해
canon decision new --title "..."→背景(사실, 데이터),方案(각 옵션에采用또는否决표시와 이유, 각각 최소 하나),决定,后果를 작성합니다. 중국어로 작성하십시오(canon/ 문서는 중국어입니다). 옵션 아래에 각 사실의 출처를 한 줄씩 인용하십시오:- 来源：<URL 또는 저장소 경로> "<정확한 인용문, 8자 이상>"— 먼저 외부 사례를 조사한 다음 인용하십시오. 새 결정에는 최소한 하나의 출처가 필요하며, 착륙 시 각각의 새 출처를 가져와 인용문이 실제로 존재하는지 확인하고 그렇지 않으면 거부합니다. 자체 평가 점수나 신뢰 수준을 추가하지 마십시오: 아무도 확인할 수 없습니다. - 규칙: 설계가 제품에 약속하는 모든 동작에 대해
canon rule new --domain <d> --title "...". 하나의 규칙 = 하나의 트리거와 하나의 결과;规则과例子를 경계의 양쪽에 있는 구체적인 입력으로 채우십시오. 이 변경으로 구축되지 않는 동작(코드는 계획의 이후 단계에서 제공됨)은 규칙의 머리말에status: planned를 받습니다.规则과例子가 필요하지만 테스트는 필요 없으며, 이를 구축하는 변경은rules:아래에 나열하고 활성화합니다. 계획된 규칙의例子에서 설계가 결정한 경계만 고정하십시오. 구현 과정에서 발견되는 에지 케이스는 이를 구축하는 단계에서 추가됩니다. - 변경 파일 (
canon/changes/C-n.md):为什么/要改什么, 결정과 규칙을 참조합니다. - 설계가 컨테이너(런타임 부분, 데이터가 있는 위치) 또는 주요 흐름을 변경하는 경우 동일한 변경에서
canon/architecture.md를 업데이트하십시오. 현재 시스템 상태를 설명하며, 각 부분은 결정 번호로 끝납니다. 방금 결정한 결정 번호와 대조하십시오: 대체되거나 수정된 결정은 다시 작성해야 할 줄을 의미합니다. - 평소와 같이 착륙하십시오 (
canon work land). 규칙 검토는 결정과 규칙을 전체 도메인 및 개요와 비교하여 읽고, 막히는 것을 수정합니다.
설계당 별도의 문서는 없습니다. 구현 전에 수정할 가치가 있는 인터페이스(타입, 명령 서명, 스키마)는 변경 파일이나 코드 자체에 들어갑니다.