[DOCS] timo-refactor 스킬에 공통 유틸 배치 기준 추가

[jjangminii]

ISSUE 🔗

close #148

What is this PR? 🔍

유틸/상수를 어디에 둘지 판단 기준이 없어 반복되던 리뷰 코멘트를 스킬 문서에 고정했습니다. 이슈에서는 새 timo-util 스킬 생성을 계획했지만, 검토 결과 기존 timo-refactor 스킬에 이미 겹치는 섹션이 있어 새 파일 대신 그 섹션을 갱신하는 방향으로 바꿨습니다.

배경

• 기존 구조: timo-refactor 스킬의 "공통 유틸 추출" 섹션이 이미 있었지만, 판단 기준 없이 "3곳 이상 중복되면 추출"이라고만 되어 있었고, 예시 경로도 실제 코드베이스에 없는 lib/format.ts를 가리키고 있었습니다.
• 발생 문제: feat/web/136-connect-modal 작업 중 시간 관련 상수·유틸(SECONDS_PER_MINUTE 등)이 여러 파일에 중복 정의된 것을 발견해 사람이 직접 판단해 공통 위치로 옮겼는데, 이 판단 기준이 문서화돼 있지 않아 다음에도 같은 논의가 반복될 상황이었습니다. 이슈를 만들 때는 새 timo-util 스킬을 만드는 것으로 계획했습니다.
• 해결 방향: 새 스킬 파일을 만들면 timo-refactor의 기존 "공통 유틸 추출" 섹션과 트리거·내용이 겹치므로, 새 파일 대신 그 섹션 자체를 갱신해 중복 스킬이 생기지 않도록 했습니다.

timo-refactor 스킬

• 변경 요약: "공통 유틸 추출" 섹션에 공통/도메인 종속 판단 기준과 JSDoc 작성 규칙을 추가하고, 예시 경로를 실제 코드베이스 기준으로 갱신했습니다.
• 이유: 판단 기준이 없어 "이거 공통 유틸로 빼야 하지 않나요?" 같은 리뷰 코멘트가 매번 반복됐고, 기존 예시(lib/format.ts)는 실제로 존재하지 않는 경로라 참고가 되지 않았습니다.
• 구현 방식: 공통(여러 도메인 재사용) → apps/timo-web/utils/constants, 도메인 종속(단일 기능 전용) → 해당 도메인 _utils 폴더라는 2단계 기준을 추가했습니다. Before/After 예시는 이번에 실제로 진행한 리팩터링(focus/_utils/duration.ts → constants/time.ts + utils/convert-duration-to-minutes.ts)을 그대로 반영했습니다.
• 경계 · 제약: 이번 PR은 스킬 문서만 변경하며, AGENTS.md의 트리거 매핑은 파일 경로·트리거가 그대로라 변경하지 않았습니다.

To Reviewers

이슈 #148은 새 스킬 파일 생성을 전제로 작성됐지만, 실제로는 기존 스킬 갱신으로 방향을 바꿨습니다. 이슈 본문과 실제 변경 사항이 다르다는 점 참고해주세요. 판단 기준(공통 vs 도메인 종속)이 실제 팀 컨벤션과 맞는지 확인 부탁드립니다.

Screenshot 📷

Test Checklist ✔

• pnpm check-types 통과
• pnpm lint 통과
• 실제 코드 변경 없는 문서 전용 PR — 런타임 동작 검증 대상 아님

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
timo	Ready	Preview, Comment	Jul 12, 2026 9:49am

[coderabbitai]

Warning

Review limit reached

@jjangminii, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 48 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 1b1845ed-3d0f-4f94-a511-aee02268711d

📥 Commits

Reviewing files that changed from the base of the PR and between 1f9826d and 9184b74.

📒 Files selected for processing (1)

• .agents/skills/quality/timo-refactor/SKILL.md

Walkthrough

SKILL.md의 유틸리티 추출 지침을 확장했다. 공통·도메인 종속 유틸리티의 배치 위치, JSDoc 필수 항목, 시간 관련 상수와 유틸리티의 Before/After 예시를 추가했다.

Changes

유틸리티 추출 지침

