Markdown: Định dạng mới cho thời AI và Oracle APEX

Khi AI ngày càng tham gia sâu vào quá trình phát triển phần mềm, cách chúng ta viết tài liệu, mô tả yêu cầu, ghi chú kỹ thuật và chuẩn hóa thông tin cũng cần thay đổi.

Trước đây, nhiều team thường dùng Word, Excel, PowerPoint, email, chat hoặc ticket để mô tả yêu cầu. Các định dạng này vẫn hữu ích cho con người, nhưng không phải lúc nào cũng thuận lợi cho AI. AI cần dữ liệu sạch, có cấu trúc, ít nhiễu và dễ chia nhỏ thành từng phần có ý nghĩa.

Đây là lý do Markdown trở nên rất quan trọng trong thời AI. Markdown đủ đơn giản để business analyst, developer, tester và product owner đều có thể viết. Đồng thời, nó đủ cấu trúc để AI hiểu heading, list, table, code block, checklist, requirement, rule, acceptance criteria và workflow.

Markdown là gì?

Markdown là một định dạng văn bản nhẹ, dùng ký hiệu đơn giản để mô tả cấu trúc tài liệu. Ví dụ:

# Tiêu đề lớn

## Tiêu đề phụ

- Gạch đầu dòng 1
- Gạch đầu dòng 2

| Cột 1 | Cột 2 |
|------|------|
| A    | B    |

```sql
select *
from customers;
```

Điểm mạnh của Markdown là bạn có thể đọc nó như plain text, nhưng vẫn có cấu trúc rõ ràng để render thành HTML, PDF, slide, tài liệu kỹ thuật, hoặc đưa vào AI prompt.

Với con người, Markdown dễ viết. Với AI, Markdown dễ phân tích. Đây chính là điểm làm Markdown trở thành định dạng rất phù hợp cho thời AI.

Vì sao AI thích Markdown?

AI không thật sự cần tài liệu đẹp mắt theo kiểu Word hoặc PowerPoint. AI cần nội dung rõ nghĩa và có cấu trúc.

Markdown giúp AI hiểu tài liệu tốt hơn vì:

• Heading cho biết ranh giới từng chủ đề.
• List cho biết các ý cùng nhóm.
• Nested list cho biết quan hệ cha con.
• Table cho biết dữ liệu so sánh hoặc mapping.
• Code block tách code ra khỏi văn bản thường.
• Checklist cho biết trạng thái hoàn thành hoặc điều kiện kiểm tra.

Nếu bạn đưa cho AI một đoạn văn dài không có cấu trúc, AI vẫn có thể hiểu, nhưng dễ bỏ sót ý, hiểu sai ranh giới hoặc trộn lẫn requirement với ghi chú.

Nếu bạn đưa cùng nội dung đó dưới dạng Markdown có heading, list và table, AI có nhiều tín hiệu hơn để phân tích đúng.

Lược đồ Markdown trong workflow AI

Vấn đề của tài liệu truyền thống trong AI workflow

Word, PDF, slide deck và email vẫn rất phổ biến trong doanh nghiệp. Nhưng khi dùng với AI, chúng có một số nhược điểm:

• Có nhiều thông tin trình bày nhưng ít cấu trúc logic rõ ràng.
• Nội dung bị trộn với layout, font, màu sắc, header, footer.
• Khó diff khi đưa vào Git.
• Khó biết phần nào là requirement, phần nào là ghi chú.
• Dữ liệu bảng có thể bị mất cấu trúc khi copy/paste.
• AI có thể đọc được, nhưng thường phải xử lý nhiều nhiễu hơn.

Ví dụ, một file Word mô tả chức năng có thể có hình ảnh, bảng, màu, comment, track changes và nhiều định dạng phức tạp. Con người nhìn thì thấy đẹp, nhưng AI có thể chỉ cần phần nội dung thật: yêu cầu, rule, input, output, exception và acceptance criteria.

Markdown giúp giảm nhiễu này. Nó tập trung vào nội dung và cấu trúc, không tập trung vào trang trí.

Markdown không thay thế tất cả định dạng khác

Không nên hiểu rằng Markdown sẽ thay thế hoàn toàn Word, Excel, PowerPoint hoặc PDF. Mỗi định dạng có vai trò riêng.

Word vẫn hữu ích cho tài liệu chính thức cần định dạng đẹp. Excel vẫn mạnh cho dữ liệu bảng và tính toán. PowerPoint vẫn phù hợp cho trình bày. PDF vẫn tốt cho tài liệu cố định không muốn bị chỉnh sửa.

