Lời nhắc được thiết kế nhằm hướng dẫn phân tích kỹ thuật chuyên sâu về kho lưu trữ mã nhằm đẩy nhanh quá trình làm quen của nhà phát triển. Nó hướng dẫn AI phân tích toàn bộ cơ sở mã và tạo tài liệu Markdown có cấu trúc bao gồm kiến trúc, ngăn xếp công nghệ, các thành phần chính, luồng dữ liệu và thực thi, tích hợp, kiểm tra, bảo mật và xây dựng/triển khai, đóng vai trò là hướng dẫn tham khảo kỹ thuật.
**Bối cảnh:**
Tôi là một nhà phát triển vừa tham gia dự án và tôi đang nhờ bạn, một trợ lý mã hóa AI, để hiểu sâu hơn về cơ sở mã hiện có. Mục tiêu của tôi là làm việc hiệu quả nhanh nhất có thể và đưa ra các quyết định kỹ thuật sáng suốt dựa trên sự hiểu biết vững chắc về hệ thống hiện tại.
**Mục tiêu chính:**
Phân tích mã nguồn được cung cấp trong dự án/không gian làm việc này và tạo **tài liệu Markdown chi tiết, rõ ràng và có cấu trúc tốt** giải thích kiến trúc, tính năng, quy trình chính, thành phần chính và ngăn xếp công nghệ của hệ thống.
Tài liệu này sẽ đóng vai trò như **hướng dẫn giới thiệu kỹ thuật**.
Bất cứ khi nào có thể, hãy cải thiện khả năng điều hướng bằng cách cung cấp **liên kết trực tiếp đến các tệp, lớp và hàm có liên quan**, cũng như các ví dụ về mã giúp làm rõ các khái niệm.
---
## **Hướng dẫn chi tiết — Vui lòng giải quyết các điểm sau:**
### 1. **README / Tóm tắt tệp hướng dẫn**
- Tìm kiếm các tệp như `README.md`, `LEIAME.md`, `CONTRIBUTING.md` hoặc tài liệu tương tự.
- Cung cấp bản tóm tắt khách quan nhưng chi tiết về các phần phù hợp nhất cho nhà phát triển mới, bao gồm:
- Tổng quan dự án
- Cách thiết lập và chạy hệ thống cục bộ
- Các tiêu chuẩn và quy ước được thông qua
- Hướng dẫn đóng góp (nếu có)
---
### 2. **Ngăn xếp công nghệ chi tiết**
- Xác định và liệt kê đầy đủ các công nghệ được sử dụng trong dự án:
- (Các) ngôn ngữ lập trình, bao gồm các phiên bản khi có thể phát hiện được (ví dụ: từ `package.json`, `pom.xml`, `.tool-versions`, `requirements.txt`, `build.gradle`, v.v.).
- Các khung chính (phụ trợ, giao diện người dùng, v.v. - ví dụ: Spring Boot, .NET, React, Angular, Vue, Django, Rails).
- Cơ sở dữ liệu:
- Kiểu (SQL/NoSQL)
- Tên (PostgreSQL, MongoDB, v.v.)
- Phong cách kiến trúc cốt lõi (ví dụ: Monolith, Microservices, Serverless, MVC, MVVM, Clean Architecture).
- Nền tảng đám mây (nếu có thể nhận dạng thông qua SDK hoặc cấu hình - AWS, Azure, GCP).
- Xây dựng các công cụ và trình quản lý gói (Maven, Gradle, npm, Fiber, pip).
- Bất kỳ công nghệ liên quan nào khác (bộ nhớ đệm, môi giới tin nhắn, container hóa — Docker, Kubernetes).
- **Tham khảo và liên kết các file cấu hình thể hiện từng mục.**
---
### 3. **Tổng quan và mục đích của hệ thống**
- Mô tả rõ ràng hệ thống làm gì và dành cho ai.
- Nó giải quyết được vấn đề gì?
- Liệt kê các chức năng cốt lõi.
- Nếu có thể, hãy liên hệ hệ thống với các lĩnh vực kinh doanh liên quan.
- Cung cấp một mô tả cấp cao về các tính năng chính.
---
### 4. **Cấu trúc dự án và khuyến nghị đọc**
- **Điểm vào:**
Tôi nên bắt đầu khám phá mã ở đâu? Xác định các điểm nhập chính (ví dụ: `main.go`, `index.js`, `Program.cs`, `app.py`, `Application.java`).
**Cung cấp liên kết trực tiếp tới các tệp này.**
- **Tổ chức chung:**
Giải thích cấu trúc thư mục và tập tin tổng thể. Nêu bật các quy ước quan trọng.
**Sử dụng ví dụ về tên thư mục và tệp thực.**
- **Cấu hình:**
Có tập tin cấu hình chính không? (ví dụ: `config.yaml`, `.env`, `appsettings.json`)
Những cấu hình nào là quan trọng?
**Cung cấp liên kết.**
- **Khuyến nghị đọc:**
Đề xuất thứ tự hoặc tập hợp các tệp/mô-đun chính cần đọc trước để nhanh chóng nắm bắt các khái niệm cốt lõi của dự án.
---
### 5. **Thành phần chính**
- Xác định và mô tả các mô-đun, lớp, chức năng hoặc dịch vụ quan trọng hoặc trung tâm nhất.
- Nêu rõ trách nhiệm của từng thành phần.
- Mô tả trách nhiệm và sự phụ thuộc lẫn nhau của họ.
- Đối với từng thành phần:
- Bao gồm đoạn mã đại diện
- Cung cấp một liên kết đến nơi nó được thực hiện
- **Cung cấp liên kết trực tiếp và ví dụ về mã bất cứ khi nào có thể.**
---
### 6. **Thực thi và luồng dữ liệu**
- Mô tả các quy trình công việc hoặc quy trình kinh doanh phổ biến hoặc quan trọng nhất (ví dụ: xử lý đơn hàng, xác thực người dùng).
- Giải thích cách dữ liệu di chuyển trong hệ thống:
- Nơi dữ liệu được lưu giữ
- Cách nó được đọc, sửa đổi và phổ biến
- **Bất cứ khi nào có thể, hãy minh họa bằng các ví dụ và liên kết đến các hàm hoặc lớp có liên quan.**
#### 6.1 **Tổng quan về lược đồ cơ sở dữ liệu (nếu có)**
- Đối với các ứng dụng sử dụng nhiều dữ liệu:
- Xác định các thực thể/bảng/bộ sưu tập chính
- Nêu mối quan hệ chính của chúng
- Dựa trên mô hình ORM, quá trình di chuyển hoặc tệp lược đồ nếu có
---
### 7. **Phụ thuộc và tích hợp**
- **Phụ thuộc:**
Liệt kê các thư viện, khung và SDK chính bên ngoài được sử dụng.
Hãy giải thích ngắn gọn vai trò của từng người.
**Cung cấp liên kết đến nơi chúng được định cấu hình hoặc được sử dụng phổ biến nhất.**
- **Tích hợp:**
Xác định và giải thích sự tích hợp với các dịch vụ bên ngoài, cơ sở dữ liệu bổ sung, API của bên thứ ba, nhà môi giới tin nhắn, v.v.
Giao tiếp diễn ra như thế nào?
**Chỉ vào các mô-đun/lớp chịu trách nhiệm và kèm theo các liên kết.**
#### 7.1 **Tài liệu API (nếu có)**
- Nếu dự án có API:
- Có bằng chứng về các công cụ hoặc tiêu chuẩn tài liệu API (ví dụ: Swagger/OpenAPI, Javadoc, chuỗi tài liệu dành riêng cho điểm cuối) không?
- Tài liệu này có thể được tìm thấy ở đâu hoặc có thể được tạo ra như thế nào?
---
### 8. **Sơ đồ**
- Tạo sơ đồ cấp cao để trực quan hóa kiến trúc và hành vi của hệ thống:
- Sơ đồ thành phần (làm nổi bật các mô-đun chính và sự tương tác của chúng)
- Sơ đồ luồng dữ liệu (thể hiện cách thông tin di chuyển trong hệ thống)
- Sơ đồ lớp (hiển thị các lớp và mối quan hệ chính, nếu có)
- Sơ đồ triển khai được đơn giản hóa (nơi các thành phần chạy, nếu có thể phát hiện được)
- Sơ đồ cơ sở hạ tầng/triển khai đơn giản hóa (nếu chi tiết cơ sở hạ tầng rõ ràng)
- **Tạo các sơ đồ này bằng cú pháp Nàng tiên cá bên trong tệp Markdown.**
- Sơ đồ phải **cấp cao**; chi tiết rộng rãi là không cần thiết.
---
### 9. **Thử nghiệm**
- Có kiểm tra tự động không?
- Kiểm tra đơn vị
- Kiểm tra tích hợp
- Kiểm tra từ đầu đến cuối (E2E)
- Họ nằm ở đâu trong dự án?
- Những khung thử nghiệm nào được sử dụng?
- Các bài kiểm tra thường được thực hiện như thế nào?
- Làm cách nào để chạy thử nghiệm cục bộ?
- Có chiến lược CI/CD nào liên quan đến kiểm tra không?
---
### 10. **Xử lý lỗi và ghi nhật ký**
- Ứng dụng thường xử lý lỗi như thế nào?
- Có mẫu chuẩn nào không (ví dụ: phần mềm trung gian toàn cầu, ngoại lệ tùy chỉnh)?
- Thư viện ghi nhật ký nào được sử dụng?
- Có định dạng ghi nhật ký chuẩn không?
- Có tích hợp rõ ràng với các công cụ giám sát (ví dụ: Datadog, Sentry) không?
---
### 11. **Cân nhắc về bảo mật**
- Có cơ chế bảo mật rõ ràng trong mã không?
- Xác thực
- Ủy quyền (phần mềm trung gian/bộ lọc)
- Xác thực đầu vào
- Các thư viện bảo mật cụ thể có được sử dụng phổ biến không (ví dụ: thư viện Spring Security, Passport.js, JWT)?
- Có thực tiễn bảo mật đáng chú ý nào không?
- Quản lý bí mật
- Bảo vệ chống lại các cuộc tấn công thông thường
---
### 12. **Các quan sát liên quan khác (Bao gồm cả Xây dựng/Triển khai)**
- Có tập tin nào liên quan đến **xây dựng hoặc triển khai** không?
- `Dockerfile`
- `docker-compose.yml`
- Xây dựng/triển khai tập lệnh
- Tệp cấu hình CI/CD (ví dụ: `.github/workflows/`, `.gitlab-ci.yml`)
- Các tệp này cho biết gì về cách ứng dụng được xây dựng và triển khai?
- Có điều gì khác quan trọng hoặc đặc biệt hữu ích cho nhà phát triển mới không?
- Đã biết nợ kỹ thuật đề cập ở phần bình luận
- Mẫu thiết kế khác thường
- Các quy ước mã hóa quan trọng
- Ghi chú hiệu suất
---
## **Định dạng đầu ra cuối cùng**
- Tạo phản hồi hoàn chỉnh dưới dạng **tài liệu Markdown (`.md`) được định dạng đúng**.
- Sử dụng **ngôn ngữ rõ ràng và trực tiếp**.
- Sắp xếp nội dung với **tiêu đề và phụ đề** theo các phần được đánh số ở trên.
- **Bao gồm các đoạn mã có liên quan** (ngắn gọn và mang tính đại diện).
- **Bao gồm các liên kết có thể nhấp** tới các tệp, hàm, lớp và định nghĩa bất cứ khi nào một thành phần mã cụ thể được đề cập.
- Cấu trúc tài liệu sử dụng các phần được đánh số ở trên để dễ đọc.
**Bất cứ khi nào có thể:**
- Bao gồm **các liên kết có thể nhấp** tới các tệp, hàm và lớp.
- Hiển thị **đoạn mã ngắn, mang tính đại diện**.
- Sử dụng **dấu đầu dòng hoặc bảng** cho danh sách.
---
### **QUAN TRỌNG**
Việc phân tích phải xem xét **TẤT CẢ các tệp trong dự án**.
Đọc và hiểu **tất cả các tệp cần thiết** cần thiết để thực hiện đầy đủ nhiệm vụ này và đạt được sự hiểu biết đầy đủ về hệ thống.
---
### **Hành động**
Vui lòng phân tích mã nguồn hiện có trong môi trường/không gian làm việc của tôi và tạo tài liệu Markdown theo yêu cầu.
Tên tệp đầu ra phải tuân theo định dạng sau:
`<yyyy-mm-dd-project-name-app-dev-discovery_cursor.md>`