maxrave-dev/kotlin-footguns

🔫 224 bài học Kotlin/Compose thực chiến, không phải lý thuyết

Mỗi kỹ năng là một tệp SKILL.md độc lập, rút từ nỗi đau thật trên môi trường sản xuất.

Dự án kotlin-footguns do maxrave-dev — người sáng lập và duy trì SimpMusic, ứng dụng nhạc đa nền tảng với hơn 10.800 sao trên GitHub — tạo ra. Đây không phải là tài liệu học từ sách vở, mà là những gì đã từng xảy ra khi phát hành phần mềm thực tế. Từ những API báo thành công nhưng thực chất đã xóa dữ liệu, đến những cờ cấu hình có hành vi khác nhau giữa các nền tảng — tất cả đều được ghi lại dưới dạng kỹ năng (skill) dành cho các đại lý lập trình như Claude Code.

✨ Điểm nổi bật

• 224 kỹ năng độc lập: mỗi kỹ năng là một tệp SKILL.md tuân thủ định dạng mở agent-skills, dễ đọc bởi cả máy và con người.
• Tập trung vào “ Traps”: phần lớn thời gian dành cho việc mô tả cụ thể cách một kỹ thuật thất bại trong thực tế, kèm theo cách kiểm chứng và khắc phục.
• Nguồn gốc từ mã nguồn thực tế: toàn bộ nội dung rút từ SimpMusic — một ứng dụng âm nhạc đa nền tảng (Android, Windows, macOS, Linux) đang hoạt động ổn định từ năm 2023.
• Cấu trúc chuẩn hóa: mỗi tệp bao gồm frontmatter, hướng dẫn ngắn, phần bẫy (Traps), và phần xác minh (Verifying it) bằng lệnh thực tế.
• Phân nhóm rõ ràng: nội dung được chia thành 14 nhóm chủ đề từ native code, desktop packaging, Compose components, reactive state, background work cho đến consuming remote APIs.
• Dễ tích hợp với công cụ: đọc trực tiếp bởi Claude Code và bất kỳ đại lý lập trình nào hỗ trợ định dạng agent-skills.
• Không phụ thuộc dịch vụ cụ thể: tập trung vào kiến trúc và cách thức thất bại chung, áp dụng cho bất kỳ API nào.
• Được kiểm chứng độc lập: mỗi lô trích xuất trải qua quy trình đánh giá chặt chẽ bởi các đội ngũ đối lập độc lập.

💡 Vì sao đáng chú ý

Khác với hầu hết các bộ kỹ năng Kotlin hoặc Android khác — thường dựa trên tài liệu chính thức — kotlin-footguns ghi nhận những gì thực sự xảy ra khi các API được triển khai trong thời gian dài. Những câu chuyện tại đây không chỉ là kinh nghiệm cá nhân, mà là kết quả tích lũy từ hàng ngàn giờ gỡ lỗi, phản hồi người dùng và vòng đời sản phẩm thật. Đây là nguồn tài nguyên hiếm hoi biến “đau khổ” thành kiến thức có hệ thống — không chỉ dạy cách viết code, mà còn cảnh báo cách nó sai thẳng từ giai đoạn phát triển.

#Kotlin #ComposeMultiplatform #JetpackCompose #Android #DesktopJVM #OpenSource #AgentSkills #TiniX