Nhưng trong workflow AI, Markdown rất phù hợp làm định dạng nguồn. Từ Markdown, bạn có thể tạo ra nhiều output khác:

• Tài liệu HTML.
• PDF.
• Slide deck.
• Prompt template.
• Test case.
• APEX Blueprint.
• Technical design.
• Release notes.

Nói cách khác, Markdown nên được xem là định dạng authoring, còn các định dạng khác có thể là định dạng xuất bản.

Markdown và Oracle APEX

Với Oracle APEX developer, Markdown đặc biệt hữu ích vì APEX vốn xoay quanh metadata, cấu hình khai báo, page definition, SQL, PL/SQL, workflow, validation và business rule.

Một ứng dụng APEX thường bắt đầu từ các nội dung như:

• Mô tả ứng dụng.
• Danh sách role.
• Danh sách page.
• Data model.
• Business rules.
• Validation rules.
• Report requirements.
• Workflow approval.
• Security matrix.
• Acceptance criteria.

Đây đều là những thứ có thể mô tả rất tốt bằng Markdown.

Khi các nội dung này nằm trong Markdown, AI có thể đọc và hỗ trợ tạo:

• DDL cho tables/views.
• PL/SQL package skeleton.
• APEX page outline.
• Validation checklist.
• Test scenarios.
• User stories.
• Technical documentation.
• Prompt cho AI agent.

Markdown và APEXlang/APEX Blueprints

Với định hướng APEX mới, đặc biệt là APEXlang và các ý tưởng blueprint/spec-driven development, Markdown càng trở nên đáng chú ý.

Một blueprint tốt không chỉ là vài câu mô tả chung chung. Nó cần có cấu trúc:

• Ứng dụng này giải quyết vấn đề gì?
• Người dùng gồm những nhóm nào?
• Dữ liệu chính là gì?
• Các page cần có là gì?
• Luồng nghiệp vụ diễn ra như thế nào?
• Quy tắc validation là gì?
• Phân quyền ra sao?
• Khi nào xem là hoàn thành?

Markdown là định dạng rất phù hợp để mô tả những phần này. Nó không quá nặng như tài liệu truyền thống, nhưng cũng không quá tự do như một đoạn chat dài.

Ví dụ Markdown spec cho một app APEX

Một spec đơn giản có thể viết như sau:

# Expense Approval App

## Goal

Xây dựng ứng dụng quản lý đề nghị thanh toán nội bộ.

## Users

| Role | Description |
|------|-------------|
| Employee | Tạo đề nghị thanh toán |
| Manager | Phê duyệt đề nghị của nhân viên |
| Finance | Kiểm tra và đánh dấu đã thanh toán |

## Main Tables

- EXPENSE_REQUESTS
- EXPENSE_LINES
- EXPENSE_ATTACHMENTS
- APPROVAL_HISTORY

## Pages

### Dashboard

- Hiển thị số request theo trạng thái
- Hiển thị request đang chờ tôi xử lý

### Create Request

- Employee nhập header
- Employee nhập nhiều dòng chi phí
- Cho phép upload hóa đơn

## Business Rules

- Tổng tiền trên 10 triệu phải có Manager approval
- Request đã paid thì không được sửa
- Finance chỉ xử lý request đã approved

## Acceptance Criteria

- Employee tạo được request mới
- Manager approve/reject được request
- Finance đánh dấu paid được request
- User chỉ thấy dữ liệu theo quyền

Với cấu trúc như vậy, AI có thể hiểu rõ hơn nhiều so với một đoạn văn dài. Developer cũng dễ review và chỉnh sửa hơn.

Markdown giúp Git diff dễ hơn

Một lợi ích rất lớn của Markdown là dễ đưa vào Git.

Nếu requirement nằm trong file Word, việc review thay đổi qua Git rất khó. Nhưng nếu requirement nằm trong file Markdown, bạn có thể thấy rõ:

• Dòng nào được thêm.
• Dòng nào bị xóa.
• Rule nào thay đổi.
• Acceptance criteria nào được cập nhật.
• Page nào được bổ sung.

Điều này đặc biệt quan trọng khi AI tham gia vào quá trình tạo hoặc chỉnh tài liệu. Bạn cần biết AI đã thay đổi gì. Markdown + Git giúp review AI output dễ hơn nhiều.

Markdown giúp giảm token và giảm nhiễu

