설명과 근거 읽기 — Noea Code 문서

구현 설명은 의도의 특정 내용을 출발점으로 코드의 동작을 이해하고 그 설명을 뒷받침하는 근거를 찾도록 돕습니다. 동작, 근거 자료, 아직 판단해야 할 질문에 집중하세요.

단락 설명과 부분 설명 열기

문서의 텍스트를 클릭하면 편집할 수 있습니다. 단락 안에서 텍스트 바깥의 빈 공간을 클릭하면 L1으로 표시되는 단락 수준 설명이 열립니다.

일부 설명은 단어나 구절에 해당합니다. 단락에 포인터를 올리면 짧은 밑줄이 나타나며, 클릭하면 L2로 표시되는 부분 설명을 읽을 수 있습니다.

목록, 표, 코드 블록에도 설명이 있을 수 있습니다. 목록은 전체를 함께 조사하며, 제목은 별도로 조사하지 않습니다.

여러 단락의 여백 메모를 동시에 열어 둘 수 있습니다. 각 단락에는 단락 설명 또는 부분 설명 하나가 한 번에 표시됩니다. 창이 좁으면 메모가 단락 아래에 나타날 수 있습니다.

세 가지 섹션 읽기

섹션	답하는 질문	살펴볼 내용
구현	구현은 이 의도를 어떻게 충족하는가?	동작, 단계, 예외 상황, 구현 선택.
근거	무엇이 설명을 뒷받침하는가?	코드 참조, 테스트, 명령 출력 등 직접 살펴볼 수 있는 자료.
주의 사항	추가 판단이 필요한 것은 무엇인가?	미충족 사항, 구현 선택, 위험, 제안.

구현은 기본으로 펼쳐져 있습니다. 필요할 때 근거를 펼치세요. 표시할 주의 사항이 없으면 해당 섹션은 숨겨집니다.

7일 연속 출석 보상이라면 날짜를 누적하는 방식을 설명하고, 관련 함수와 테스트를 인용하고, 시간대가 바뀌는 여행을 어떻게 처리하는지 짚을 수 있습니다. 실제 내용은 프로젝트 조사 결과에 따라 달라집니다.

근거 살펴보기

코드 참조를 누르면 시스템 기본 앱으로 파일이 열립니다. 이미지는 여백 메모에서 보거나 확대할 수 있습니다. 명령 출력이나 코드 차이 같은 자료의 레이블을 누르면 새 탭이 열립니다. 자료가 더 이상 없으면 Noea가 알려 줍니다.

각 참조가 자신의 질문에 답하는지, 테스트가 어떤 조건을 다루는지, 결과가 결론을 뒷받침하는지 확인하세요. 핵심 상황이 빠졌다면 해당 단락에 대해 질문하고 추가 조사나 검증을 요청하세요.

특히 다음 세 가지 근거를 구분하세요.

자료	확인에 도움이 되는 내용	확인할 수 없는 내용
구현 코드 또는 테스트 코드	사용한 로직과 테스트에 정의된 시나리오.	테스트가 존재한다고 실행되었거나 통과했다는 뜻은 아닙니다.
이전 실행 결과	당시 무엇을 실행했고 그때 어떤 결과가 나왔는지.	이후 코드가 바뀌면 해당 결과를 더 이상 적용할 수 없을 수 있습니다.
지금 실제로 수행한 검증	이번 실행의 환경과 범위에서 나온 결과.	검증한 시나리오가 통과했다고 검증하지 않은 경우까지 올바르다고 할 수는 없습니다.

설명과 조사는 일반적으로 코드와 기존 근거를 읽으며, 매번 테스트나 빌드, 앱을 다시 실행하지는 않습니다. 읽기만으로 판단에 필수적인 사실을 확인할 수 없을 때 필요에 따라 검증합니다. 실제로 실행한 내용을 기준으로 검증 범위를 판단하세요.

특정 테스트를 다시 실행하려면 채팅에서 에이전트에게 실행을 요청하고 범위와 결과를 보고하도록 한 뒤 관련 단락을 다시 조사하세요.

의도에 기록할 선택 결정하기

“현재 구현은 로컬 저장소를 사용한다”는 설명은 지금의 방식을 묘사할 뿐, 이후 버전도 같은 방식을 사용해야 한다는 요구사항이 아닙니다. 유지하고 싶은 요구사항은 의도 문서에 기록해야 합니다.

그 선택이 사용자 경험, 비용, 개인정보, 위험, 향후 결정에 영향을 주는지 생각해 보세요. 이해한 뒤에는 보통 두 가지로 판단할 수 있습니다.

현재 방식은 괜찮고 나중에 바꿀 여지도 남기고 싶다면, 제약으로 만들지 않고 그대로 사용합니다.
앞으로의 버전에서도 반드시 지켜야 한다면, 요구사항을 명시하고 그로 인해 생기는 제한을 검토합니다.

예를 들어 지금은 출석 기록을 로컬에 저장해도 괜찮을 수 있습니다. 오프라인 사용이 필수가 되면 “네트워크에 연결되지 않아도 출석할 수 있다”라고 작성하고 구현이 그 동작을 어떻게 지원하는지 조사하세요. 상세한 구현 설명을 복사하기보다 필요한 동작을 표현하는 편이 대개 유지 관리하기 쉽습니다.

주의 사항 이해하기

주의 사항은 격차, 구현 선택, 위험, 제안으로 분류됩니다. 여기서 격차는 요구사항 중 충족하지 못한 부분을 뜻하며, 현재의 설계 선택이나 더 논의할 주제와 구분됩니다.

단락 오른쪽의 주의 사항 표시를 누르면 관련 설명이 열립니다. 숫자는 개별 문제 수가 아니라 주의 사항을 포함한 설명 패널 수입니다. 격차가 있으면 더 눈에 띄는 색으로 표시됩니다.

영향을 이해한 뒤 코드를 수정할지, 검증을 추가할지, 의도를 바꿀지, 현재 동작을 유지할지 결정하세요. 모든 주의 사항을 요구사항으로 만들 필요는 없습니다. 표시가 없다는 것은 현재 설명에 주의 사항이 나열되어 있지 않다는 뜻일 뿐입니다.

동작 예시 살펴보기

일부 설명에는 동작을 보여 주는 작은 대화형 예시가 포함됩니다. 직접 조작하거나 초기화하거나 소스를 살펴볼 수 있습니다.

이 예시는 앱이나 네트워크에 접근할 수 없는 격리된 샌드박스에서 실행되며 조작 상태를 저장하지 않습니다. 규칙을 설명하는 용도이므로 실제 소프트웨어가 이를 따르는지는 여전히 코드와 검증 근거로 확인해야 합니다.

설명이 여전히 유효한지 확인하기

이전 텍스트는 편집 전 의도에 대한 설명이라는 뜻입니다. 오래되었을 수 있음은 조사 후 설명이 읽거나 인용한 파일이 바뀌었다는 뜻입니다. 둘 다 다시 조사해야 할 이유가 됩니다.

여백 메모는 읽기 전용입니다. 요구사항을 바꾸려면 의도를 편집하고, 설명을 확인하려면 조사 또는 다시 조사를 사용하세요. 설명을 최신 상태로 유지하기를 참고하세요.