Docs và artifact cạnh code

Tài liệu tách theo từng web app và đặt cạnh code; có khu riêng cho artifact UI. Lý do: sửa app nào thì docs của app ấy đi cùng commit, CI theo đường dẫn tự hiểu, và nếu sau này app tách repo thì docs đi theo.

Mỗi app có

<app>/
  CLAUDE.md        luật riêng của app, Claude Code nạp khi làm trong thư mục này
  docs/            PRD, SDD, runbook, quyết định UI, ảnh trước và sau
  design/
    prototypes/    bản nháp HTML/React, link claude.ai Artifact, link Figma (không vào build)
    assets.json    danh mục file nguồn và media trên R2: khoá, nguồn, giấy phép, ghi công
  public/          asset app thật sự dùng, nhỏ, đã tối ưu
  src/             code

Docs dùng chung (nền tảng, API, D1, design system) ở lại kho docs chung. Site harness này cũng theo luật ấy: nội dung nằm ngay trong harness.conan.school/.

Luồng nâng cấp UI

1. Làm prototype nhanh: claude.ai Artifact hoặc Figma.
2. Chủ dự án duyệt.
3. Phiên của làn app làm vào code.
4. Ảnh trước và sau, quyết định, ghi vào <app>/docs/.

Mỗi làn làm chủ thư mục design/ của app mình, nên các phiên không đụng nhau. File nặng của artifact (render, .blend, PSD) theo quy tắc lưu trữ: lên R2, không vào git.

Ở Conan hôm nay

Conan làm ngược lại: mọi tài liệu ở một cổng docs.conan.school/ (VitePress, 167 file), sidebar khai ở một file .vitepress/config.mts. Luật thường trực "cập nhật docs sau mọi yêu cầu" làm mọi phiên cùng sửa thư mục đó và file config đó: 495 file đổi trong 30 ngày tới 18.10.2026, đứng thứ ba toàn repo. Xem Audit.