Khi làm việc với AI, token là tài nguyên quan trọng. Một tài liệu quá nhiều định dạng, comment, layout hoặc metadata dư thừa sẽ làm tăng lượng token mà không tăng nhiều giá trị.

Markdown giúp input gọn hơn:

• Ít formatting noise.
• Ít thông tin layout không cần thiết.
• Cấu trúc rõ nhưng vẫn nhẹ.
• Dễ chunk theo heading.
• Dễ nhúng vào prompt hoặc retrieval system.

Với RAG, knowledge base hoặc agent memory, Markdown cũng rất phù hợp. Bạn có thể chia tài liệu theo heading, giữ nguyên code block, table và checklist.

Markdown giúp prompt engineering có kỷ luật hơn

Nhiều người viết prompt theo kiểu một đoạn văn dài. Cách đó có thể dùng được, nhưng khó tái sử dụng và khó kiểm soát.

Prompt viết bằng Markdown có thể rõ hơn:

# Task

Bạn là Oracle APEX developer. Hãy tạo thiết kế cho module quản lý chi phí.

## Context

Ứng dụng dùng Oracle APEX, PL/SQL packages và bảng EXPENSE_REQUESTS.

## Requirements

- Nhân viên tạo request
- Manager approve hoặc reject
- Finance đánh dấu paid

## Constraints

- Không hard-code role trong page process
- Business logic phải nằm trong package
- Mọi thay đổi trạng thái phải ghi audit log

## Output Format

- Data model
- Page list
- PL/SQL package outline
- Test cases

Prompt này dễ đọc, dễ chỉnh, dễ lưu lại và dễ dùng lại hơn. AI cũng hiểu ranh giới giữa task, context, requirement, constraint và output format.

Markdown cho BA và Product Owner

Markdown không chỉ dành cho developer. Business Analyst và Product Owner cũng có thể dùng Markdown để viết requirement rõ hơn.

Ví dụ một user story:

# User Story: Approve Expense Request

## As a

Manager

## I want to

Approve or reject expense requests from my team.

## So that

Finance can process only validated requests.

## Rules

- Manager can only approve requests from their team
- Request over 10 million requires second approval
- Rejected request must have a reason

## Acceptance Criteria

- Given I am a manager
- When I open the approval queue
- Then I only see requests from my team

- Given I reject a request
- When I do not enter a reason
- Then the system shows validation error

Đây là định dạng rất dễ cho AI chuyển thành test cases, validation rules, APEX page design hoặc PL/SQL package outline.

Markdown cho technical design

Developer có thể dùng Markdown để viết technical design ngắn gọn nhưng rõ ràng.

# Technical Design: Expense Approval

## Tables

- EXPENSE_REQUESTS
- EXPENSE_LINES
- EXPENSE_AUDIT_LOG

## Packages

- EXPENSE_REQUEST_PKG
- EXPENSE_APPROVAL_PKG
- EXPENSE_SECURITY_PKG

## Security

- APP_USER maps to APP_USERS.USERNAME
- Role is checked by EXPENSE_SECURITY_PKG
- Page authorization uses server-side checks

## State Transitions

| From | Action | To |
|------|--------|----|
| DRAFT | Submit | SUBMITTED |
| SUBMITTED | Approve | APPROVED |
| SUBMITTED | Reject | REJECTED |
| APPROVED | Mark Paid | PAID |

## Error Handling

- Invalid transition raises -20001
- Unauthorized action raises -20002
- All state changes write audit log

Đây là loại tài liệu vừa hữu ích cho team, vừa rất hữu ích cho AI khi cần sinh code hoặc review logic.

Markdown cho test cases

Test cases cũng có thể viết bằng Markdown:

# Test Cases: Expense Approval

## TC01 - Employee creates draft request

### Steps

1. Login as EMPLOYEE01
2. Open Create Request page
3. Enter header information
4. Add two expense lines
5. Click Save Draft

### Expected Result

- Request is created with status DRAFT
- Expense lines are saved
- Audit log has CREATE_DRAFT entry

## TC02 - Manager rejects without reason

### Steps

1. Login as MANAGER01
2. Open Approval Queue
3. Select a submitted request
4. Click Reject without reason

### Expected Result

- System shows validation error
- Request status remains SUBMITTED

AI có thể dùng test cases này để tạo checklist, test script, regression plan hoặc automation draft.

Markdown cho AI Agents và Skills

Khi bạn xây AI Agent, Markdown rất phù hợp để viết hướng dẫn cho agent.

