Vibe Coding Project Memory: Cách Dùng Git, AGENTS.md và AI_CONTEXT.md Để Không Mất Context

# Product
## Problem
Product Security team cần quản lý knowledge của ~100 hệ thống.
## Users
- Product Security Officer
- Product Security Lead
- Security Architect
## Core capabilities
1. Asset inventory
2. Security posture
3. Architecture knowledge
4. Risk tracking
5. AI Q&A
6. ASM validation
## Key questions system must answer
- Hệ thống này làm gì?
- Business owner là ai?
- Có bao nhiêu web/mobile/API?
- Authentication/authorization thế nào?
- Sensitive data là gì?
- Inbound/outbound integration?
- Risk hiện tại?

# AI Engineering Instructions
Before modifying code:
1. Read PRODUCT.md
2. Read ARCHITECTURE.md
3. Read DECISIONS.md
4. Inspect existing implementation
5. Do not redesign architecture unless necessary
Engineering rules:
- Do not hardcode secrets
- New API must have authentication
- Validate all external input
- Add tests for new functionality
- Database changes require migration
- Existing API compatibility must be preserved
Before finishing:
- Run tests
- Update documentation if architecture changes
- Update CHANGELOG.md
- Add architectural decisions to DECISIONS.md

docs/adr/
├── 001-use-postgresql.md
├── 002-use-vector-search.md
├── 003-use-keycloak.md
├── 004-multi-tenant-design.md
└── 005-asm-integration.md

# ADR-004 Multi Tenant Architecture
Status: Accepted
## Context
ASM platform cần phục vụ nhiều business unit.
## Decision
Use tenant_id at application and DB layer.
## Reason
- simpler operation
- lower infrastructure cost
- easier centralized management
## Rejected alternatives
Separate DB per tenant.
Reason:
Operational overhead too high.

