project-map-builder

Project directory map builder

Generate or incrementally update a high-signal-to-noise directory description document for a specified directory scope.

Core rules

• The user must specify the folder scope to be scanned; defaulting to a full repository scan is prohibited.
• If the scope is too large, warn about context risk and have the user confirm or narrow the scope.
• The output language must match the user's current language.
• The document filename is fixed: PROJECT_MAP.md.
• If PROJECT_MAP.md already exists at the output location, enter update mode (incremental updates only).
• If it does not exist, enter proactive guidance mode (confirm the scope first, then create it).

Output location rules

• Single directory: write PROJECT_MAP.md at the root of that directory.
• Multiple directories:
  • First ask: generate one merged document, or one for each directory.
  • Merged: write to the project root directory.
  • Separate: write one PROJECT_MAP.md at the root of each directory.

Minimum questions to ask the user

• Which folders should be scanned?
• If there are multiple folders: merge into one document, or generate multiple separately?
• If the scope is large or unclear: confirm the scope?

Workflow

A) Proactive guidance mode (PROJECT_MAP.md does not exist)

1. Confirm the scan scope and output strategy.
2. Quickly list the file inventory of the specified directory.
3. Identify entry points and key files (such as manifest, main entry, service threads, UI, configuration, storage, tests, documentation).
4. Only open "key files" to explain responsibilities and relationships; avoid reading everything in full.
5. Generate PROJECT_MAP.md according to the structure template.
6. Uncertainties must be explicitly marked (such as "assumption" or "unconfirmed").

B) Update mode (PROJECT_MAP.md already exists)

1. Read the existing PROJECT_MAP.md.
2. Only rescan the directory scope specified by the user.
3. Using the "current conversation context" and differences in the file inventory, locate the sections that need updating.
4. Only perform incremental patch updates; do not perform a full rewrite.
5. Add a "This update" subsection (date + scope + change points).

Scanning rules

• Prefer using fast file listing commands (such as rg --files or Get-ChildItem）。
• Do not open all files; only read key files.
• If deeper details are needed, first confirm with the user which subdirectories to go deeper into.

Document structure template (PROJECT_MAP.md)

May be adjusted as needed, but it is recommended to include:

1. Project overview (one sentence)
2. Scope (list of folders scanned this time)
3. Entry points and runtime chain (simplified version)
4. Key configuration and storage keys (if applicable)
5. Directory and file descriptions (by directory hierarchy)
6. Key module relationships/call chains
7. Risks/legacy issues/uncertain points
8. This update (update mode only)

Multi-directory output rules

• Merged document: list each directory under "Scope" and write a separate subsection for each directory.
• Separate documents: each directory describes only its own scope; no cross-directory merging.

Update mode rules (incremental only)

• Preserve existing structure and wording as much as possible.
• Modify only the parts related to added/deleted files or new context.
• Do not delete old content unless it is clearly erroneous.
• "This update" records the date, scope, and change summary.

Safety and clarity

• Behaviors or rules that cannot be confirmed must be marked as "assumption/unconfirmed."
• Files that appear to be leftovers should be marked as "possibly leftover," and deletion is not recommended unless the user requests it.