Viết sách trên nền GitHub

Mục lục

1. 1. Bối cảnh và vấn đề đặt ra
2. 2. Khảo sát phương pháp
   • 2.1 Cấu trúc repo thay cho workspace
   • 2.2 Markdown làm định dạng viết chủ đạo
   • 2.3 Skills, agents và pipelines cùng nơi với bản thảo
   • 2.4 GitHub Actions compute chạy khi máy đã tắt
3. 3. Đánh giá tính đúng đắn
   • 3.1 Ưu điểm có thể kiểm chứng
   • 3.2 Hạn chế và rủi ro
   • 3.3 So sánh với các nền tảng hiện hành
4. 4. Chiến lược triển khai
   • 4.1 Thiết lập repo viết chuẩn
   • 4.2 Quy trình commit có kỷ luật
   • 4.3 Tích hợp AI agent
   • 4.4 Lộ trình theo giai đoạn
5. 5. Kết luận
6. Tài liệu tham khảo
7. Footnotes

---

1. Bối cảnh và vấn đề đặt ra

Người viết nghiêm túc thường đối mặt với ba vấn đề cốt lõi khi quản lý bản thảo dài hạn:

1. Kiểm soát lịch sử thay đổi biết chính xác cái gì đã sửa, khi nào, và tại sao.
2. Tính nhất quán của định dạng tránh entropy tích lũy qua nhiều lần chỉnh sửa trên nhiều thiết bị.
3. Tích hợp với công cụ AI đưa agent vào quy trình viết mà không phải "copy-paste qua lại giữa nhiều tab".¹

Các nền tảng phổ biến Word/OneDrive, Google Docs, Notion, Obsidian Sync giải quyết được một số nhưng không phải tất cả. Câu hỏi đặt ra: liệu một Git repository có thể là đơn vị làm việc tự nhiên hơn không?

---

2. Khảo sát phương pháp

2.1 Cấu trúc repo thay cho workspace

Thay vì "workspace" hay "database" như Notion, GitHub tổ chức công việc theo cây thư mục phẳng với version control tích hợp sẵn.

my-book/
├── CLAUDE.md              # Hướng dẫn cho AI agents
├── draft/
│   ├── chapter-01.md
│   ├── chapter-02.md
│   └── chapter-03.md
├── references/
│   └── sources.md
├── clauses/               # Với research pháp luật
│   └── dieu-khoan-*.md
├── .claude/
│   ├── skills/
│   │   ├── legal-currency/SKILL.md
│   │   └── citation-check/SKILL.md
│   └── agents/
│       ├── fact-checker.md
│       └── proofreader.md
└── pipelines/
    └── full-draft.yml

Sức mạnh cốt lõi là git diff không chỉ "file này được sửa hôm thứ Ba" mà là xem chính xác câu nào bị xóa, câu nào được thêm vào.¹

2.2 Markdown làm định dạng viết chủ đạo

Markdown do John Gruber phát hành năm 2004.² Cú pháp tối giản:

Cú pháp	Kết quả
# Heading	Tiêu đề cấp 1
**text**	Chữ đậm
- item	Bullet list
[text](url)	Hyperlink
> quote	Blockquote

Lý do Markdown bền hơn .docx:

• Plaintext đọc được trên bất kỳ editor nào, kể cả cat trong terminal
• Không bị lỗi font hay formatting khi chuyển máy
• File nhỏ không "nặng hàng chục MB chỉ vì chèn một logo"¹
• Portability: VS Code, github.dev (nhấn . trên bàn phím khi xem repo), GitHub Mobile, Obsidian đều đọc được

2.3 Skills, agents và pipelines cùng nơi với bản thảo

Đây là điểm khác biệt kiến trúc quan trọng nhất so với các nền tảng khác.

Trong một repo viết, có thể đặt chung:

