Purple-Horizons/tick-md

TICK.md

Git 기반 마크다운을 통한 멀티 에이전트 작업 조정

구조화된 TICK.md 파일을 사용하여 인간과 AI 에이전트 간의 작업을 조정하세요. Git 위에 구축되었으며, 자연어 상호작용에 최적화되어 있고, 멀티 에이전트 워크플로우에 최적화되어 있습니다.

✨ 기능

• 🤖 AI 네이티브: 원활한 봇 통합을 위한 MCP 서버
• 📝 사람이 읽기 쉬움: YAML 프론트매터가 포함된 일반 마크다운
• 🔄 Git 기반: 전체 버전 관리 및 자동 감사 추적
• 🎯 의존성 추적: 자동 작업 차단 해제
• 🔒 파일 잠금: 동시 편집 충돌 방지
• 🔍 고급 필터링: 상태, 우선순위, 태그별 작업 검색
• 📊 시각화: 의존성 그래프 (ASCII 및 Mermaid)
• 👀 실시간 모니터링: 실시간 업데이트를 위한 감시 모드
• 🌐 로컬 우선: 클라우드 불필요, 오프라인 작동

🚀 빠른 시작

CLI 설치

npm install -g tick-md

프로젝트 초기화

cd your-project
tick init
tick status

작업 생성 및 할당

tick add "Build authentication" --priority high --tags backend
tick claim TASK-001 @yourname
tick done TASK-001 @yourname

🤖 AI 에이전트용

MCP 서버 설치

npm install -g tick-mcp-server

MCP 설정에 추가 (예: ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "tick": {
      "command": "tick-mcp",
      "args": [],
      "env": {}
    }
  }
}

MCP 도구 사용

MCP 서버는 모든 CLI 명령을 도구로 노출합니다:

• tick_init - 프로젝트 초기화
• tick_add - 작업 생성
• tick_claim - 에이전트를 위한 작업 할당
• tick_done - 작업 완료 표시
• tick_status - 프로젝트 개요 조회
• tick_list - 작업 쿼리 및 필터링
• tick_comment - 진행 상황 메모 추가

🎯 주요 개념

TICK.md 파일 구조

---
meta:
  project_id: my-project
  id_prefix: TASK
  next_id: 4
  updated: 2026-02-07T15:30:00-05:00
---

### TASK-001 · Build user authentication

```yaml
id: TASK-001
status: in_progress
priority: high
claimed_by: @claude-code
assigned_to: @claude-code
created_by: @gianni
created_at: 2026-02-07T10:00:00-05:00
updated_at: 2026-02-07T15:30:00-05:00
tags: [backend, auth]
depends_on: []
blocks: [TASK-002, TASK-003]
history:
  - ts: 2026-02-07T10:00:00  who: @gianni       action: created
  - ts: 2026-02-07T15:30:00  who: @claude-code  action: claimed

JWT 기반 인증을 리프레시 토큰과 함께 구축

### 자동 Git 커밋

기본적으로 모든 변경 사항은 Git 커밋을 생성합니다:
```bash
[tick] TASK-001 claimed by @claude-code
[tick] TASK-001 completed by @claude-code
[tick] TASK-003: created

플래그로 제어:

• --commit - 강제 커밋
• --no-commit - 커밋 건너뛰기
• 또는 .tick/config.yml에서 설정

작업 상태

• backlog - 시작할 준비가 되지 않음
• todo - 할당 가능
• in_progress - 작업 중
• review - 검토 대기 중
• blocked - 의존성 대기
• done - 완료

파일 잠금

CLI는 .tick.lock을 사용하여 동시 편집을 방지합니다. 에이전트가 작업을 할당받으면 잠금을 획득합니다. 다른 에이전트는 작업이 할당된 것을 확인하고 수정할 수 없습니다.

📚 문서

• 프로토콜 스펙: https://tick.md/docs/protocol
• CLI 레퍼런스: https://tick.md/docs/cli
• 시작 가이드: https://tick.md/docs/getting-started

💡 예제 워크플로우