Bạn đang đóng vai **Senior Software Architect + Product Engineer + Technical Documentation Owner**.
Tôi đang phát triển một sản phẩm theo phương pháp vibe coding. Tôi muốn toàn bộ kiến thức quan trọng của sản phẩm được lưu trong Git repository, thay vì phụ thuộc vào lịch sử conversation với AI.
Mục tiêu là:
- Tôi có thể chuyển dự án giữa ChatGPT, Claude, Gemini, Cursor, Codex hoặc local model.
- AI mới có thể đọc repository và nhanh chóng hiểu được sản phẩm.
- Kiến thức, quyết định kiến trúc, roadmap và trạng thái hiện tại của sản phẩm không bị mất.
- Conversation với AI KHÔNG được xem là source of truth.
- Repository phải là source of truth.
Hãy thực hiện các bước sau.
## 1. Phân tích toàn bộ repository
Đọc và phân tích:
- source code
- README hiện tại
- cấu trúc thư mục
- database schema
- migration
- API
- config
- Docker / deployment
- CI/CD
- test
- dependency
- authentication / authorization
- integration với hệ thống bên ngoài
- các file documentation hiện có
Không được giả định nếu có thể xác minh từ source code.
Nếu có điểm chưa xác định được, ghi rõ:
`UNKNOWN / NEED CONFIRMATION`
Không tự bịa thông tin.
---
## 2. Tạo Project Memory Pack
Tạo hoặc cập nhật cấu trúc:
```text
/
├── README.md
├── AI_CONTEXT.md
├── AGENTS.md
│
├── docs/
│   ├── PRODUCT.md
│   ├── ARCHITECTURE.md
│   ├── SECURITY.md
│   ├── DATA_MODEL.md
│   ├── API.md
│   ├── DEPLOYMENT.md
│   ├── ROADMAP.md
│   ├── DECISIONS.md
│   └── CHANGELOG.md
│
└── docs/adr/
```
Không tạo tài liệu cho có. Nội dung phải phản ánh đúng implementation thực tế.
---
# 3. Nội dung từng file
## AI_CONTEXT.md
Đây là entry point cho mọi AI model mới.
AI_CONTEXT.md phải giúp một AI chưa từng biết dự án có thể hiểu nhanh:
### Product
- sản phẩm là gì
- giải quyết vấn đề gì
- user chính
- use case chính
### Current State
- version hiện tại
- feature đã hoàn thành
- feature đang phát triển
- limitation hiện tại
- technical debt quan trọng
### Architecture
- technology stack
- các component chính
- data flow chính
- authentication
- authorization
- database
- external integration
### Important Decisions
Tóm tắt các quyết định kiến trúc quan trọng và link tới ADR tương ứng.
### Current Roadmap
- Now
- Next
- Later
### AI Instructions
Khi AI làm việc với repository này:
1. đọc AI_CONTEXT.md
2. đọc PRODUCT.md
3. đọc ARCHITECTURE.md
4. đọc các ADR liên quan
5. đọc AGENTS.md
6. kiểm tra implementation thực tế trước khi sửa code
AI_CONTEXT.md nên ngắn gọn, khoảng 2–5 phút đọc.
---
## PRODUCT.md
Mô tả sản phẩm từ góc nhìn Product.
Bao gồm:
- Product Vision
- Problem Statement
- Target Users
- Personas
- Core Use Cases
- Core Features
- Business Rules
- Out of Scope
- Product Constraints
- Success Metrics nếu xác định được
Phân biệt rõ:
- EXISTING
- PLANNED
- IDEA
Không mô tả planned feature như thể đã tồn tại.
---
## ARCHITECTURE.md
Mô tả kiến trúc hiện tại.
Bao gồm:
- System Context
- Technology Stack
- Components
- Component responsibilities
- Request flow
- Authentication flow
- Authorization model
- Data flow
- External integrations
- Background jobs
- Storage
- Cache
- Queue nếu có
- Deployment architecture
- Network boundaries
- Trust boundaries
Tạo Mermaid diagram nếu phù hợp.
Ví dụ:
```mermaid
flowchart LR
    User --> Frontend
    Frontend --> API
    API --> Database
    API --> ExternalService
```
Architecture phải phản ánh implementation hiện tại, không phải kiến trúc lý tưởng.
---
## SECURITY.md
Mô tả security architecture và security requirements.
Bao gồm:
- Authentication
- Authorization
- Session management
- Secret management
- Input validation
- API security
- Data protection
- Encryption
- Logging
- Audit logging
- Dependency security
- CI/CD security
- Security assumptions
- Trust boundaries
- Known security risks
- Security technical debt
Phân biệt:
- Implemented
- Partially Implemented
- Missing
- Planned
Không tuyên bố một security control tồn tại nếu source code không chứng minh được.
---
## DATA_MODEL.md
Mô tả:
- entities
- tables
- relationships
- important fields
- identifiers
- tenant model nếu có
- lifecycle của dữ liệu
- sensitive data
Tạo Mermaid ER diagram nếu phù hợp.
---
## API.md
Tổng hợp API hiện tại:
- method
- endpoint
- purpose
- authentication
- authorization
- input
- output
- important validation
- error handling
Không cần copy toàn bộ OpenAPI nếu đã tồn tại.
Link tới OpenAPI nếu có.
---
## DEPLOYMENT.md
Bao gồm:
- local development
- environment
- build
- deployment
- Docker
- infrastructure
- database migration
- rollback
- required environment variables
- observability
- backup nếu có
Không đưa secret thực vào tài liệu.
---
## ROADMAP.md
Sử dụng format:
# NOW
Những việc đang thực hiện.
# NEXT
Những việc dự kiến tiếp theo.
# LATER
Ý tưởng / enhancement dài hạn.
Mỗi item nên có:
- mục tiêu
- trạng thái
- dependency
- technical impact nếu đáng kể
Không suy diễn roadmap nếu repository không đủ thông tin.
---
## DECISIONS.md
Tạo danh sách các quyết định quan trọng:
| ID | Decision | Status | ADR |
|---|---|---|---|
Ví dụ:
```text
ADR-001 PostgreSQL as primary database
ADR-002 JWT authentication
ADR-003 Multi-tenant architecture
```
---
## docs/adr/
Với những quyết định kiến trúc quan trọng có thể suy ra rõ ràng từ hệ thống, tạo ADR.
Format:
```markdown
# ADR-XXX: Decision title
Status: Accepted
## Context
Vấn đề / constraint cần giải quyết.
## Decision
Quyết định đã được lựa chọn.
## Rationale
Tại sao lựa chọn này hợp lý.
## Consequences
### Positive
### Negative
## Alternatives
Các phương án khác nếu có bằng chứng.
## Evidence
Các file/source code chứng minh quyết định này.
```
Không bịa lý do lịch sử nếu không tìm thấy bằng chứng.
Nếu biết WHAT nhưng không biết WHY, ghi:
`Rationale: UNKNOWN – historical context not available.`
---
## AGENTS.md
Đây là instruction cho tất cả AI coding agent.
Bao gồm ít nhất:
```markdown
# AI Engineering Instructions
## Before making changes
1. Read AI_CONTEXT.md.
2. Read PRODUCT.md.
3. Read ARCHITECTURE.md.
4. Read relevant ADRs.
5. Inspect the existing implementation.
6. Do not assume documentation is newer than code.
7. If documentation and implementation conflict, identify the conflict before modifying the system.
## Engineering Principles
- Preserve existing architecture unless change is justified.
- Prefer incremental changes over unnecessary rewrites.
- Do not introduce new dependencies without a reason.
- Preserve backward compatibility unless explicitly instructed otherwise.
- Never hardcode secrets.
- Validate untrusted input.
- Follow existing authentication and authorization patterns.
- Database changes require migrations.
- New behavior should have tests where practical.
## Security
- Treat all external input as untrusted.
- Enforce authorization server-side.
- Do not expose secrets or sensitive information in logs.
- Do not weaken security controls merely to make implementation easier.
## Before finishing a task
1. Run relevant tests.
2. Review security impact.
3. Review backward compatibility.
4. Update documentation if behavior or architecture changed.
5. Update CHANGELOG.md.
6. Create/update ADR when an architectural decision is introduced.
7. Update AI_CONTEXT.md if the current state of the product changed materially.
```
Bổ sung các rule đặc thù của repository mà bạn phát hiện.
---
# 4. CHANGELOG.md
Không cố gắng dựng lại toàn bộ lịch sử nếu không đủ dữ liệu.
Tạo section:
```markdown
# Unreleased
## Added
## Changed
## Fixed
## Security
```
Nếu Git history cho phép xác định chính xác các thay đổi lớn trước đây thì có thể bổ sung.
---
# 5. Kiểm tra consistency
Sau khi tạo documentation, kiểm tra chéo:
- Documentation vs source code
- Architecture vs deployment
- API vs implementation
- Database vs migration
- Security documentation vs actual controls
- README vs cách chạy thực tế
Liệt kê các inconsistency phát hiện được.
Không âm thầm sửa implementation chỉ để khớp documentation.
---
# 6. Tạo Project Snapshot
Trong AI_CONTEXT.md thêm:
```markdown
## Project Snapshot
Last reviewed:
Current version:
Current branch:
Production status:
### Working
-
### In Progress
-
### Known Issues
-
### Technical Debt
-
### Next Recommended Work
-
```
Điền dựa trên bằng chứng tìm được.
---
# 7. Quy tắc chống hallucination
Rất quan trọng:
Không được biến suy đoán thành fact.
Sử dụng các nhãn:
- `CONFIRMED` — xác minh được từ repository
- `INFERRED` — suy ra hợp lý từ implementation
- `UNKNOWN` — chưa đủ thông tin
- `PLANNED` — dự kiến nhưng chưa implement
Đối với quyết định Product/Business không thể suy ra từ code, để UNKNOWN.
---
# 8. Sau khi hoàn thành
Cho tôi báo cáo ngắn:
### Repository understanding
Tóm tắt hệ thống trong tối đa 10 dòng.
### Files created
Danh sách file đã tạo.
### Files updated
Danh sách file đã cập nhật.
### Important findings
Những phát hiện quan trọng.
### Documentation gaps
Những thông tin cần tôi xác nhận.
### Architecture risks
Những điểm kiến trúc đáng chú ý.
### Security risks
Những vấn đề security đáng chú ý.
### Recommended next actions
Tối đa 10 việc ưu tiên tiếp theo.
Sau đó dừng lại.
Không tự redesign hoặc refactor sản phẩm trừ khi tôi yêu cầu.