• Bản thảo draft.md, references/*.md
• Hướng dẫn agent CLAUDE.md hoặc AGENTS.md ở gốc repo. Nhiều công cụ AI đọc được: Claude Code, OpenAI Codex, GitHub Copilot, Cursor, Factory, Amp, Jules¹
• Skills .claude/skills/ mỗi sub-folder là một quy trình đóng gói: kiểm tra trích dẫn luật, rà legal currency, chỉnh dịch thuật
• Subagents .claude/agents/ fact-checker, legal-currency, proofreader, translation-reviewer
• Pipelines pipelines/ workflow tuần tự: Intake → Draft → Self-review → Proof → Compile

Cơ chế hoạt động:

graph LR
    A[Lệnh của người dùng] --> B[Agent đọc CLAUDE.md]
    B --> C[Agent gọi SKILL.md phù hợp]
    C --> D[Pipeline chạy]
    D --> E[Output ghi vào draft.md]
    E --> F[git commit → history]

2.4 GitHub Actions compute chạy khi máy đã tắt

GitHub Actions là một compute runtime đặt ngay bên cạnh file, kích hoạt bởi:

• push commit hoặc mở PR
• Comment chứa @claude
• Cron schedule (ví dụ: 6h sáng mỗi ngày)
• Trigger thủ công qua "Run workflow"

Tam giác độc lập:

GitHub Runner ←→ Anthropic API
        ↑
   Git Repo (cloud)
        
≠ laptop của người dùng

Ba thành phần này hoạt động độc lập với thiết bị cá nhân.¹ Agent có thể tiếp tục làm việc trên bản thảo khi tác giả đang trên máy bay.

---

3. Đánh giá tính đúng đắn

3.1 Ưu điểm có thể kiểm chứng

Về version control:

• git diff cung cấp line-level tracking mà không nền tảng văn phòng nào có natively
• Commit message là audit trail có cấu trúc: biết ai sửa gì khi nào vì sao
• Branch cho phép thử nghiệm song song mà không ảnh hưởng bản thảo chính

Về tính bền của định dạng:

• .md là open standard, không bị vendor lock-in
• Obsidian, Typora, VS Code, iA Writer, Zettlr đều đọc cùng một file
• Không có "file bị corrupt" kiểu .docx

Về tích hợp AI:

• CLAUDE.md là giao thức chuẩn mà nhiều AI tool đã hỗ trợ
• Context nằm trong repo không cần upload/copy-paste sang tool khác
• GitHub Actions cho phép automation thực sự, không chỉ "gợi ý"

3.2 Hạn chế và rủi ro

Learning curve:

• Git có khái niệm riêng (commit, branch, merge, rebase) cần thời gian làm quen
• Conflict resolution khi nhiều người cùng sửa một file là phức tạp hơn Google Docs

Thiếu WYSIWYG:

• Người quen Word/Google Docs sẽ thấy thiếu real-time formatting
• Mặc dù github.dev và Obsidian giải quyết phần lớn vấn đề này

Collaboration với người không dùng Git:

• Khó chia sẻ với đồng nghiệp dùng Word
• Không có tính năng comment/suggestion kiểu Google Docs natively

Chi phí ẩn:

• GitHub Actions có giới hạn free tier (2,000 phút/tháng cho private repo)
• Cần setup ban đầu tốn thời gian

3.3 So sánh với các nền tảng hiện hành

Tiêu chí	GitHub + MD	Google Docs	Notion	Obsidian Sync	Word/OneDrive
Line-level diff	✅	❌	❌	❌	❌
Offline hoàn toàn	✅	⚠️	⚠️	✅	✅
AI agent integration	✅✅	⚠️	⚠️	⚠️	❌
Compute automation	✅	❌	❌	❌	❌
WYSIWYG	❌	✅	✅	✅	✅
Real-time collab	⚠️	✅	✅	❌	✅
Vendor lock-in	Thấp	Cao	Cao	Thấp	Cao
Learning curve	Cao	Thấp	Trung bình	Trung bình	Thấp
Chi phí	Thấp	Thấp	Trung bình	Trung bình	Cao

Kết luận so sánh: GitHub không phải lựa chọn tốt nhất cho mọi loại viết lách. Nó tối ưu cho người viết dài hạn, nghiêm túc, cần audit trail và AI integration. Không phải cho note nhanh hay cộng tác với người không dùng Git.

---

4. Chiến lược triển khai

4.1 Thiết lập repo viết chuẩn

Bước 1 Khởi tạo cấu trúc:

mkdir my-writing-project && cd my-writing-project
git init
mkdir -p draft references .claude/skills .claude/agents pipelines

Bước 2 Tạo CLAUDE.md ở gốc repo:

# Hướng dẫn cho AI Agents

## Ngữ cảnh dự án
[Mô tả ngắn về dự án viết]

## Conventions
- Tất cả file viết ở định dạng `.md`
- Trích dẫn theo chuẩn [tên chuẩn]
- Commit message theo format: `type(scope): description`

## Skills có sẵn
- `.claude/skills/citation-check/`  kiểm tra trích dẫn
- `.claude/skills/proofreader/`  rà soát văn phong

Bước 3 .gitignore phù hợp:

.DS_Store
*.tmp
node_modules/
.obsidian/workspace.json

4.2 Quy trình commit có kỷ luật

Commit message nên có cấu trúc để git log thành audit trail có ý nghĩa:

feat(chapter-2): thêm phần phân tích điều 15 khoản 3
fix(references): cập nhật trích dẫn Nghị định 13/2023
refactor(intro): viết lại đoạn mở đầu theo góc độ thực tiễn
review(chapter-1): tích hợp feedback từ lần đọc thứ hai

4.3 Tích hợp AI agent

Pattern cơ bản với Claude Code:

1. Mở terminal tại thư mục repo
2. Chạy claude (Claude Code CLI)
3. Agent tự đọc CLAUDE.md và hiểu context
4. Ra lệnh bằng ngôn ngữ tự nhiên: "Rà soát chapter-02.md theo skill proofreader, tập trung vào tính nhất quán thuật ngữ pháp lý"

Pattern nâng cao với GitHub Actions:

# .github/workflows/nightly-review.yml
name: Nightly AI Review
on:
  schedule:
    - cron: '0 23 * * *'  # 6h sáng GMT+7
jobs:
  review:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Run AI proofreader
        run: |
          # Gọi Anthropic API, output vào review/nightly-$(date).md
          # Commit kết quả vào repo

4.4 Lộ trình theo giai đoạn

Giai đoạn 1 Foundation (Tuần 1–2):

• Tạo repo, viết README.md và CLAUDE.md cơ bản
• Chuyển bản thảo hiện tại sang .md
• Thiết lập Obsidian đọc từ repo (nếu dùng Obsidian)
• Commit đều đặn, tập viết commit message có nghĩa

Giai đoạn 2 Skills (Tuần 3–4):

• Tạo skill đầu tiên (ví dụ: citation-check)
• Thử Claude Code với skill đó trên một chapter
• Đánh giá output, tinh chỉnh SKILL.md

Giai đoạn 3 Pipelines (Tháng 2):

• Thiết lập pipeline Proof → Compile đơn giản
• Thêm subagent fact-checker nếu cần
• Cân nhắc GitHub Actions cho automation

Giai đoạn 4 Optimization (Tháng 3+):

• Review và refactor skills dựa trên thực tế dùng
• Thêm nightly review workflow nếu hữu ích
• Chia sẻ/publish repo nếu phù hợp (có thể để private)

---

5. Kết luận

Luận điểm trung tâm của phương pháp này: khi AI trở thành đồng tác giả mặc định trong công việc viết nghiêm túc, đơn vị làm việc tự nhiên sẽ không còn là "document" mà là "repo".¹

Đánh giá của note này:

• Tính đúng đắn về kỹ thuật: Cao. Các lợi thế về diff, version control, và AI integration là thực chất, không phải lý thuyết.
• Tính phổ quát: Trung bình. Phù hợp với người viết kỹ thuật và nghiên cứu; ít phù hợp với người viết sáng tạo thuần túy hoặc môi trường cộng tác hỗn hợp.
• Rủi ro triển khai: Thấp–Trung bình. Git learning curve là rào cản thực, nhưng có thể vượt qua trong 1–2 tuần với practice có chủ đích.

Khuyến nghị: Thử nghiệm với một dự án viết cụ thể, không phải toàn bộ workflow. Đánh giá sau 4 tuần dùng thực tế trước khi quyết định migrate hoàn toàn.

---

Tài liệu tham khảo

Footnotes

1. Hoang Tran (2026,). Tôi viết sách trên GitHub, chứ không phải Word Facebook ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

2. Gruber, J. (2004). Markdown. Daring Fireball. https://daringfireball.net/projects/markdown/ ↩