Tối Ưu Hóa Tài Liệu AI: Chiến Lược và Ví Dụ Thực Tế

Vấn Đề Hiệu Quả Tài Liệu

Trong giai đoạn 4.6, tôi đã tách kho lưu trữ monolithic thành các thư viện commons mô-đun để ngăn AI tiếp xúc với mã không liên quan. Mặc dù điều này giải quyết vấn đề ranh giới vật lý, nhưng nó đã tạo ra một thách thức mới: AI không tự động biết về các thư viện tùy chỉnh.

Yêu cầu Claude đọc các tệp JAR hoặc tài liệu bên ngoài đã làm gián đoạn quy trình phát triển. Đồng thời, việc cung cấp mã commons đầy đủ cho AI là không hiệu quả - đó là một nhiệm vụ nặng nề bao gồm các chi tiết triển khai mà AI không cần cho hầu hết các hoạt động.

Giải pháp trở nên rõ ràng: biên soạn chữ ký commons và ví dụ thành tài liệu thân thiện với AI cung cấp chính xác những gì AI cần, khi nó cần.

Chiến Lược Biên Soạn

AI Thực Sự Cần Gì

Thông qua các thí nghiệm, tôi phát hiện ra rằng AI cần các mức độ chi tiết khác nhau cho các nhiệm vụ khác nhau:

Đối với Thư Viện Commons: Chữ ký lớp, giao diện phương thức và nhận xét - nhưng không cần chi tiết triển khai. AI cần hiểu những gì có sẵn và cách sử dụng nó, không phải cách thức hoạt động bên trong.

Đối với Ví Dụ Triển Khai: Mã hoàn chỉnh với tất cả các chi tiết triển khai, nhận xét và kịch bản kiểm thử. Khi AI xây dựng chức năng tương tự, nó cần các mẫu đầy đủ để theo dõi.

Đối với Hằng Số và Cấu Hình: Tất cả các giá trị có thể và ý nghĩa của chúng. Đây là dữ liệu tham khảo mà AI nên có quyền truy cập đầy đủ.

Các Dự Án Biên Soạn

Tôi đã tạo hai kho lưu trữ chính để xử lý chiến lược tài liệu này:

Framework Prompts: Chứa các hướng dẫn biên soạn cho các loại tài liệu khác nhau, được chia theo mục đích:

commons.md: Hướng dẫn biên soạn thư viện commons chỉ để lấy chữ ký
service-impl-main.md: Ví dụ triển khai đầy đủ cho AI tham khảo
service-impl-test.md: Kịch bản và mẫu kiểm thử hoàn chỉnh
service-objects-main.md: Cấu trúc đối tượng với các phương thức trống cho TDD
service-objects-test.md: Tiện ích kiểm thử, giả lập và đối tượng mẹ

Framework Examples: Lưu trữ các tệp markdown đã biên soạn mà AI có thể dễ dàng đọc và tham khảo trong quá trình phát triển.

Quy Trình Biên Soạn Trong Hành Động

Ví Dụ Biên Soạn Commons

Dưới đây là cách biên soạn commons chuyển đổi mã thư viện dài dòng thành tài liệu thân thiện với AI:

Trước (Triển Khai Đầy Đủ):

kotlin Copy

/**
 * Xác thực các lệnh bằng cách sử dụng danh sách quy tắc xác thực với thực thi bất đồng bộ.
 * Hỗ trợ xác thực song song để cải thiện hiệu suất.
 */
open class CommandValidator(
    private val rules: List<ValidationRule<*>>,
    coroutines: Int = 5,
) {

    private val validationDispatcher = Dispatchers.IO.limitedParallelism(
        parallelism = coroutines,
        name = "command-validator"
    )

    /**
     * Xác thực lệnh và ném ValidationException nếu phát hiện lỗi
     */
    suspend fun validate(command: Command) {
        val errors = validateAndGetErrors(command)
        if (errors.isNotEmpty()) throw ValidationException(errors)
    }

    /**
     * Xác thực lệnh và trả về danh sách lỗi xác thực mà không ném ra
     */
    suspend fun validateAndGetErrors(command: Command): List<ValidationError> = withContext(validationDispatcher) {
        rules
            .filter { it.isApplicable(command) }
            .map { async { it.validateOne(command) } }
            .awaitAll()
            .filterNotNull()
    }

    @Suppress("UNCHECKED_CAST")
    private fun ValidationRule<*>.validateOne(command: Command): ValidationError? {
        val input: Any = command.toInput() ?: return null
        val typedRule: ValidationRule<Any> = this as ValidationRule<Any>
        return typedRule.validate(input)
    }
}

Sau (Đã Biên Soạn Cho AI):

