timeline-report

timeline-report 스킬 개요

timeline-report가 하는 일

timeline-report 스킬은 프로젝트에 기록된 claude-mem 히스토리를 바탕으로 서사형 개발 리포트를 만들어 줍니다. 현재 코드베이스를 평면적으로 요약하는 데 그치지 않고, 프로젝트가 시간에 따라 어떻게 진화했는지, 어떤 주요 단계와 전환점이 있었는지, 어떤 결정이 내려졌는지, 진척 패턴은 어땠는지를 이야기 형태로 재구성합니다.

리포트 작성용으로 가장 잘 맞는 경우

읽기 쉬운 프로젝트 이력 문서가 필요하고, 단순 이벤트 나열만으로는 부족할 때 리포트 작성용 timeline-report가 잘 맞습니다. 특히 창업자, 메인테이너, 리뷰어, 컨설턴트, 에이전트처럼 프로젝트의 전체 여정을 일관된 "Journey Into [Project]" 스타일로 설명해야 하는 사람에게 적합합니다.

실제로 해결하는 핵심 과제

대부분의 사용자는 막연한 회고 요약을 원하는 것이 아닙니다. 보통 이런 질문에 답하고 싶어 합니다:

• 이 프로젝트 개발의 주요 장면은 무엇이었나?
• 작업은 시간에 따라 어떻게 전개됐나?
• 무엇이 바뀌었고, 어디서 정체됐으며, 무엇이 속도를 냈나?
• 타임라인 데이터를 다른 사람이 실제로 읽을 수 있는 리포트로 어떻게 바꿀 수 있나?

바로 이런 지점에서 timeline-report 스킬은 일반 프롬프트보다 더 유용합니다.

timeline-report가 다른 점

가장 큰 차별점은 timeline-report가 즉석 repo 점검만이 아니라 claude-mem의 지속형 타임라인을 중심으로 설계됐다는 점입니다. 지금 파일이 무엇이 있는지만 보는 것이 아니라, 프로젝트의 역사적 서사를 뽑아내고 싶을 때 이 차이가 중요합니다. 또한 올바른 프로젝트 이름을 찾기 위한 워크플로 가이드도 포함되어 있어, 실무적으로 중요한 worktree 확인을 통해 잘못된 디렉터리가 아니라 상위 프로젝트를 기준으로 리포트를 만들 수 있게 해줍니다.

설치 전에 확인해야 할 것

이 스킬이 제대로 맞으려면 아래 두 조건이 모두 충족돼야 합니다:

• claude-mem worker가 localhost:37777에서 실행 중일 것
• 해당 프로젝트에 claude-mem 관찰 기록이 이미 저장돼 있을 것

둘 중 하나라도 없으면 timeline-report install만으로는 충분하지 않습니다. 분석할 유의미한 히스토리가 거의 없거나 아예 없을 수 있습니다.

이 스킬이 잘 맞지 않는 경우

다음만 필요하다면 timeline-report 스킬은 건너뛰는 편이 낫습니다:

• 현재 아키텍처 요약
• Git만으로 만든 changelog
• 한 문단짜리 프로젝트 설명
• claude-mem 히스토리가 없는 프로젝트용 리포팅

이런 경우에는 직접 프롬프트를 쓰거나 다른 repo 분석 스킬이 대체로 더 간단합니다.

timeline-report 스킬 사용 방법

timeline-report 설치 맥락

저장소 기준으로 이 스킬은 thedotmack/claude-mem 내부의 plugin/skills/timeline-report에 있습니다. 기본 설치 패턴은 다음과 같습니다:

npx skills add thedotmack/claude-mem --skill timeline-report

설치 후에는 출력 품질을 탓하기 전에 먼저 환경을 점검하세요:

1. claude-mem worker가 localhost:37777에서 접근 가능한지 확인
2. 대상 프로젝트에 관찰 기록이 저장되어 있는지 확인
3. 타임라인이 어떤 프로젝트 이름으로 저장돼 있는지 정확히 파악했는지 확인

먼저 읽어야 할 파일

가장 먼저 볼 파일은 다음입니다:

• plugin/skills/timeline-report/SKILL.md

이 스킬은 설정 중심이라기보다 워크플로 중심입니다. 실제 도입에서 가장 큰 리스크는 숨겨진 설정이 아니라, 잘못된 프로젝트를 대상으로 실행하거나 비어 있는 타임라인에 대해 실행하는 것입니다.

반드시 알아야 하는 입력값

가장 중요한 입력은 claude-mem이 인식하는 프로젝트 이름입니다. 사용자가 “이 프로젝트”라고 말하더라도, 스킬 가이드는 현재 디렉터리 basename을 쓰기 전에 먼저 git worktree 내부인지 확인하라고 안내합니다.

이 디테일이 중요한 이유는 worktree의 디렉터리 이름이 상위 프로젝트 타임라인 이름과 일치하지 않는 경우가 많기 때문입니다.

