Document an Existing Project. Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
Document an Existing Project. Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
Source
Converted from /Users/shankavi/Documents/Voyager/.bmad-core/tasks/document-project.md
Task Definition
<!-- Powered by BMAD™ Core -->
Document an Existing Project
Purpose
Generate comprehensive documentation for existing projects optimized for AI development agents. This task creates structured reference materials that enable AI agents to understand project context, conventions, and patterns for effective contribution to any codebase.
Task Instructions
相關技能
1. Initial Project Analysis
CRITICAL: First, check if a PRD or requirements document exists in context. If yes, use it to focus your documentation efforts on relevant areas only.
IF PRD EXISTS:
Review the PRD to understand what enhancement/feature is planned
Identify which modules, services, or areas will be affected
Focus documentation ONLY on these relevant areas
Skip unrelated parts of the codebase to keep docs lean
IF NO PRD EXISTS:
Ask the user:
"I notice you haven't provided a PRD or requirements document. To create more focused and useful documentation, I recommend one of these options:
Create a PRD first - Would you like me to help create a brownfield PRD before documenting? This helps focus documentation on relevant areas.
Provide existing requirements - Do you have a requirements document, epic, or feature description you can share?
Describe the focus - Can you briefly describe what enhancement or feature you're planning? For example:
'Adding payment processing to the user service'
'Refactoring the authentication module'
'Integrating with a new third-party API'
Document everything - Or should I proceed with comprehensive documentation of the entire codebase? (Note: This may create excessive documentation for large projects)
Please let me know your preference, or I can proceed with full documentation if you prefer."
Based on their response:
If they choose option 1-3: Use that context to focus documentation
If they choose option 4 or decline: Proceed with comprehensive analysis below
Begin by conducting analysis of the existing project. Use available tools to:
Project Structure Discovery: Examine the root directory structure, identify main folders, and understand the overall organization
Technology Stack Identification: Look for package.json, requirements.txt, Cargo.toml, pom.xml, etc. to identify languages, frameworks, and dependencies
Build System Analysis: Find build scripts, CI/CD configurations, and development commands
Existing Documentation Review: Check for README files, docs folders, and any existing documentation
Code Pattern Analysis: Sample key files to understand coding patterns, naming conventions, and architectural approaches
Ask the user these elicitation questions to better understand their needs:
What is the primary purpose of this project?
Are there any specific areas of the codebase that are particularly complex or important for agents to understand?
What types of tasks do you expect AI agents to perform on this project? (e.g., bug fixes, feature additions, refactoring, testing)
Are there any existing documentation standards or formats you prefer?
What level of technical detail should the documentation target? (junior developers, senior developers, mixed team)
Is there a specific feature or enhancement you're planning? (This helps focus documentation)
2. Deep Codebase Analysis
CRITICAL: Before generating documentation, conduct extensive analysis of the existing codebase:
Explore Key Areas:
Entry points (main files, index files, app initializers)
Configuration files and environment setup
Package dependencies and versions
Build and deployment configurations
Test suites and coverage
Ask Clarifying Questions:
"I see you're using [technology X]. Are there any custom patterns or conventions I should document?"
"What are the most critical/complex parts of this system that developers struggle with?"
"Are there any undocumented 'tribal knowledge' areas I should capture?"
"What technical debt or known issues should I document?"
"Which parts of the codebase change most frequently?"
Map the Reality:
Identify ACTUAL patterns used (not theoretical best practices)
Find where key business logic lives
Locate integration points and external dependencies
Document workarounds and technical debt
Note areas that differ from standard patterns
IF PRD PROVIDED: Also analyze what would need to change for the enhancement
3. Core Documentation Generation
[[LLM: Generate a comprehensive BROWNFIELD architecture document that reflects the ACTUAL state of the codebase.
CRITICAL: This is NOT an aspirational architecture document. Document what EXISTS, including:
Technical debt and workarounds
Inconsistent patterns between different parts
Legacy code that can't be changed
Integration constraints
Performance bottlenecks
Document Structure:
[Project Name] Brownfield Architecture Document
Introduction
This document captures the CURRENT STATE of the [Project Name] codebase, including technical debt, workarounds, and real-world patterns. It serves as a reference for AI agents working on enhancements.
Document Scope
[If PRD provided: "Focused on areas relevant to: {enhancement description}"]
[If no PRD: "Comprehensive documentation of entire system"]
Change Log
Date
Version
Description
Author
[Date]
1.0
Initial brownfield analysis
[Analyst]
Quick Reference - Key Files and Entry Points
Critical Files for Understanding the System
Main Entry: src/index.js (or actual entry point)
Configuration: config/app.config.js, .env.example
Core Business Logic: src/services/, src/domain/
API Definitions: src/routes/ or link to OpenAPI spec
Database Models: src/models/ or link to schema files
Key Algorithms: [List specific files with complex logic]
If PRD Provided - Enhancement Impact Areas
[Highlight which files/modules will be affected by the planned enhancement]
High Level Architecture
Technical Summary
Actual Tech Stack (from package.json/requirements.txt)
Category
Technology
Version
Notes
Runtime
Node.js
16.x
[Any constraints]
Framework
Express
4.18.2
[Custom middleware?]
Database
PostgreSQL
13
[Connection pooling setup]
etc...
Repository Structure Reality Check
Type: [Monorepo/Polyrepo/Hybrid]
Package Manager: [npm/yarn/pnpm]
Notable: [Any unusual structure decisions]
Source Tree and Module Organization
Project Structure (Actual)
project-root/
├── src/
│ ├── controllers/ # HTTP request handlers
│ ├── services/ # Business logic (NOTE: inconsistent patterns between user and payment services)
│ ├── models/ # Database models (Sequelize)
│ ├── utils/ # Mixed bag - needs refactoring
│ └── legacy/ # DO NOT MODIFY - old payment system still in use
├── tests/ # Jest tests (60% coverage)
├── scripts/ # Build and deployment scripts
└── config/ # Environment configs
Key Modules and Their Purpose
User Management: src/services/userService.js - Handles all user operations