Ví dụ file hướng dẫn:

# Agent Rules

## Scope

Agent hỗ trợ người dùng tạo, tìm kiếm và cập nhật task trong hệ thống nội bộ.

## Allowed Actions

- Create task
- List task
- Update task status
- Summarize overdue task

## Not Allowed

- Delete task
- Change task owner without approval
- Access financial data

## Tool Usage

- Use task_api.create_task for creating task
- Use task_api.search_tasks for searching
- Use task_api.update_status for status update

## Response Style

- Trả lời ngắn gọn
- Không hiển thị raw JSON
- Luôn nêu rõ task id sau khi tạo

Markdown ở đây đóng vai trò như một lớp instruction dễ đọc, dễ version control, và dễ cập nhật khi business rule thay đổi.

Markdown và tài liệu trong repository

Một repository APEX/PLSQL hiện đại có thể tổ chức như sau:

docs/
  requirements.md
  technical-design.md
  security-model.md
  test-cases.md
  release-notes.md

src/
  database/
    tables/
    views/
    packages/
  apex/
    application.apx

agents/
  AGENTS.md
  second-brain-skill.md
  support-ticket-skill.md

Cách tổ chức này giúp developer, AI assistant và team cùng làm việc trên một nguồn tài liệu rõ ràng.

Khi AI cần hiểu dự án, bạn có thể chỉ nó đọc các file Markdown quan trọng trước. Khi AI tạo output, bạn yêu cầu nó cập nhật lại đúng file Markdown thay vì trả lời rời rạc trong chat.

Markdown không tự đảm bảo chất lượng

Dù Markdown rất hữu ích, nó không tự làm tài liệu trở nên tốt. Một file Markdown lộn xộn vẫn là tài liệu lộn xộn.

Để Markdown phát huy giá trị, team cần thống nhất cấu trúc.

Ví dụ, mỗi requirement nên có:

• Goal.
• Users/Roles.
• Data model.
• Pages.
• Business rules.
• Validation rules.
• Security rules.
• Acceptance criteria.
• Open questions.

Nếu mỗi người viết một kiểu, AI vẫn sẽ phải đoán nhiều. Markdown tốt nhất khi có template.

Template Markdown cho yêu cầu APEX

Bạn có thể dùng template sau cho các module APEX:

# Module Name

## Goal

Mô tả mục tiêu của module.

## Users and Roles

| Role | Permission |
|------|------------|
|      |            |

## Data Objects

- Table/View 1
- Table/View 2

## Pages

### Page 1: Name

- Purpose:
- Regions:
- Items:
- Buttons:
- Processes:
- Validations:

## Business Rules

- Rule 1
- Rule 2

## Security Rules

- Rule 1
- Rule 2

## Acceptance Criteria

- Criteria 1
- Criteria 2

## Open Questions

- Question 1
- Question 2

Khi dùng template này đều đặn, AI có thể xử lý tài liệu ổn định hơn. Developer cũng dễ review hơn.

Markdown giúp giao tiếp giữa BA và Developer tốt hơn

Một vấn đề thường gặp là BA viết yêu cầu theo ngôn ngữ nghiệp vụ, developer lại cần chuyển thành bảng, page, validation, process và test.

Markdown có thể làm cầu nối:

• BA viết requirement bằng Markdown template.
• AI hỗ trợ chuyển requirement thành technical outline.
• Developer review và chỉnh lại.
• AI tiếp tục hỗ trợ tạo SQL, PL/SQL hoặc APEX blueprint.
• Tester dùng acceptance criteria để tạo test cases.

Nhờ vậy, Markdown không chỉ là định dạng tài liệu. Nó trở thành format trung gian giữa nghiệp vụ, kỹ thuật và AI.

Markdown cho slide và tài liệu đào tạo

Ngoài requirement và technical design, Markdown cũng rất hữu ích cho tài liệu đào tạo. Một số công cụ có thể chuyển Markdown thành slide, PDF hoặc HTML.

Ví dụ nội dung bài học có thể viết:

# Oracle APEX Debugging

## Mục tiêu bài học

- Hiểu APEX_DEBUG
- Biết xem Debug Messages
- Biết debug Dynamic Action

## Nội dung

1. Bật Debug
2. Ghi log bằng APEX_DEBUG.MESSAGE
3. Kiểm tra Session State
4. Debug Performance

## Bài tập

- Tạo process có lỗi
- Bật debug
- Tìm lỗi trong Debug Messages