kotlin Copy

/**
 * Xác thực các lệnh bằng cách sử dụng danh sách quy tắc xác thực với thực thi bất đồng bộ.
 * Hỗ trợ xác thực song song để cải thiện hiệu suất.
 */
open class CommandValidator(
    private val rules: List<ValidationRule<*>>,
    coroutines: Int = 5,
) {
    /**
     * Xác thực lệnh và ném ValidationException nếu phát hiện lỗi
     */
    suspend fun validate(command: Command)

    /**
     * Xác thực lệnh và trả về danh sách lỗi xác thực mà không ném ra
     */
    suspend fun validateAndGetErrors(command: Command): List<ValidationError>
}

Quy trình biên soạn:

Trích xuất chữ ký lớp và giao diện công khai
Bảo tồn tất cả các nhận xét (quan trọng cho việc AI hiểu)
Loại bỏ các chi tiết triển khai mà AI không cần
Nhóm theo gói để dễ dàng điều hướng
Bao gồm tất cả các hằng số với các giá trị của chúng

Chiến Lược Biên Soạn Ví Dụ

Đối với các ví dụ triển khai, chiến lược thay đổi theo mục đích:

service-objects-main.md: Cấu trúc đối tượng đã chuẩn bị với các phương thức trống sẵn sàng cho TDD

service-objects-test.md: Các lớp tiện ích, giả lập và đối tượng mẹ cho kiểm thử

service-impl-test.md: Kịch bản kiểm thử hoàn chỉnh cho thấy các mẫu mong muốn

service-impl-main.md: Các triển khai hoàn chỉnh mà AI có thể học hỏi từ đó

Mỗi cái có hướng dẫn cụ thể về những gì cần bao gồm, những gì cần loại bỏ và cách định dạng kết quả để tối đa hóa khả năng hiểu của AI.

Ví Dụ Biên Soạn Đối Tượng Dịch Vụ

Biên soạn service-objects-main.md chuyển đổi các triển khai hoàn chỉnh thành các cấu trúc sẵn sàng cho TDD:

Trước (Triển Khai Đầy Đủ):

kotlin Copy

class CreateUserUseCase(
    private val timeProvider: TimeProvider,
    private val idProvider: IdProvider<UUID>,
    private val validator: CommandValidator,
    private val storagePort: UserStoragePort,
) : SaveCommandUseCase<CreateUserCommand, User> {

    /**
     * Đây là điểm vào. Luôn luôn triển khai SaveCommandUseCase<COMMAND, MODEL>
     */
    override suspend fun execute(command: CreateUserCommand): Model<User> {
        validator.validate(command)

        val user = Model(
            // LƯU Ý: Đọc kỹ yêu cầu về cách tạo id: một id ngẫu nhiên hoặc dựa trên thông số
            id = idProvider.generate(command.email),
            version = 0,
            createdAt = timeProvider.now(),
            updatedAt = timeProvider.now(),
            data = User(
                email = command.email,
                name = command.name,
            )
        )

        return storagePort.create(user)
    }
}

Sau (Đã Biên Soạn Cho TDD):

kotlin Copy

class CreateUserUseCase(
    private val timeProvider: TimeProvider,
    private val idProvider: IdProvider<UUID>,
    private val validator: CommandValidator,
    private val storagePort: UserStoragePort,
) : SaveCommandUseCase<CreateUserCommand, User> {

    /**
     * Đây là điểm vào. Luôn luôn triển khai SaveCommandUseCase<COMMAND, MODEL>
     */
    override suspend fun execute(command: CreateUserCommand): Model<User> {
        TODO("Chưa được triển khai")
    }
}

Quy trình biên soạn này:

Bảo tồn cấu trúc lớp và các phụ thuộc
Giữ tất cả các nhận xét để hướng dẫn AI hiểu
Thay thế triển khai bằng các đoạn mã phù hợp (TODO, null, emptyList())
Duy trì chữ ký kiểu để thành công trong biên soạn
Cung cấp gợi ý triển khai thông qua các nhận xét

Giải Pháp Tự Động Hóa

Kịch Bản Cấp Dự Án

Mỗi dự án có các kịch bản bash đơn giản thực hiện Claude với các yêu cầu biên soạn phù hợp:

Đối với Các Dự Án Commons (ví dụ: kịch bản common-service):

bash Copy

cd ../common-service-core || exit
claude "Đọc yêu cầu: ~/VTProjects/framework/be/kotlin/prompts/compilation/commons.md"

Đối với Các Dự Án Ví Dụ (ví dụ: kịch bản dịch vụ người dùng):

bash Copy

cd ../../../../service/core/impl || exit
claude "Đọc yêu cầu: ~/VTProjects/framework/be/kotlin/prompts/compilation/service-impl-main.md"

