중요한 의도 작성하기

의도 문서는 소프트웨어가 충족해야 할 동작과 제약을 기록합니다. 결정한 내용을 작성하고 구현과 근거를 통해 배우면서 다듬어 나가세요. 문서를 읽기 쉽게 유지하면서 에이전트가 구현할 여지도 남길 수 있습니다.

유지할 가치가 있는 요구사항 고르기

의도에는 여러 종류의 요구사항을 담을 수 있습니다.

유형	예시
제품 규칙	사용자가 7일 연속 출석하면 보상을 지급한다.
아키텍처 제약	모든 결제 요청은 서버에서 검증해야 한다.
알고리즘 요구사항	같은 입력과 시드는 같은 정렬 순서를 만들어야 한다.
상호작용 요구사항	저장에 실패하면 사용자 입력을 보존하고 다시 시도할 수 있어야 한다.

동작이 시작되는 조건과 관찰 가능한 결과를 설명하세요. “내보내기는 안정적이어야 한다”는 확인하기 어렵습니다. “내보내기에 실패하면 현재 필터를 유지하고 다시 시도할 수 있어야 한다”는 더 명확한 평가 기준을 제공합니다.

앞으로의 변경에서도 지켜야 할 만큼 중요한 구현 선택이라면 의도에 기록하세요. 아직 결정하지 않은 세부 사항은 구현 단계의 선택으로 남겨도 됩니다.

의도는 소프트웨어가 계속해야 할 동작을 설명합니다. 작업을 마치면 지우는 체크리스트가 아닙니다. 기능을 완성한 뒤에도 요구사항을 유지하고, 동작을 바꾸기로 결정하면 관련 문구를 수정하세요.

채팅에는 이번 작업을 위한 지시도 들어갑니다. 다음처럼 구분해 보세요.

내용	기록할 곳
7일 연속 출석하면 보상을 한 번 지급한다.	의도: 지속적으로 적용할 보상 조건.
보상 지급에 실패하면 중복 지급 없이 재시도를 허용한다.	의도: 지속적으로 적용할 실패 처리 방식.
이번에는 보상 로직을 바꾸기 전에 기존 코드를 조사한다.	현재 채팅: 이번 작업에 대한 지시.
먼저 프로토타입을 완성하고 시각 디자인은 다음에 논의한다.	현재 채팅: 현 단계의 작업 계획.

그 문장이 무엇을 제약하는지 생각해 보세요. “내보내기 전에 매번 데이터를 검증한다”는 소프트웨어의 실행 순서를 정하므로 의도에 속합니다. “이번에는 내보내기 모듈부터 조사한다”는 현재 작업의 순서를 정합니다.

어떤 지시가 지속적인 요구사항이고 어떤 지시가 이번 작업에만 적용되는지 에이전트에게 알려 주세요. 중요한 작업별 지시는 필요할 때 다시 전달하세요. 새 채팅이 이를 이어받는다고 가정하지 마세요.

사이드바의 새로운 의도를 클릭하고 이름을 입력하세요. Noea는 의도 폴더의 루트에 1단계 제목이 있는 .noea.md 파일을 만듭니다.

문서는 Markdown을 사용하며, 같은 화면에서 읽고 편집합니다. 텍스트를 클릭해 수정하고 제목, 목록, 표, 코드 블록으로 구성하세요.

예를 들면 다음과 같습니다.

# 매일 출석

사용자는 하루에 한 번 출석할 수 있다.

## 보상

사용자가 7일 연속 출석하면 보상을 지급한다. 같은 연속 출석 기간에는 보상을 한 번만 지급한다.

제목으로 섹션을 나누고 서로 다른 요구사항은 단락으로 구분하세요. 조사는 목록 전체를 하나의 내용으로 다룹니다. 각각 조사하고 논의하고 싶은 주제는 별도의 단락이나 섹션으로 나누세요.

규칙이 아직 명확하지 않다면 에이전트에게 변경을 제안하도록 요청하기 전에 먼저 논의하세요.

출석 보상 중복 지급을 막고 싶습니다. 여기서 “중복”의 의미를 정리해 주시고, 제가 확인하기 전에는 의도 변경을 제안하지 마세요.

결정이 내려지면 에이전트에게 제안으로 정리해 달라고 요청하세요. 문구를 검토하고 필요하면 새 텍스트를 수정한 뒤 수락합니다. 채팅에서 말한 내용은 실제 문서에 기록되어야 의도의 일부가 됩니다.

결과 문구는 자신이 이해하는 개념과 언어를 사용해야 합니다. 낯선 용어나 추가된 요구사항은 유지하기 전에 질문하세요. 좋은 문구라면 요구사항을 직접 설명할 수 있고, 다른 동작을 원할 때 어느 문장을 바꿀지 찾을 수 있습니다.

제안과 추천 카드는 의도 변경 논의와 검토를 참고하세요.

언어가 mermaid인 코드 블록은 다이어그램으로 표시할 수 있습니다. 상태 전이, 작업 흐름, 모듈 간 관계를 설명할 때 사용하세요.

오른쪽 위 컨트롤로 다이어그램과 소스를 전환할 수 있습니다. 편집하려면 소스로 전환하세요. 문법이 잘못되었거나 지원하지 않는 다이어그램 유형이면 Noea가 소스와 이유를 표시하며, 문서의 나머지 부분은 계속 읽을 수 있습니다.

macOS에서는 ⌘S, Windows / Linux에서는 Ctrl+S 또는 파일 → 저장으로 직접 저장합니다. 제목 옆의 점은 저장하지 않은 변경 사항을 나타냅니다. 탭을 바꿔도 유지되지만, 문서나 프로젝트를 닫거나 앱을 종료하면 저장 여부를 묻습니다.

저장하면 Markdown 서식이 정규화됩니다. 외부 편집기로 파일을 관리해도 됩니다. Noea에서 편집하는 동안 디스크의 파일이 바뀌면, 앱은 바로 덮어쓰는 대신 다시 불러오기나 다른 이름으로 저장하기를 제공합니다.

텍스트를 추가하거나 대체하거나 삭제하면 요구사항에 서로 다른 영향을 줍니다.

“보상은 배지여야 한다”를 삭제해도 기존 배지 구현이 반드시 잘못되는 것은 아닙니다. 남은 의도를 여전히 충족할 수 있습니다. 보상을 완전히 없애려면 형태에 대한 요구사항만 지우지 말고, 보상을 더 이상 지급하지 않아야 한다고 명시하세요.

편집 전에 어떤 동작이 바뀌고 어떤 요구사항이 유지되어야 하는지 에이전트에게 물어보세요. 답변은 논의의 출발점으로 삼고, 실제 구현과 근거를 확인하세요.

저장 후 이전 설명에는 이전 텍스트가 표시됩니다. 새로운 요구사항에 코드 변경이 필요하면 구현한 뒤 조사하세요. 기존 동작만 확인하려면 바로 조사해도 됩니다.