# 인간이 작업 생성
tick add "Build landing page" --priority high --tags frontend --assign @claude-code
tick add "Write launch email" --priority medium --tags content --assign @content-bot
tick add "E2E tests" --priority medium --tags qa --depends-on TASK-001

# AI 에이전트가 작업 처리
tick claim TASK-001 @claude-code
tick comment TASK-001 @claude-code --note "히어로 섹션이 포함된 반응형 랜딩 페이지 구축"
tick done TASK-001 @claude-code

# 다른 에이전트 자동 트리거
tick claim TASK-003 @qa-bot
tick done TASK-003 @qa-bot --skip-review

🔧 설정

.tick/config.yml 편집:

git:
  auto_commit: true      # 변경 시 자동 커밋 (기본값: true)
  commit_prefix: "[tick]"
  push_on_sync: false

locking:
  enabled: true
  timeout: 300

agents:
  default_trust: full
  require_registration: false

🌟 OpenClaw 봇을 위한 모범 사례

1. 작업 전 항상 할당: tick claim TASK-XXX @yourbotname
2. 진행 상황 댓글 추가: tick comment TASK-XXX @yourbotname --note "상태 업데이트"
3. 완료 시 완료 표시: tick done TASK-XXX @yourbotname
4. 의존성 확인: tick list --blocked를 사용하여 차단된 작업 찾기
5. MCP 서버 사용: 자연어 작업 관리를 가능하게 함

🔧 OpenClaw 멀티 에이전트 설정

TICK.md를 통해 여러 OpenClaw 봇을 조정하기 위한 단계별 가이드입니다.

1. 공유 작업 리포지토리 생성

gh repo create yourorg/project-tasks --private
cd project-tasks
npx tick-md init
git add -A && git commit -m "init" && git push

2. 각 OpenClaw 봇 서버에서

cd /data/.openclaw/workspace
git clone [email protected]:yourorg/project-tasks.git tasks
cd tasks && npx tick-md status

3. 각 봇의 AGENTS.md에 추가

## ✅ 작업 조정 (TICK.md)

저는 `./tasks/`의 TICK.md를 통해 다른 에이전트와 조정합니다.

### 작업 시작 전:
1. `cd tasks && npx tick-md sync` — 최신 상태 가져오기
2. `npx tick-md list --status backlog --priority high` — 사용 가능한 작업 찾기
3. `npx tick-md claim TASK-XXX @mybotname` — 작업 전 할당
4. `npx tick-md done TASK-XXX @mybotname` — 완료 표시

### 규칙:
- **다른 에이전트가 할당한 작업은 절대 수행하지 마세요**
- **시작 전 항상 할당하세요**
- **작업 전후에 동기화하세요**

4. 각 봇의 HEARTBEAT.md에 추가

## 작업 동기화 (TICK.md)

- [ ] 작업 동기화: `cd tasks && npx tick-md sync`
- [ ] 내 작업 확인: `npx tick-md list --claimed-by @mybotname --status in_progress`
- [ ] 사용 가능한 작업 확인: `npx tick-md list --status backlog --priority high`

5. 배포 키

각 봇은 공유 리포지토리에 SSH 접근이 필요합니다. 각 서버에서 배포 키를 생성하세요:

ssh-keygen -t ed25519 -C "botname@tasks" -f ~/.ssh/tasks_deploy -N ""
cat ~/.ssh/tasks_deploy.pub
# 리포지토리 설정 → 배포 키에 추가 (쓰기 권한 필요)

Git에서 사용하도록 설정:

cd tasks
git config core.sshCommand "ssh -i ~/.ssh/tasks_deploy -o IdentitiesOnly=yes"

6. 봇 동기화 명령

tick 변경 후, 변경 사항을 푸시:

cd tasks && git push

또는 pull + push를 자동으로 처리하는 tick sync 사용.

📦 패키지 정보

• CLI: tick-md on npm
• MCP 서버: tick-mcp-server on npm
• GitHub: https://github.com/Purple-Horizons/tick-md
• 라이선스: MIT

🆘 지원

• GitHub 이슈: https://github.com/Purple-Horizons/tick-md/issues
• 스폰서: https://github.com/sponsors/Purple-Horizons