Layer / File(s)	Summary
추출 위치 및 JSDoc 지침 .agents/skills/quality/timo-refactor/SKILL.md	반복 로직의 공통·도메인 종속 여부에 따른 추출 경로와 JSDoc 작성 요건을 추가하고, 시간 포맷·변환 로직의 공통화 예시로 기존 예시를 교체했다.

Estimated code review effort: 1 (Trivial) | ~3 minutes

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	제목이 기존 timo-refactor 스킬 문서에 공통 유틸 배치 기준을 추가한 핵심 변경을 정확히 요약합니다.
Description check	✅ Passed	설명이 공통/도메인 종속 기준, JSDoc 규칙, 실제 예시 갱신 등 변경 내용과 잘 맞습니다.
Linked Issues check	✅ Passed	이슈 #148의 핵심 요구인 공통/도메인 배치 기준과 JSDoc 문서화를 기존 스킬 문서 갱신으로 충족했습니다.
Out of Scope Changes check	✅ Passed	스킬 문서 수정만 포함되어 있으며, 요구와 무관한 변경은 보이지 않습니다.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch docs/root/148-add-util-placement-skill

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[kimminna]

😍

[yumin-kim2]

😍

[github-actions]

Timo Performance Report

Bundle Size — timo-web

라우트	크기	First Load JS
/[locale]/home	167.33 kB	🔴 373.15 kB
/[locale]/today	64.79 kB	🟡 270.61 kB
/[locale]/focus	61.47 kB	🟡 267.30 kB
/[locale]/settings/account	0 B	🟡 205.82 kB
/[locale]/settings	71.49 kB	🟡 277.31 kB
/[locale]/statistics	58.75 kB	🟡 264.57 kB
/[locale]/[...rest]	0 B	🟡 205.82 kB
/[locale]/login	116.05 kB	🟡 321.87 kB
/[locale]/onboarding	134.84 kB	🟡 340.66 kB
/[locale]	0 B	🟡 205.82 kB

공유 번들: 205.82 kB
🟢 < 200kB  |  🟡 < 350kB  |  🔴 ≥ 350kB (First Load JS · gzip)

Lighthouse — timo-web

URL	Perf	A11y	LCP	CLS	TBT
/en/home	🔴 60	🟢 96	🔴 14.5s	🟢 0.000	🟡 594ms
/en/today	🟡 71	🟡 93	🔴 13.8s	🟢 0.000	🟡 231ms
/en/focus	🟡 72	🟡 91	🔴 13.8s	🟢 0.000	🟡 203ms
/en/statistics	🔴 55	🟢 96	🔴 13.7s	🟢 0.000	🔴 875ms

Perf ≥ 70 / A11y ≥ 85 목표
LCP 🟢 < 2.5s 🟡 < 4s 🔴 ≥ 4s  |  CLS 🟢 < 0.1 🟡 < 0.25 🔴 ≥ 0.25  |  TBT 🟢 < 200ms 🟡 < 600ms 🔴 ≥ 600ms

Image Optimization — timo-web

파일	크기	포맷	상태
images/google-calendar.png	36.20 kB	PNG ⚠️	🟢
images/google-logo.png	26.79 kB	PNG ⚠️	🟢

총 2개 · 63.00 kB  |  🟢 < 200KB  |  🟡 < 500KB  |  🔴 ≥ 500KB
⚠️ 2개 파일 WebP/AVIF 변환 권장

측정 커밋: a55bd8b

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In @.agents/skills/quality/timo-refactor/SKILL.md:
- Around line 73-77: Update the JSDoc requirement in the
transformation/formatting placement guidance to distinguish functions from
constants: require functions to include a description, `@param`, `@returns`, and
`@example`, while requiring constants to document their description, unit where
applicable, and usage scope. Keep the existing common-versus-domain-specific
placement rules unchanged.
- Around line 80-83: Update the Before/After example to describe the current
convertDurationToTimeText flow: reference the local convertDurationToTimeText
definition in duration.ts and its shared destination at
`@/utils/convert-duration-to-time-text`, replacing convertDurationToMinutes and
convert-duration-to-minutes.ts. Keep the shared constant example and JSDoc
guidance unchanged.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 22f8ea96-843d-437a-9767-7d6d3f0131ce

📥 Commits

Reviewing files that changed from the base of the PR and between cda1a38 and 1f9826d.

📒 Files selected for processing (1)

• .agents/skills/quality/timo-refactor/SKILL.md