Development Standards / 개발 표준과 코딩 규범
하나의 스킬, 하나의 워크플로우, 두 가지 언어 리소스.
리소스 쌍 개정: 2026-10-05.9. 이는 리소스 번들을 식별하며 프로젝트 승인 또는 검증 통과를 의미하지 않습니다.
Language Selection / 언어 선택
- 사용자의 명시적 선호도에서 지침 언어를 선택합니다. 그렇지 않으면 중국어 요청에는
zh-CN을, 영어 요청에는en을 사용합니다. 다른 언어의 경우 영어 리소스를 사용하고 사용자 언어로 응답합니다. UI 메타데이터 또는 소스 파일의 언어에서 언어를 추론하지 마십시오. - 대화의 경우 사용자가 요청한 언어를 따르고, 그렇지 않으면 현재 요청을 따릅니다. 각 문서에 대해 명시적으로 요청된 언어를 따르고, 그렇지 않으면 프로젝트의 기존 문서 규칙을 따르고, 그렇지 않으면 대화 언어를 따릅니다. 일치하는 템플릿을 사용하고 다른 언어의 경우 영어 템플릿을 조정합니다. 관련 없는 파일을 번역하거나 코드 식별자를 이름을 바꾸는 부작용을 만들지 마십시오.
- 작업 전에 아래 해당 기준선 중 하나만 읽고 작업과 관련된 참조만 읽습니다. 요청된 문서 언어는 지침 언어와 다를 수 있습니다. 그 이유만으로 두 가지 전체 리소스 세트를 로드하지 마십시오.
| 기준선 | 읽을 조건 |
|---|---|
| 中文规范 | 지침 언어가 중국어인 경우 |
| English Standards | 지침 언어가 영어이거나 영어 폴백을 사용하는 경우 |
Shared Invariants / 공통 제약
- 정식 개발의 경우 먼저 요구사항을 승인한 다음 현재 구현 범위에 대한 완전한 모듈/아키텍처 설계를 승인합니다. 새 프로젝트에는 명시적인 스택 확인도 필요합니다. 부분 승인은 식별된 범위만 포함하며 필요한 종속성도 승인되어야 하며 암시적으로 포함되지 않습니다. 적용 가능한 게이트를 통과하기 전에 구현하거나 스캐폴딩하지 마십시오. 진정하고 적용 가능한 승인을 재사용하고 절대 위조하지 마십시오.
- 아키텍처 설계 중에 복잡한 모듈에는 아키텍처 다이어그램이 필요하고 복잡한 워크플로우에는 순서도가 필요하며 설계와 함께 저장되고 모듈/인터페이스 설명과 일치해야 합니다. 필수 다이어그램이 누락되면 해당 범위가 불완전합니다. 다이어그램은 계약을 대체하거나 승인 단계를 추가하지 않습니다. 간단한 설계 및 읽기 전용/경량 작업에는 전체 프로젝트 다이어그램 백필이 필요하지 않습니다.
- 인터페이스 설계가 필요한 경우 동일한 범위의 요구사항 및 대표적인 화면에 대해 3개의 실질적으로 다른 브라우저에서 볼 수 있는 HTML 시각적 프로토타입을 제공하고 미적 감각, 레이아웃, 타이포그래피 및 시각적 계층 구조를 우선시합니다. 정적 HTML/CSS로 충분합니다. JavaScript 및 상호 작용 데모는 명시적으로 요청되지 않는 한 선택 사항입니다. 진입점과 실제 렌더링 검사 결과를 제공하고 공식 구현 전에 절충점과 사용자의 선택을 기록합니다. 격리된 설계 작업은 요구사항/스택/아키텍처 게이트를 우회하거나 라이브 서비스를 승인하지 않습니다. 유효하고 적용 가능한 선택을 재사용하고 읽기 전용 검토 및 기존 설계를 유지하는 수리는 강제로 재선택하지 않습니다.
- 코딩 시작 시 구현 범위가 데이터베이스를 사용하는지 확인합니다. 그렇다면 데이터베이스 관련 코드 전에 설계를 출력하고 저장합니다. 새 데이터베이스를 제안하거나 기존 설계를 검사하고 재사용/업데이트합니다. 기본값은
docs/database-design.md입니다. 데이터베이스가 없으면 데이터베이스 문서를 생성하지 마십시오. 이는 코딩 산출물이며 아키텍처 승인의 전제 조건이나 추가 승인 단계가 아닙니다. 적용 가능한 범위 변경 및 데이터 작업 안전 장치는 여전히 적용됩니다. 읽기 전용 작업은 편집을 승인하지 않습니다. - 버그 수정 및 리팩토링을 포함한 모든 완전한 프로젝트 코드 변경은 설정된 체계에 따라 영향을 받는 제품 버전을 증가시켜야 합니다. 전달 전에 실제 버전 소스 및 필요한 동기화된 항목을 업데이트하고 이전 값, 새 값 및 위치를 보고합니다. 각 파일 편집 또는 재시도가 아닌 하나의 완전한 변경으로 계산합니다. 순수 문서/읽기 전용 작업은 제품 증가를 트리거하지 않습니다. 명확하지 않은 체계나 권한 충돌은 먼저 명확히 해야 합니다. 버전 증가는 릴리스를 승인하거나 호환성 요구 사항을 면제하지 않습니다.
- 자격을 갖춘 저위험 지역화된 수리는 명확한 의도를 복원합니다. 자격을 갖춘 동작 보존 리팩토링은 관찰 가능한 동작, 오류 및 부작용을 유지합니다. 둘 다 승인된 범위 내에 있으며 새로운 기능, 계약/경계 변경 또는 고위험 효과가 없습니다. 목표, 증거, 범위 및 검증 계획을 명시하고 기록적인 제품 문서 백필이나 중복 승인을 강제하지 않습니다. 모호성을 명확히 하고 범위나 위험이 증가할 때 영향을 받는 작업을 에스컬레이션합니다.
- 클라이언트/서버 제품의 경우 서버 변경은 강제 업그레이드 없이 이전 제품 에이전트의 프로토콜, 인터페이스, 필드 의미 체계 및 핵심 워크플로우를 유지해야 합니다. 영향을 받는 상호 작용에는 사용자/프로젝트 호환성 범위 및 실제 이전 에이전트 증거가 필요합니다. 비호환성, 실패하거나 누락된 검증은 병합/릴리스를 차단하며 단지 경고가 아닙니다. 여기서 에이전트는 소프트웨어 클라이언트이지 LLM이 아닙니다.
- 사용자 범위, 저장소 규칙 및 더 높은 우선순위의 지침을 유지합니다. 읽기 전용 요청은 편집을 승인하지 않습니다. 승인은 관련 없는 커밋, 푸시, PR, 배포, 프로덕션 데이터 또는 외부 쓰기 권한을 부여하지 않습니다. 실제 증거와 확인되지 않은 작업을 보고합니다. 자체 검토는 독립적인 검토가 아닙니다.
Translation Maintenance / 번역 유지 관리
| 용어 | 의미 |
|---|---|
| Required / 필수 | 적용 가능한 의무, 제안이 아님 |
| Must not / 금지 | 금지된 작업 |
| Recommended / 권장 | 정당한 조정이 허용되며 우선 채택 |
| Approved / 승인됨 | 확인된 내용 및 범위의 진정한 승인 |
| Verified / 검증됨 | 관련 검사가 실제로 통과됨, 승인 또는 배포와 동일하지 않음 |
references/zh-CN 및 assets/zh-CN은 중국어 규칙/템플릿 소스입니다. 일치하는 en 파일은 번역이며 독립적인 정책이 아닙니다. 해당 파일, 링크, README 및 영향을 받는 동작 시나리오를 함께 업데이트합니다. 이 진입점, 두 README 및 리소스 헤더에서 리소스 쌍의 개정을 진행합니다. 일치하는 개정은 의미적 동등성을 증명하지 않습니다. 위의 용어, 작업 모드, 안전 제약 및 증거 표준을 동등하게 유지합니다. 언어 전환만으로는 승인이 무효화되거나 작업이 승인되지 않습니다. 불일치가 발견되면 보고하고 영향을 받는 중국어 소스만 참조하고 조용히 더 약한 번역을 선택하지 마십시오. 소스를 확인할 수 없는 경우 불확실성을 공개하고 영향을 받는 게이트가 통과되었다고 주장하지 마십시오. 더 높은 우선순위의 지침은 항상 우선합니다.