Cấu trúc Repo SDD

Không cần copy y nguyên, nhưng nên giữ ý tưởng cốt lõi: spec, code và test SOI CHIẾU được nhau - cùng một nhịp thư mục. Nhờ vậy con người truy ngược dễ (Traceable) và AI lấy context dễ hơn.

Layout gợi ý

project-root/
├── /specs                       ← source of truth nghiệp vụ
│   ├── /business-requirements    (BR-001-hr-tool.md)
│   ├── /use-cases
│   │    ├── /checkout-context    (UC-042-place-order-qr.md)
│   │    ├── /shipping-context
│   │    └── _legacy
│   ├── /entities                 (checkout-context.md)
│   └── /diagrams                 (use-cases.puml, architecture.puml)
├── /docs
│   ├── /adr                      (001-chose-postgres.md)
│   ├── runbooks/  └── onboarding.md
├── /src
│   ├── /use-cases  ├── /domain  ├── /ports  └── /adapters
└── /tests
    ├── /use-cases                (checkout/place-order-qr/AC-1.test.ts)
    └── /characterization

Khi PR đụng UC-042, reviewer biết cần xem đúng 3 chỗ: /specs/.../UC-042.md, /src/.../place-order-qr/, /tests/.../place-order-qr/.

Lớp OpenSpec (tuỳ chọn)

Nếu thích mô hình Spec hiện tại và Spec thay đổi:

openspec/
├── specs/       ← baseline: hệ thống hiện tại phải hành xử thế nào
├── changes/     ← mỗi thay đổi một folder (proposal/specs/design/tasks)
│    └── archive/
└── config.yaml

Không phải team nào cũng cần đúng layout này, nhưng cách nghĩ phía sau đáng lấy: spec chính mô tả hiện tại, thay đổi mới sống trong change folder cho tới khi review + archive.

Liên quan

• Traceable - mục đích của việc soi chiếu thư mục
• Hexagonal Architecture - src chia domain/ports/adapters
• Spec hiện tại và Spec thay đổi - lớp openspec/
• Bounded Context - thư mục chia theo context