Tên thư mục không phải là danh tính của dự án

Đường dẫn thư mục là một lộ trình. Nó cho công cụ biết dự án hiện đang nằm ở đâu. Danh tính dự án thì khác.

Danh tính phải duy trì được qua những thay đổi phổ biến sau:

  • Đổi tên thư mục
  • Di chuyển dự án giữa các máy tính
  • Clone repo vào một đường dẫn mới
  • Sử dụng nhiều bản checkout của cùng một dự án

Nếu danh tính phụ thuộc vào đường dẫn, những hành động này sẽ trở nên rủi ro. Đường dẫn có thể vẫn hoạt động, nhưng nó không chứng minh được dự án vẫn là dự án đó. Điều này khiến nó trở thành một "khóa" (key) tồi để lưu trữ trạng thái (state).

Tôi sử dụng thiết kế tách biệt với APC và APX để giải quyết vấn đề này.

APC xử lý hợp đồng dự án (project contract). Nó nằm trong repository. APX xử lý trạng thái runtime. Nó nằm ngoài repository.

APC sử dụng các tệp cụ thể để tạo ra một điểm neo (anchor) ổn định:

  • AGENTS.md cho hợp đồng gốc (root contract)
  • .apc/project.json cho metadata của dự án
  • .apc/agents/*.md cho các định nghĩa agent
  • .apc/mcps.json cho các gợi ý MCP

Tệp .apc/project.json rất nhỏ. Nó chứa một cái tên và một ID ổn định. Nó là một dấu mốc (marker), không phải là một tệp cấu hình lớn.

APX sử dụng tệp này để kết nối một bản checkout đang chạy với một bản ghi bền vững. Đường dẫn giúp APX tìm thấy dự án. Metadata giúp APX giữ cho dự án ổn định sau khi đã tìm thấy.

Thiết kế này giúp repo luôn sạch sẽ. Dữ liệu runtime như nhật ký phiên (session logs) và lịch sử tin nhắn sẽ nằm trong bộ lưu trữ của APX. Chúng không làm rác lịch sử git của bạn.

Khi bạn dựa vào đường dẫn, bạn sẽ đối mặt với những lỗi sau:

  • Đường dẫn thay đổi
  • Trạng thái bị hỏng
  • Công cụ đưa ra những dự đoán sai
  • Bạn mất thời gian để debug tên thay vì tập trung xây dựng

Một danh tính ổn định sẽ loại bỏ những nhiễu loạn này. Nó giúp việc review code dễ dàng hơn. Bạn sẽ thấy các thông tin thực tế của dự án trong các bản diff thay vì các đầu ra runtime ngẫu nhiên.

Ranh giới rất đơn giản:

  • AGENTS.md: những gì dự án mong đợi
  • .apc/project.json: dự án là gì
  • ~/.apx/: những gì đã xảy ra trong quá trình làm việc

Một dự án cần một điểm neo ổn định. Đường dẫn thư mục quá biến động. Runtime thì quá nhiễu. Một hợp đồng repo cộng với một tệp metadata là kích thước hợp lý.

Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca

Optional learning community: https://t.me/GyaanSetuAi