Quy Trình Biên Soạn

Nhà phát triển cập nhật thư viện commons hoặc mã ví dụ
Chạy kịch bản biên soạn (một lệnh bash duy nhất)
Claude đọc yêu cầu, trích xuất thông tin phù hợp
Kết quả tự động được đặt trong dự án ví dụ
AI giờ đây có thể tham khảo tài liệu đã biên soạn một cách hiệu quả

Tích Hợp Với Quy Trình Phát Triển

Trước Khi Tạo Mã

Giờ đây, khi tôi yêu cầu AI tạo mã dựa trên thông số kỹ thuật, quy trình bắt đầu với:

Đọc commons đã biên soạn: AI hiểu các tiện ích và mẫu có sẵn
Đọc các ví dụ liên quan: AI thấy các mẫu triển khai hoàn chỉnh
Tạo theo các mẫu đã theo dõi: AI có những ví dụ cụ thể để theo dõi

Kết Quả Đến Nay

Phương pháp tài liệu đã biên soạn cho thấy những cải tiến hứa hẹn:

Tải Ngữ Cảnh Nhanh Hơn: AI có thể nhanh chóng quét các chữ ký đã biên soạn thay vì phân tích các triển khai đầy đủ

Nhận Diện Mẫu Tốt Hơn: Các ví dụ hoàn chỉnh giúp AI tạo mã chính xác hơn

Giảm Sáng Tạo: Khi AI thấy các mẫu đã thiết lập, nó ít có khả năng phát minh ra các giải pháp phức tạp cho các vấn đề đơn giản

Giới Hạn Hiện Tại

Vẫn Cần Nhiều Ví Dụ Hơn: AI tạo ra kết quả tốt hơn với nhiều ví dụ tham khảo hơn. Đến nay, tôi đã cung cấp chỉ một ví dụ với dịch vụ người dùng, điều đó là chưa đủ.

Hành Vi Chỉnh Sửa Kiểm Thử: AI vẫn đôi khi chỉnh sửa các bài kiểm tra khi triển khai gặp sự cố, thay vì sửa chữa triển khai.

Bước Tiếp Theo: Vượt Qua CRUD

Hệ thống hiện tại tôi xây dựng giả định các hoạt động CRUD cơ bản, nhưng kiến trúc của tôi yêu cầu các mẫu dựa trên sự kiện mà vẫn còn thiếu. Giai đoạn tiếp theo tôi sẽ sửa chữa vấn đề này và thêm hỗ trợ sự kiện.

Tôi cũng đang điều tra Event Modeling như một khuôn khổ có thể tự nhiên phù hợp với mục tiêu kiến trúc của tôi và làm cho quy trình từ đặc tả đến triển khai trở nên liền mạch hơn.

Thấu Hiểu Chính: Tài Liệu Như Giao Diện Mã

Giai đoạn này đã dạy tôi rằng tài liệu cho AI không giống như tài liệu cho con người. AI cần:

Định dạng cấu trúc, nhất quán
Ví dụ đầy đủ, không phải đoạn mã một phần
Chữ ký mà không có tiếng ồn triển khai
Dữ liệu tham khảo ở định dạng dễ quét

Cách tiếp cận biên soạn coi tài liệu như một giao diện giữa mã được viết bởi con người và việc tiêu thụ của AI - tối ưu hóa cho việc đọc của máy trong khi vẫn dễ hiểu cho con người.

Hệ thống biên soạn này minh họa một nguyên tắc khác của VibeTDD: tối ưu hóa ngữ cảnh của AI cho nhiệm vụ cụ thể, thay vì cung cấp mọi thứ và hy vọng AI tìm ra điều gì là liên quan.

Tối Ưu Hóa Tài Liệu AI: Chiến Lược và Ví Dụ Thực Tế

Vấn Đề Hiệu Quả Tài Liệu

Chiến Lược Biên Soạn

AI Thực Sự Cần Gì

Các Dự Án Biên Soạn

Quy Trình Biên Soạn Trong Hành Động

Ví Dụ Biên Soạn Commons

Chiến Lược Biên Soạn Ví Dụ

Ví Dụ Biên Soạn Đối Tượng Dịch Vụ

Giải Pháp Tự Động Hóa

Kịch Bản Cấp Dự Án

Quy Trình Biên Soạn

Tích Hợp Với Quy Trình Phát Triển

Trước Khi Tạo Mã

Kết Quả Đến Nay

Giới Hạn Hiện Tại

Bước Tiếp Theo: Vượt Qua CRUD

Thấu Hiểu Chính: Tài Liệu Như Giao Diện Mã

Bình luận