Từ một file Markdown, bạn có thể dùng AI để tạo:

• Bài học chi tiết.
• Slide trình bày.
• Quiz.
• Checklist thực hành.
• Bài post mạng xã hội.

Những lỗi thường gặp khi dùng Markdown với AI

Một số lỗi phổ biến:

• Viết heading không rõ nghĩa.
• Trộn requirement, solution và ghi chú vào cùng một đoạn.
• Không dùng table cho dữ liệu mapping.
• Không dùng code block cho SQL/PLSQL/JSON.
• Viết checklist nhưng không ghi trạng thái rõ.
• File quá dài nhưng không chia section.
• Không có template thống nhất giữa các module.
• Không version control tài liệu Markdown.

Các lỗi này làm AI phải suy luận nhiều hơn và tăng khả năng hiểu sai.

Best practice khi viết Markdown cho AI

• Dùng heading rõ ràng và nhất quán.
• Mỗi section chỉ nên nói một nhóm ý chính.
• Dùng bullet list cho rule và requirement.
• Dùng table cho mapping, role, trạng thái và so sánh.
• Dùng code block cho SQL, PL/SQL, JSON, prompt và command.
• Dùng checklist cho tiêu chí hoàn thành.
• Viết rõ constraint và non-goals.
• Tách business rule khỏi technical solution.
• Giữ file trong Git để review thay đổi.
• Dùng template cho các loại tài liệu lặp lại.

Checklist chuyển tài liệu hiện tại sang Markdown

Nếu bạn đang có tài liệu trong Word, email hoặc slide, có thể chuyển dần sang Markdown theo checklist:

1. Tách từng module hoặc chủ đề thành file riêng.
2. Đặt heading rõ ràng.
3. Chuyển rule thành bullet list.
4. Chuyển role/permission thành table.
5. Đưa SQL/JSON/code vào code block.
6. Tách open questions thành section riêng.
7. Thêm acceptance criteria.
8. Commit vào Git.
9. Yêu cầu AI review xem tài liệu còn mơ hồ không.
10. Cập nhật template để dùng cho module sau.

Khi nào không nên dùng Markdown?

Markdown không phải lựa chọn tốt nhất cho mọi thứ. Không nên ép Markdown cho các trường hợp:

• Bảng tính phức tạp có công thức nhiều lớp.
• Tài liệu cần layout in ấn chính xác.
• Biểu mẫu pháp lý cần định dạng cố định.
• Thiết kế UI cần mockup hình ảnh chi tiết.
• Sơ đồ phức tạp cần công cụ diagram chuyên dụng.

Tuy nhiên, ngay cả trong các trường hợp này, Markdown vẫn có thể dùng làm phần mô tả, giải thích, requirement hoặc metadata đi kèm.

Markdown như “ngôn ngữ trung gian” của AI workflow

Có thể xem Markdown như một ngôn ngữ trung gian giữa con người và AI. Nó vẫn là ngôn ngữ tự nhiên, nhưng có thêm cấu trúc.

Con người đọc được. AI đọc được. Git diff được. Công cụ build chuyển đổi được. Repository lưu trữ được.

Đây là lý do Markdown ngày càng quan trọng trong workflow hiện đại, đặc biệt với các team đang dùng AI để viết code, tạo tài liệu, phân tích yêu cầu, sinh test cases, tạo agent instructions hoặc chuẩn bị APEX Blueprints.

Kết luận

AI đang làm thay đổi cách chúng ta mô tả và xây dựng phần mềm. Trong thế giới đó, ngôn ngữ tự nhiên trở thành một phần quan trọng của quy trình phát triển. Nhưng ngôn ngữ tự nhiên nếu không có cấu trúc sẽ dễ mơ hồ, khó lặp lại và khó kiểm soát.

Markdown là một giải pháp rất thực tế. Nó không phức tạp như code, không nặng như tài liệu truyền thống, nhưng đủ cấu trúc để AI hiểu và đủ đơn giản để con người dùng hằng ngày.

Với Oracle APEX developer, Markdown có thể dùng cho requirement, technical design, APEX Blueprints, APEXlang workflow, test cases, agent instructions, AI Skills, release notes và tài liệu đào tạo.

Nếu AI là lớp tăng tốc mới trong phát triển phần mềm, thì Markdown rất có thể sẽ trở thành một trong những định dạng nền tảng để con người, developer và AI cùng làm việc trên một nguồn thông tin rõ ràng hơn.