git worktree를 올바르게 처리하는 법

상위 스킬 설명에서 가장 실무적인 포인트는 worktree 확인입니다. worktree 안에 있다면 worktree 폴더명이 아니라 상위 프로젝트의 식별자를 사용해야 합니다. 프로젝트 이름을 잘못 잡으면 리포트 품질이 “고장 난 것처럼” 보일 수 있는데, 이는 실제로는 엉뚱하거나 너무 빈약한 메모리를 보고 있기 때문입니다.

확신이 없다면 먼저 git common directory를 확인한 뒤, 거기서 상위 프로젝트를 식별하고 나서 리포트를 요청하는 편이 안전합니다.

실제 timeline-report 사용 예시

약한 요청:

• "Write a report on this repo"

더 강한 timeline-report 사용 요청:

• "Use timeline-report to generate a Journey Into my-app based on its claude-mem timeline. Focus on major phases, important decisions, pivots, and the overall development arc."

더 나은 요청:

• "Use timeline-report for my-app. Produce an executive-readable report with sections for origin, milestone phases, key decision points, setbacks, and current trajectory. Base it on the full claude-mem timeline rather than the current repo snapshot."

막연한 목표를 강한 프롬프트로 바꾸기

좋은 결과를 얻으려면 프롬프트에 다음 요소를 넣는 것이 좋습니다:

• 정확한 프로젝트 이름
• 대상 독자
• 원하는 리포트 형식
• 강조할 포인트
• 원하는 디테일 수준

예시:

• "Use timeline-report on tokyo. Write a narrative report for stakeholders, not developers. Explain how the project started, what changed over time, where momentum increased or dropped, and what themes define its evolution."

이렇게 하면 단순히 “프로젝트 히스토리를 요약해줘”라고 하는 것보다 톤과 출력 구조가 훨씬 명확해집니다.

안정적인 출력을 위한 추천 워크플로

실무적으로는 다음 흐름이 좋습니다:

1. 올바른 프로젝트 이름을 식별한다
2. claude-mem 타임라인 데이터가 실제로 존재하는지 확인한다
3. 서사형 리포트로 요청한다
4. 출력이 단순 연대기 나열에 치우치지 않았는지 검토한다
5. 독자, 섹션 구성, 강조 포인트를 더 분명히 해서 다시 요청한다

이 스킬은 반복적으로 쓰는 방식이 가장 잘 맞습니다. 첫 번째 시도에서 타임라인의 큰 흐름을 잡고, 두 번째 시도에서 리포트 형태를 더 잘 다듬는 식입니다.

스킬에 무엇을 강조해 달라고 해야 하나

유용한 강조 포인트는 다음과 같습니다:

• 사소한 이벤트보다 주요 마일스톤
• 아키텍처 또는 제품 방향 전환
• 릴리스 준비도 진척
• 디버깅 또는 복구 구간
• 의사결정 패턴
• 프로젝트 방향성을 설명해 주는 핵심 테마

이런 가이드가 없으면 타임라인 리포트는 길기만 하고 의사결정에 덜 도움이 되는 결과가 되기 쉽습니다.

generic한 출력을 피하는 방법

timeline-report가 밋밋한 요약처럼 들리지 않게 하려면, 다음을 명시적으로 요청하세요:

• 이벤트 목록이 아니라 단계별 구분
• 단순 타임스탬프가 아니라 인과 설명
• 큰 변화 뒤에는 “왜 이것이 중요했는지” 설명
• 프로젝트의 현재 궤적에 대한 마무리 평가

이렇게 해야 단순 메모리 덤프가 아니라 실제 리포트 작성에 가까운 결과를 얻을 수 있습니다.

timeline-report 설치 및 사용 중 자주 막히는 지점

주요 문제는 문체가 아니라 운영 조건 쪽에 있습니다:

• claude-mem worker가 실행 중이 아님
• 프로젝트에 관찰 기록이 없음
• 잘못된 프로젝트 이름을 사용함
• worktree 이름을 상위 프로젝트 이름으로 착각함
• 사용자가 현재 코드 분석을 기대했지만 실제 스킬은 히스토리 분석에 초점이 맞춰져 있음

도입이 잘 안 된다면 프롬프트를 다시 쓰기 전에 먼저 이 부분부터 점검하세요.

timeline-report 스킬 FAQ

timeline-report는 일반 프롬프트보다 더 나은가?

목표가 claude-mem 데이터를 바탕으로 한 프로젝트 이력 리포팅이라면 그렇습니다. 일반 프롬프트로도 서사형 출력을 요청할 수는 있지만, timeline-report 스킬은 역사적 개발 분석과 "Journey Into [Project]"라는 사용 맥락에 맞춰 이미 과업이 구조화되어 있습니다.

timeline-report는 초보자도 쓰기 쉬운가?

