Skip to content

AGENTS.md

Latest commit

 

History

History
108 lines (82 loc) · 4.74 KB

AGENTS.md

File metadata and controls

108 lines (82 loc) · 4.74 KB
Raw

AGENTS.md

Entry point and routing document for AI agents (Claude Code, Codex, etc.). This file only tells you WHERE to look — detailed rules live in linked docs.

Project Summary

Keeply — a mobile-first web service for convenience store workers. Consolidates announcements, operation logs, and expiration-date tracking to eliminate information loss and duplicate work across shifts.

  • Tech Stack: React 19 + TypeScript 6 + Vite 8 + TailwindCSS
  • Package Manager: pnpm (ESM)

Required Reading (Source of Truth)

Read these before starting any work.

Skill Routing

Use the following skills based on task type. Natural language triggers auto-match.

Task Type Skill Trigger Examples
Start Notion task (Notion → GitHub) start-notion-task "Notion 태스크 시작해줘", "이 태스크 시작하자"
Create GitHub issue create-issue "이슈 만들어줘", "이슈 올려야 해"
Design implementation logic-design "설계 좀 해줘", "구현 계획 세워줘"
Review branch (pre-push) branch-review "리뷰해줘", "push 전 확인해줘"
Create / update PR create-pr "PR 올려줘", "PR 설명 써줘"

Standard Skill Execution

Every skill invocation follows this flight protocol:

  1. Preflight — .agents/checklists/preflight.md — verify context, branch, issue, and get user approval
  2. Flight — Execute skill-specific steps (from the skill's SKILL.md)
  3. Postflight — .agents/checklists/postflight.md — lint / typecheck / build / convention checks
  4. Debrief — Report using .agents/checklists/debrief.md format

Exception: Trivial fixes (typo, missing semicolon, 1 file & ≤5 lines) may skip preflight steps 3-5, but must be explicitly declared upfront.

Standard Workflow

Typical feature development order (Notion-first hybrid):

1. Create Notion task    → (create manually in Notion "Task 관리" DB)
2. Start Notion task     → start-notion-task
                           (auto: GitHub Issue + branch + Notion → "진행 중")
3. Design implementation → logic-design
4. Implement
5. Review branch         → branch-review
6. Create PR             → create-pr
                           (manually update Notion "리뷰 중" / PR URL; auto sync TBD)

Note: Notion is the source of truth for tasks. GitHub Issues are auto-mirrored for PR linking. Steps 6+ Notion sync automation is planned but not yet implemented.

Skill Specification

  • Location: .agents/skills/{name}/SKILL.md (single source of truth)
  • Claude Code slash command compatibility: .claude/commands/{name}.md is a symlink
  • Frontmatter only uses name and description
  • Names must be lowercase kebab-case

Work Policy (Mandatory)

  1. Always preview → get approval → execute before creating or modifying code
  2. Respond in Korean by default (exception only when requested)
  3. Always include file paths (e.g., apps/web/src/...)
  4. Stay within scope — do only what was requested

Folder Structure (Summary)

keeply-client/
├── AGENTS.md                    ← this file (router)
├── CLAUDE.md                    ← Claude Code entry point (references this file)
│
├── docs/                        ← human-facing manuals (source of truth)
│   ├── rules/
│   └── branch-review/
│
├── .agents/                     ← AI execution harness
│   ├── checklists/              ← flight protocol (preflight / postflight / debrief)
│   │   ├── preflight.md
│   │   ├── postflight.md
│   │   └── debrief.md
│   └── skills/                  ← actual skill files
│       ├── branch-review/SKILL.md
│       ├── create-issue/SKILL.md
│       ├── create-pr/SKILL.md
│       ├── logic-design/SKILL.md
│       └── start-notion-task/SKILL.md
│
└── .claude/
    └── commands/                ← Claude Code slash commands (symlinks → .agents/skills)

Documentation Sync Rule

  • Modify docs/ first → .agents/ follows (one-way, never reverse)
  • Editing a skill file auto-reflects to symlinks (.agents/skills/ → .claude/commands/)