비밀을 조각으로 나누는 오프라인 복구 소프트웨어 개발하기

## 몇 년 뒤 어려운 순간의 사람을 위해 동작하는 소프트웨어로 만들기 복구 소프트웨어는 누군가가 어려운 순간에 의지하기 전까지 수년간 손대지 않은 채로 남을 수 있는 기반 시설로 취급하세요. 유지관리자가 없을 때 결함이 드러날 수 있으므로, 빠른 완료보다 오래 지속되는 정확성을 우선하세요. - 기존 시스템을 변경하기 전에 경계와 규약이 존재하는 이유까지 이해하세요. - 국지적으로 편리한 예외를 도입하지 말고 확립된 패턴과 표준을 따르세요. - 기술에 익숙하지 않거나, 감당하기 벅차거나, 슬픔을 겪는 사람도 이해할 수 있도록 지침, 메시지, 인터페이스를 설계하세요. - 할당된 편집을 마쳤는지만 확인하지 말고 실제 결과를 검증하세요. 세심함, 공감, 이식성, 장기 운용성은 선택적인 마무리가 아니라 공학적 요구 사항입니다. ## 기능을 바꾸거나 없애기 전에 연결된 부분 모두 추적하기 상수, 도우미, 타입, 목록 또는 구성 출처를 추가하기 전에 검색하세요. 병렬 복사본이 서로 달라지지 않도록 기준 정의를 찾고 거기에서 파생하세요. - 기능을 변경하거나 제거하기 전에 코드, 스타일, 번역, 타입, 테스트, 주석, 문서, 빌드 구성 전반의 모든 연결 요소를 추적하세요. - 더 이상 필요 없는 동작은 완전히 제거하세요. 주석 처리하거나, 스타일로 숨기거나, 조건문 뒤에 남겨 두지 마세요. - 변경 후 관련 식별자와 개념을 다시 검색하여 남은 참조를 우연이 아니라 의도적으로 찾으세요. - 최종 차이에서 무관한 편집, 중복 로직, 죽은 코드, 불완전한 정리를 확인하세요. 전체 종속성과 참조 그래프를 처리하기 전에는 기능이 제거된 것으로 보지 마세요. ## 암호 처리를 명령줄과 브라우저가 함께 쓰도록 하나로 모으기 암호화 작업과 기타 핵심 동작은 명령줄 경로와 브라우저 경로가 함께 사용하는 공유 구현에 두세요. 얇은 어댑터는 달라도 되지만, 보안에 민감한 로직, 상수, 형식, 검증 규칙은 하나의 기준 출처에서 관리해야 합니다. - 편집하기 전에 생성, 복구, 패키징, 사용자 인터페이스 동작, 배포를 어느 런타임이 담당하는지 정리하세요. - 재사용성이나 이식성이 높아지는 경우, 가벼운 오프라인 복구 경로에는 브라우저 네이티브 코드를 사용하고 생성에는 컴파일된 브라우저 모듈을 사용하세요. - 빌드 시점의 기능 플래그로 오프라인 버전과 네트워크 보조 버전을 만들어 오프라인 산출물에 사용하지 않는 네트워크 코드가 포함되지 않게 하세요. - 호스트 언어에서 동작을 중복 구현하지 말고 작고 명시적인 브리지를 통해 컴파일된 함수를 노출하세요. - 패키지 전반에서 런타임과 모듈 선택을 일관되게 유지하세요. 내장 리소스가 순환 종속성을 만들 수 있다면, 순환을 강제하지 말고 애플리케이션 초기화 시 생성된 모듈을 불러와 명시적인 인터페이스로 바이트를 주입하세요. ## 복구를 완전히 오프라인으로 끝내고 검증된 암호만 쓰기 독립형 복구 산출물은 설치 없이 로컬에서 열 수 있어야 하며 서버나 네트워크 연결 없이 복구를 완료해야 합니다. 배포되는 모든 패키지는 자체 완결성을 유지하고 원래 저장소에 의존하지 않아야 합니다. - 외부 비콘을 잠시 확인하는 시간 지정 해제 산출물이나 같은 서버에서 아카이브를 가져오는 자체 호스팅 페이지처럼 범위가 좁고 문서화된 변형에만 네트워크 접근을 허용하세요. - 선택적 서버 변형이 있어도 각 수신자용 독립형 산출물은 완전한 오프라인 상태를 유지하세요. - 필요한 임계값보다 적은 키 조각으로는 추가된 메타데이터를 통해서도 비밀에 관한 어떤 정보도 드러나지 않게 하세요. - 검증된 암호화, 임계값 비밀 공유, 시간 잠금 구성을 사용하고 사용자 정의 암호화 기본 요소를 절대 만들지 마세요. - 심층 방어를 위해 모든 시간 잠금 계층을 주 암호화 계층 안에 두세요. - 모든 암호화 변경에 테스트, 검토, 명확한 근거를 요구하세요. 복구 경로에 원격 측정, 분석, 원격 글꼴, 콘텐츠 전송 종속성 또는 기타 숨겨진 네트워크 요구 사항을 추가하지 마세요. ## 패키지 형식을 유지하고 복구에 필요한 것을 모두 내장하기 패키지 구성, 암호화된 페이로드 형식, 키 조각 인코딩, 복구 단계를 프로토콜의 일부로 취급하세요. 이를 변경하려면 마이그레이션 계획, 갱신된 테스트 데이터, 호환성 테스트, 문서화된 이유가 필요합니다. - 플랫폼, 브라우저, 언어가 달라도 복구 환경이 작동하게 하세요. - 외부 서비스나 일시적인 형식에 의존하지 말고 스크립트, 스타일, 템플릿 및 기타 필수 리소스를 내장하세요. - 각 수신자 패키지에 명확한 텍스트 지침과 인쇄 가능한 지침, 암호화된 아카이브 메타데이터, 개인화된 복구 페이지를 포함하세요. - 암호화된 매니페스트가 10 MB 이하라면 개인화된 페이지에 내장하여 별도 파일 없이 복구할 수 있게 하되, 내장을 비활성화하는 명시적 옵션을 따르세요. - 브라우저 기반 생성 경로에 별도의 재정의가 없다면 조건을 충족하는 매니페스트를 자동으로 내장하세요. - 패키지를 만들거나 복구하는 사람이 개발 도구 체인에 런타임으로 의존하지 않게 하세요. 키 조각을 배포한 뒤 철회할 수 있다고 약속하지 말고, 시스템이 영원히 작동한다고 보장하지도 마세요. 확실성을 과장하지 않으면서 내구성을 추구하세요. ## 실패하는 테스트를 먼저 쓰고 페이지 변경에는 브라우저 테스트 추가하기 먼저 실패하는 테스트를 작성하고 실패를 관찰한 다음 통과시키세요. 실패를 확인한 적이 없는 테스트는 의도한 동작을 실제로 검사하지 않을 수 있습니다. - 브라우저 복구 또는 생성 페이지에 영향을 주는 모든 변경에 브라우저 수준 테스트를 추가하세요. - 핵심 로직, 아카이브 처리, 구성, 명령 동작에는 범위를 좁힌 단위 테스트와 통합 테스트를 사용하세요. - HTML 구조, 브라우저 코드, 레이아웃이나 가시성에 영향을 주는 스타일, 컴파일된 브라우저 바인딩을 변경할 때는 브라우저 종단 간 테스트를 실행하세요. - 번역만 수정하거나, 문서 또는 문구를 바꾸거나, 브라우저 동작에 영향을 줄 수 없는 백엔드만 변경한 경우에는 느린 브라우저 테스트를 요구하지 마세요. - 완료를 보고하기 전에 관련 테스트를 직접 실행하고 검증을 다른 사람에게 맡기지 마세요. 변경 후에는 관련 용어를 검색하고, 영향을 받은 산출물을 다시 빌드하고, 적절한 테스트를 실행한 뒤 결과를 확인하세요. ## 임시 도구 대신 저장소가 정한 빌드·테스트 명령 사용하기 프런트엔드 컴파일부터 브라우저 모듈을 거쳐 최종 명령줄 바이너리에 이르는 전체 빌드 파이프라인을 이해하세요. 생성된 스크립트와 컴파일된 모듈이 이후 단계에 내장될 수 있으므로 명령 순서도 정확성의 일부입니다. - 저장소의 표준 빌드, 테스트, lint, 정적 사이트, 개발 서버 명령을 사용하세요. - 컴파일이나 내장 전에 생성된 리소스가 있어야 한다면 언어의 테스트 실행기를 직접 호출하지 말고 프로젝트 테스트 래퍼를 사용하세요. - 단일 테스트를 위한 더 좁은 문서화된 명령은 해당 전제 조건이 이미 생성된 경우에만 실행하세요. - 네트워크 의존 테스트 모음은 해당 통합이 필요한 변경에만 사용하세요. - 종속성이나 빌드 도구를 사용할 수 없다면 임시 패키지 실행기로 대체하지 말고 저장소가 지정한 재현 가능한 개발 환경으로 들어가세요. 내장된 소스에서 정적 산출물을 빌드하고, 릴리스 설계에 명시적으로 포함되지 않은 비공개 복구 산출물은 공개 사이트에 배포하지 마세요. ## 긴장한 사람을 위해 차분하고 알기 쉬운 문장 쓰기 중요하고 스트레스가 큰 작업을 마주한 사람을 위해 모든 단어를 골랐다는 느낌이 들도록 사용자 대상 문구를 작성하세요. 친절함은 연출된 안심이 아니라 명확성, 호흡, 미리 내다본 배려에서 나와야 합니다. - 독자가 구현을 해석하지 않고 다음 행동을 알 수 있도록 기술적 표현보다 직접적이고 인간적인 언어를 우선하세요. - 명확한 능동문을 쓸 수 있다면 수동적인 지시를 피하고 사람에게 직접 말하세요. - 대상 독자에 맞는 용어를 일관되게 사용하세요. 외부 대상 문구에서는 “신뢰하는 사람들”과 “조각”을 우선하고, 수신자에게 보내는 지침에서는 “친구” 같은 관계 용어를 사용할 수 있습니다. - 느낌표, 군더더기 단어, 과장된 주장, 기계적인 표현, 억지로 만든 열정을 피하세요. - 이중 하이픈이나 앞뒤 공백이 없는 대시 대신 양쪽에 공백을 둔 em 대시를 사용하세요. - 상태 메시지는 간결하면서도 인간적으로 유지하고, 성공을 침묵시키지 말고 차분하게 전하세요. 절제된 대비를 갖춘 부드럽고 따뜻하며 비기업적인 시각 언어를 선호하세요. 색상 값은 중앙에서 관리하고, 순수한 검정, 선명한 빨강, 기업용 파랑을 피하며, 의도적인 시각 예외는 분리하여 문서화하세요. ## 문서를 고치고 변경 이력은 사용자가 느끼는 변화 중심으로 쓰기 동작이 변경되면 관련 문서, 기여자 지침, 운영 지침을 같은 변경에서 갱신하세요. 아키텍처 설명에는 런타임 경계, 생성된 리소스, 네트워크 예외, 결과를 재현하는 데 필요한 명령을 설명해야 합니다. - 구성 및 빌드 지침을 구현과 동기화하세요. - 안정적인 형식이 변경되면 테스트 데이터와 마이그레이션 지침을 갱신하세요. - 변경 이력 항목은 소프트웨어를 사용하는 사람에게 무엇이 달라졌는지를 중심으로 작성하세요. - 사용자에게 보이는 결과를 먼저 제시하고 이해에 필요한 구현 배경만 포함하세요. - 관찰 가능한 동작을 바꾸지 않는 내부 리팩터링과 코드 재구성은 제외하세요. 새 항목을 작성하기 전에 주변 항목을 읽어 말투와 세부 수준을 일관되게 유지하세요. ## 외부 서비스 제출은 기여자 본인이 검토하고 올리게 하기 외부 이슈 추적기나 코드 호스팅 서비스에 쓰는 작업을 하기 전에 프로젝트의 기여 정책을 읽으세요. 해당 정책이 인간의 책임을 요구한다면 게시 전에 멈추고 기여자가 코드와 문구의 모든 줄에 책임을 진다고 설명하세요. - 제안된 차이, commit 메시지 또는 제출 설명을 인간이 검토할 수 있도록 보여 주세요. - 기여자에게 자료를 자신의 말로 편집하고, 확인 항목을 정직하게 작성하며, commit, push, 제출을 직접 수행하도록 요청하세요. - 제출 전에 생성된 바닥글, 공동 작성자 줄, 군더더기 내용, 자동 생성 귀속 표시를 제거하세요. - 책임 요구 사항을 설명한 뒤에도 기여자가 명시적으로 고집하지 않는 한 외부 쓰기를 수행하지 마세요. - 그래도 고집한다면 메시지를 간결하고 직접적으로 유지하고, 자동 생성 귀속 표시를 추가하지 않으며, 인간 검토 요구 사항을 한 번만 다시 알리세요. 로컬 편집 지원과 읽기 전용 검사는 이러한 외부 쓰기 제한을 적용하지 않습니다. 릴리스 자동화는 게시 전에 빌드, 테스트, lint, 브라우저 검사, 교차 플랫폼 패키징, 체크섬, 대표 산출물 생성을 계속 실행해야 합니다.