대체로는 그렇습니다. 단, 환경이 이미 갖춰져 있다는 전제가 필요합니다. 사용 패턴 자체는 단순하지만, 초보자는 다음 전제 조건에서 막히기 쉽습니다: worker 실행, 관찰 기록 저장 여부, 그리고 올바른 프로젝트 이름 확인.

긴 히스토리가 있는 저장소가 꼭 필요한가?

반드시 그런 것은 아닙니다. 다만 타임라인에 단계 변화와 흐름이 드러날 정도의 밀도가 있을수록 이 스킬의 가치가 커집니다. 메모리가 듬성듬성하면 리포트도 얇아질 수밖에 없습니다.

claude-mem 없이 timeline-report를 사용할 수 있나?

아니요. 이 스킬은 claude-mem 타임라인 데이터와 localhost:37777의 worker에 명시적으로 의존합니다. 이 생태계가 없다면 이 도구는 적합하지 않습니다.

언제 리포트 작성용 timeline-report를 쓰지 말아야 하나?

다음이 필요하다면 리포트 작성용 timeline-report는 쓰지 않는 편이 낫습니다:

• 현재 상태 기준 코드 감사
• 보안 리뷰
• API 문서화
• Git만 기반으로 한 changelog
• claude-mem에서 한 번도 추적되지 않은 프로젝트 분석

timeline-report는 현재 코드베이스도 함께 분석하나?

핵심 가치는 전체 repo 점검이 아니라 역사적 서사에 있습니다. 다른 분석 단계와 조합할 수는 있지만, 이 스킬 자체는 메모리 관찰 기록을 바탕으로 한 개발 이력 분석에 초점을 둡니다.

timeline-report 결과가 약하거나 모호하게 나오는 이유는?

대개는 다음 중 하나입니다:

• 타임라인 데이터가 너무 희소함
• 잘못된 프로젝트를 대상으로 했음
• 프롬프트에 대상 독자나 리포트 형식이 지정되지 않았음
• 구조화된 서사 리포트가 아니라 넓은 범위의 요약만 요청했음

timeline-report 스킬 개선 방법

timeline-report에 정확한 리포팅 브리프를 주기

가장 큰 품질 개선 포인트는 더 좋은 브리프입니다. timeline-report에 다음을 분명히 알려주세요:

• 리포트 독자가 누구인지
• 서사형을 원하는지, executive summary를 원하는지
• 어떤 테마를 드러내야 하는지
• 무엇을 덜 강조해야 하는지

예시:

• "Use timeline-report on my-app for an investor-style update. Focus on momentum, milestones, pivots, and evidence of execution."

먼저 올바른 프로젝트 식별자를 제공하기

리포트가 빈약해 보인다면 다른 것을 바꾸기 전에 먼저 프로젝트 이름부터 검증하세요. 특히 worktree 환경에서는 이 한 가지 수정만으로도 어떤 프롬프트 조정보다 출력이 크게 좋아질 수 있습니다.

요약만이 아니라 구조를 요청하기

더 강한 구조 요청은 가독성을 즉시 개선하는 경우가 많습니다. 예를 들어 다음과 같은 섹션을 요청해 보세요:

• 프로젝트 기원
• 초기 구축 단계
• 전환점
• 안정화 또는 확장 단계
• 현재 궤적

이렇게 하면 사람들이 훑어보고 재활용하기 쉬운 형태의 리포트를 만들 가능성이 높아집니다.

단순 연대기를 넘어서기

흔한 실패 패턴은 타임라인이 날짜 달린 메모처럼 읽히는 것입니다. timeline-report 사용 품질을 높이려면 해석을 요청하세요:

• "group events into phases"
• "identify the main inflection points"
• "explain what changed after each pivot"
• "highlight recurring themes"

이런 식의 지시가 있어야 단순 나열을 넘어 의미 있는 해석이 붙습니다.

첫 초안 이후 출력을 개선하는 법

첫 결과를 받은 뒤에는 처음부터 다시 시작하기보다, 한 가지 목적이 분명한 수정 요청을 하는 편이 좋습니다:

• 더 짧게 해달라고 요청
• 더 executive-facing하게 바꿔 달라고 요청
• 기술 세부사항보다 제품 의사결정을 더 강조해 달라고 요청
• 프로젝트 방향에 대한 최종 평가를 추가해 달라고 요청

이 스킬은 역사적 기반 데이터는 그대로 두고 편집 방향만 다듬을 수 있어서, 반복 개선이 특히 잘 먹힙니다.

원하는 결과에 맞는 도구로 쓰기

스토리, 흐름, 개발 맥락이 필요할 때 timeline-report 스킬을 쓰세요. 반대로 정말 필요한 것이 기술 문서화, 의존성 분석, repo 온보딩이라면 초기에 다른 도구로 바꾸는 것이 낫습니다. 가장 빠르게 결과를 개선하는 방법은, 애초에 맞는 도구를 선택하는 것입니다.