Project Directory Map Builder

Core Rules

• Must ask the user to specify the folder scope to scan; default full-repository scanning is prohibited.
• If the scope is too large, warn about context risks and ask the user to 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 active guidance mode (confirm the scope first before creating a new one).

Output Location Rules

• Single directory: Write PROJECT_MAP.md in the root of that directory.
• Multiple directories:
  • First ask: Generate a merged document, or generate one for each directory separately?
  • Merged: Write to the project root directory.
  • Separate: Write a PROJECT_MAP.md in the root of each directory.

Minimum Questions to Ask the User

• Which folders do you want to scan?
• If multiple folders: Merge into one document, or generate multiple separate documents?
• If the scope is large or unclear: Confirm the scope?

Workflow

A) Active Guidance Mode (PROJECT_MAP.md does not exist)

1. Confirm the scanning scope and output strategy.
2. Quickly list the file inventory of the specified directory.
3. Identify entry points and key files (e.g., manifest, main entry, service threads, UI, configuration, storage, tests, documentation).
4. Only open "key files" to explain their responsibilities and relationships; avoid full reading.
5. Generate PROJECT_MAP.md according to the structure template.
6. Must explicitly mark uncertain points (e.g., "Assumed", "Unconfirmed").

B) Update Mode (PROJECT_MAP.md already exists)

1. Read the existing PROJECT_MAP.md.
2. Only rescan the user-specified directory scope.
3. Combine "current conversation context" and file inventory differences to locate paragraphs that need updates.
4. Only perform incremental patch updates; do not rewrite the entire document.
5. Add a "This Update" section (date + scope + change points).

Scanning Rules

• Prioritize using fast file listing commands (e.g.,

  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 delve into.

Document Structure Template (PROJECT_MAP.md)

1. Project Overview (one sentence)
2. Scope of Application (list of folders scanned this time)
3. Entry Points and Execution Flow (simplified version)
4. Key Configurations and Storage Keys (if applicable)
5. Directory and File Descriptions (by directory hierarchy)
6. Key Module Relationships/Call Chains
7. Risks/Legacy Items/Uncertain Points
8. This Update (update mode only)

Multiple Directory Output Rules

• Merged document: List each directory in the "Scope of Application" section, and write independent sections for each directory.
• Separate documents: Each directory only describes its own scope; no cross-directory merging.

Update Mode Rules (Incremental Only)

• Try to retain the existing structure and expressions.
• Only modify parts related to added/deleted files or new context.
• Do not delete old content unless it is clearly incorrect.
• "This Update" records the date, scope, and change summary.

Security and Clarity

• Must mark unconfirmed behaviors or rules as "Assumed/Unconfirmed".
• Files that appear to be legacy should be marked as "Potentially Legacy"; do not recommend deletion unless requested by the user.