𝗔 𝗙𝗼𝗹𝗱𝗲𝗿 𝗡𝗮𝗺𝗲 𝗜𝘀 𝗡𝗼𝘁 𝗔 𝗣𝗿𝗼𝗷𝗲𝗰𝘁 𝗜𝗱𝗲𝗻𝘁𝗶𝘁𝘆
A folder path is a route. It tells a tool where a project lives right now. A project identity is different.
Identity must survive these common changes:
- Renaming the directory
- Moving the project between machines
- Cloning the repo into a new path
- Using multiple checkouts of the same project
If identity depends on the path, these actions become risky. The path might work, but it fails to prove the project is the same. This makes it a bad key for storing state.
I use a split design with APC and APX to solve this.
APC handles the project contract. It lives in the repository. APX handles the runtime state. It lives outside the repository.
APC uses specific files to create a stable anchor:
- AGENTS.md for the root contract
- .apc/project.json for project metadata
- .apc/agents/*.md for agent definitions
- .apc/mcps.json for MCP hints
The .apc/project.json file is tiny. It contains a name and a stable ID. It is a marker, not a large config file.
APX uses this file to connect a live checkout to a durable record. Paths help APX find the project. The metadata helps APX keep the project stable once it finds it.
This design keeps the repo clean. Runtime data like session logs and message history stay in APX storage. They do not clutter your git history.
When you rely on paths, you face these failures:
- Paths change
- State breaks
- The tool makes wrong guesses
- You spend time debugging names instead of building
A stable identity removes this noise. It makes code reviews easier. You see project facts in your diffs instead of accidental runtime output.
The boundary is simple:
- AGENTS.md: what the project expects
- .apc/project.json: what the project is
- ~/.apx/: what happened while working on it
A project needs one stable anchor. The folder path is too volatile. The runtime is too noisy. A repo contract plus a metadata file is the right size.
Source: https://dev.to/tecnomanu/a-folder-name-is-not-a-project-identity-4eca
Optional learning community: https://t.me/GyaanSetuAi