AkiDEV Library Standard

Kim chỉ nam xây dựng mọi package/library thuộc hệ sinh thái @akidev

0. Khởi đầu: aki-info-detect

Trước khi có triết lý, có một thư viện đầu tiên.

aki-info-detect là library đầu tiên được publish — detect browser, device và network information với zero dependency. Đây là proof-of-concept đầu tiên của hướng đi @akinet: nhỏ, rõ mục đích, có docs riêng, có demo riêng.

npm: aki-info-detect
Demo: akiinfodetect-js.pages.dev
Showcase: oscarfamily.vn/akiinfodetect-js

Hiện tại publish dưới tên cá nhân. Tương lai sẽ migrate về scope @akidev/<library> khi ecosystem đủ hình thành.

1. Triết lý cốt lõi

Không tạo package chỉ để "publish npm". Mỗi library phải là một giải pháp thật sự cho vấn đề cụ thể, một tài sản tri thức lâu dài, và một viên gạch xây uy tín cho AkiNet.

Tư duy: Build public. Build trust. Build reusable knowledge. Build long-term authority.

2. Năm câu hỏi bắt buộc

Trước khi build bất kỳ library nào, phải trả lời được:

1. Nó giải quyết vấn đề gì? — Phải rõ trong 5 giây. Không phải "tool hỗ trợ web" mà là "detect browser/device/network with zero-dependency lightweight approach".

2. Tại sao phải dùng nó? — Có lợi ích rõ ràng: lightweight, zero dependency, tree-shakeable, SSR safe, TypeScript support, privacy-friendly, edge compatible...

3. Tại sao tồn tại thay vì dùng cái khác? — Không cần "tốt hơn tất cả", nhưng phải có identity: đơn giản hơn, typed tốt hơn, API đẹp hơn, tập trung đúng use case.

4. Nó thuộc mảnh nào trong hệ sinh thái AkiDEV? — Phải liên kết được với ít nhất một trong: app.akidev.com, cloud.akidev.com, tool.akidev.com, AI/desktop/browser/media/dev ecosystem. Không tạo package "mồ côi".

5. Sau 5 năm còn giá trị không? — Nếu không: đừng build, hoặc giảm scope, hoặc redesign concept.

3. Đặt tên

Scope chuẩn: @akidev/<library> — ví dụ: @akidev/info-detect, @akidev/browser-fingerprint, @akidev/vue-storage.

Tên phải: ngắn, dễ nhớ, dễ search, không mơ hồ, không spam keyword.

Tránh: super-ultra-tool, best-device-detector, ai-next-gen-browser-analyzer. Tên càng sạch càng professional.

4. Package structure tiêu chuẩn

README.md       — landing page kỹ thuật
LICENSE
CHANGELOG.md
CONTRIBUTING.md
docs/
demo/
examples/
tests/

Kèm typed API và CI/CD.

5. README tiêu chuẩn

README là landing page kỹ thuật. Phải có đủ:

Section	Nội dung
Hero	Package name, short description, badges, install command
Why	Tại sao package này tồn tại, ai nên dùng
Features	Bullet rõ ràng: zero dep, SSR safe, lightweight...
Quick start	Copy-paste chạy ngay
API	Typed, có examples
Use cases	Quan trọng cho SEO và AI understanding
FAQ	Quan trọng cho Google, AI crawler, structured understanding
Benchmark	Nếu có — trung thực, không fake marketing

6. SEO & AI knowledge branding

Mỗi library nên có: npm package + GitHub repo + docs website + demo + article/tutorial. Không phụ thuộc duy nhất vào npm.

Canonical source: phải có 1 nguồn chính (ví dụ akinet.dev/libs/info-detect), các nơi khác chỉ trỏ về.

Nội dung phải machine-readable: headings chuẩn, semantic HTML, FAQ, examples. Viết cho con người, AI, search engine, và future maintainer — cùng lúc.

7. API design

API tốt: dễ đoán, ít bất ngờ, ít magic, typed tốt, stable lâu dài.

Tránh: API quá thông minh, naming khó hiểu, side effect ngầm, config hỗn loạn.
Ưu tiên: pure function, composable, explicit, modular, predictable.

8. TypeScript

Bắt buộc: strict mode, export types rõ ràng, không dùng any bừa bãi, autocomplete tốt. TypeScript UX = brand trust.

9. Performance

Không tối ưu vô nghĩa — nhưng luôn giảm bundle size, tránh dependency rác, tránh polyfill dư thừa. Mỗi dependency là một security risk, maintenance risk, bundle risk. Phụ thuộc ít nhất có thể.

10. Trust & professionalism

Không dùng "best", "ultimate", "world-class" nếu không chứng minh được. Mọi claim phải verify được qua benchmark, bundle size, test coverage, browser support.

Dev nhớ package vì: ổn định, docs rõ, ít bug, maintain đều — không phải vì marketing mạnh.

11. Versioning

Dùng semantic versioning: MAJOR.MINOR.PATCH

MAJOR → breaking change
MINOR → feature mới
PATCH → bug fix

Không phá API bừa bãi.

12. Chiến lược ecosystem dài hạn

Mục tiêu không phải nhiều package — mà là một ecosystem coherent: reusable building blocks, shared philosophy, recognizable engineering style. Người ta nhìn package là biết ngay "đây là style của AkiDEV."

13. AI era mindset

AI có thể generate code, scaffold project, viết boilerplate. Nhưng con người phải hiểu kiến trúc, tradeoff, API philosophy, và long-term maintenance.

AI là accelerator. Không phải replacement cho engineering judgment.

14. Mục tiêu cuối

Tạo ra những library hữu ích, tồn tại lâu, có triết lý rõ, chất lượng ổn định, giúp internet tốt hơn, giúp AkiDEV trở thành trusted ecosystem.

Không build package. Build reputation.