데이터 폴더와 파일 형식

데이터 폴더(Markdown 세계에서는 ‘Vault’라고도 함)는 TandemLoop이 모든 데이터를 저장하는 폴더입니다. 데이터 폴더는 일반 텍스트 파일, 즉 YAML 머리말이 있는 Markdown 파일로만 이루어져 있으며, 설정할 때 선택한 위치(로컬 또는 iCloud Drive)에 있습니다. 따라서 다른 도구와 AI 에이전트는 물론 사용자도 어떤 텍스트 편집기로든 읽을 수 있습니다.

폴더 구조

{데이터 폴더}/
  AGENTS.md                  ← AI 에이전트용 안내서
  _inbox/                    ← 빠르게 입력한 작업(GTD 수신함)
  bereiche/                  ← 영역(영역마다 하위 폴더 하나)
    {영역}/
      area_{slug}.md         ← 영역 메타데이터
      _projects/             ← 영역의 프로젝트
      _singles/              ← 영역에 바로 속한 단일 작업
      _folders/              ← 선택적 폴더
        {폴더}/
          fld_{slug}.md      ← 폴더 메타데이터
          _projects/
          _singles/
  _config/                   ← 구성(태그, 속성, 테마, 표시, 언어)
    tags.yaml
    attributes/              ← 사용자 속성(속성마다 파일 하나)
      {키}.yaml
    themes/                  ← 테마(테마마다 파일 하나)
      {키}.yaml
    agent.yaml               ← AI 에이전트의 마지막 실행(에이전트가 기록)
    language.yaml            ← 데이터 폴더의 언어
  _views/                    ← 저장된 뷰(하위 폴더에도 가능)
    vw_{slug}.yaml
  _proposals/                ← AI의 제안
    prop_{slug}.md
  _archive/                  ← 보관된 항목(직접 편집하지 마십시오)
  _conflicts/                ← 저장된 iCloud 충돌 사본
  _system/                   ← 스키마와 자동 생성된 참조 문서

_ 접두사가 붙은 디렉터리는 시스템 폴더이며 앱이 관리합니다.

항목 ID와 파일 이름 접두사

모든 항목은 Frontmatter의 id 필드에 UUID 기반의 고정 ID를 가지고 있습니다. 파일 이름은 ID와 무관하며 읽기 쉬운 슬러그를 따릅니다. 뷰, 뷰 폴더(vf_…), 제안만 ID에 슬러그를 포함합니다. 오래된 파일에는 아직 슬러그 ID가 있을 수 있습니다(예: area_arbeit).

데이터 계약

파일 형식은 세 가지 원칙을 따릅니다.

관대한 읽기: 필드가 없거나, 알 수 없는 상태 값이 있거나, 이전 버전의 오래된 파일이어도 앱은 파일을 읽습니다. 따라서 직접 편집했거나 AI 에이전트가 생성한 항목 때문에 앱 전체가 멈추는 일이 없습니다.

안정적인 쓰기: 파일을 업데이트할 때 앱은 기존 필드의 순서와 기존 정보를 유지합니다. 외부 편집기가 추가한 알 수 없는 필드도 그대로 남습니다. 미리 알림(remind_at)처럼 나중에 추가된 필드는 앱이 Frontmatter 끝에 붙입니다. 빈 필드는 null로 기록되며, remind_at, repeat: 등 일부 필드만 설정되지 않은 동안 아예 생략됩니다.

기계 판독 가능: 일반 텍스트 Markdown 파일이므로 AI 에이전트와 다른 도구가 데이터 폴더를 바로 읽을 수 있습니다. 이런 도구가 직접 할 수 있는 변경은 AI 에이전트와의 협업 장에서 설명합니다.

사용자 속성

사용자 속성(설정의 속성)은 작업, 프로젝트, 마일스톤에 추가 필드를 더합니다. 각 속성은 _config/attributes/에 있는 작은 YAML 파일이며, 파일 이름이 속성의 키입니다.

key: customer
name: 고객
type: select
applies_to:
  - task
  - project
options:
  - ACME
  - Contoso
description: 어느 고객을 위한 작업인지 나타냅니다.

값은 각 파일의 Frontmatter에서 attributes: 아래에 있습니다.

attributes:
  customer: ACME
  budget: 12000
  acceptance: '2026-11-30'

• 유형: text, number(숫자), date('YYYY-MM-DD'), boolean(예/아니요), select(옵션 중 하나), url(링크).
• 키는 소문자, 숫자, 밑줄로 이루어지며 status나 due_date 같은 기본 제공 필드와 같을 수 없습니다. 키는 나중에 변경할 수 없습니다.
• 빈 필드는 저장되지 않습니다. 속성을 삭제해도 값은 제거되지 않으며, 파일에 남아 인스펙터에 읽기 전용 행으로 표시됩니다.
• 뷰에서는 속성을 attributes.키 필드로 필터링, 정렬, 그룹화할 수 있습니다.

반복 작업

반복 규칙은 작업 Frontmatter의 repeat: 아래에 있습니다. 예를 들어 매주 월요일이라면 다음과 같습니다.

repeat:
  unit: week
  days: [mon]

unit은 day, weekday, week, month 또는 year이며, 선택적으로 every(간격), day 또는 nth + weekday(월간 규칙), from: completion(완료일 기준), 그리고 종료 조건으로 until 또는 count가 추가됩니다. series, occurrence, next 키는 앱이 직접 관리합니다. 에이전트를 위한 전체 참조는 _system/docs/data-model.md에 있습니다.

테마

각 테마는 _config/themes/ 아래의 YAML 파일이며, 확장자를 뺀 파일 이름이 테마의 키입니다(nordlicht.yaml → nordlicht). 테마에는 기본값과 다른 색상만 적습니다.

name: Nordlicht
description: 어두운 배경과 시원한 청록색.
appearance: system        # system, light 또는 dark
font_design: rounded      # default, rounded, serif 또는 monospaced
colors:
  primary:
    light: "#0F766E"
    dark: "#2DD4BF"
  danger: "#E5484D"       # 값 하나는 라이트와 다크 모두에 적용

색상은 따옴표로 묶은 16진수 값으로 쓰며, 불투명도를 포함하려면 #RRGGBBAA 형식을 사용합니다. 어떤 색상 키가 있는지, 어떤 키가 다른 키에서 파생되는지, 어떤 기본값이 적용되는지는 _system/docs/themes.md에 있습니다. AI 에이전트가 테마를 알맞게 디자인할 수 있도록 TandemLoop이 이 참조를 직접 관리합니다. 어떤 테마가 활성 상태인지는 각 기기가 따로 저장하며, 테마 파일 자체는 데이터 폴더와 함께 동기화됩니다.

관계 블록

수신함 작업을 제외한 모든 작업, 프로젝트, 마일스톤, 폴더 파일의 본문 끝에는 상위 연결을 상대 Markdown 링크로 저장하는 짧은 기계 판독용 섹션이 있습니다. 다음은 ‘Website-Relaunch’ 프로젝트에 속한 작업의 예입니다.

<!-- tandemloop:relations:start -->
[Bereich: Arbeit](../../../area_arbeit.md) · [Projekt: Website Relaunch](../prj_website-relaunch.md)
<!-- tandemloop:relations:end -->

이 블록은 앱이 자동으로 최신 상태로 유지하므로 직접 편집할 필요가 없습니다. AI 에이전트는 새 파일에서 이 블록을 생략하고, 항목을 옮길 때 이 블록을 제거합니다. 이 블록 덕분에 도구와 에이전트는 앱의 메모리 내 색인 없이도 계층 관계를 파악할 수 있습니다.

데이터 폴더의 언어

관계 블록의 레이블(Bereich: / Area: 등), 작업 기록의 머리말(## Du — 21.3.2026 / ## You — 2026-03-21), 제안의 섹션(## Diskussion / ## Discussion), AI 에이전트용 안내서(AGENTS.md, _system/docs/)처럼 TandemLoop이 직접 파일에 쓰는 몇 안 되는 텍스트는 데이터 폴더의 언어를 따릅니다. 이 언어는 _config/language.yaml에 저장됩니다.

language: en

새로 생성한 데이터 폴더는 영어이며, 이 파일이 없는 데이터 폴더(이전 버전)는 독일어로 유지됩니다. 데이터 폴더의 언어는 기기의 언어와 관계가 없으므로 모든 기기가 같은 파일을 씁니다. 읽을 때는 TandemLoop이 두 가지 형식을 모두 인식합니다.

여러 기기: iCloud Drive를 통한 동기화

TandemLoop에는 자체 서버가 없으며 스스로 네트워크로 데이터를 전송하지 않습니다. 데이터 폴더는 평범한 폴더이므로 iCloud Drive에 두면 여러 기기에서 사용할 수 있습니다. iCloud가 Mac, iPad, iPhone 간에 파일을 최신 상태로 유지하고, TandemLoop은 각 기기에서 같은 폴더를 읽으며 필요한 경우 없는 파일을 iCloud에서 내려받습니다.