Back to Details

brownfield-onboarding

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Brownfield Project Onboarding

遗留项目上手流程

Overview

概述

This skill provides a systematic approach to understand and document existing projects. It helps developers quickly get up to speed with unfamiliar codebases by generating comprehensive documentation about the project's structure, architecture, design decisions, identifying areas for improvement, and creating AI agent constitution files (AGENTS.md) that encode project-specific knowledge, coding principles, and UI/UX guidelines for effective AI-assisted development.
该技能提供了一套系统化的方法来理解和记录已有项目。它通过生成关于项目结构、架构、设计决策的全面文档，识别改进方向，并创建AI Agent配置文件（AGENTS.md）（其中包含项目专属知识、编码原则和UI/UX指南，以支持高效的AI辅助开发），帮助开发者快速熟悉陌生的代码库。

When to Use This Skill

适用场景

Invoke this skill when:
  • Starting work on an unfamiliar or inherited codebase
  • Joining a new team or project
  • Conducting a technical audit of an existing system
  • User requests "help me understand this project"
  • Need to document an undocumented or poorly documented project
  • Preparing for a major refactoring or modernization effort
  • Setting up AI agent constitution files for better AI-assisted development
  • Establishing coding principles and standards for a team
  • Creating comprehensive context for AI agents working on the project
在以下场景中调用该技能：
  • 开始接手陌生或继承的代码库
  • 加入新团队或新项目
  • 对现有系统进行技术审计
  • 用户请求“帮我理解这个项目”
  • 需要为无文档或文档不完善的项目补充文档
  • 准备进行重大重构或现代化改造
  • 为AI辅助开发设置AI Agent配置文件
  • 为团队制定编码原则和标准
  • 为参与项目的AI Agent创建全面的上下文信息

How This Skill Works

工作原理

Upon invocation, this skill:
  1. Analyzes the project to determine its documentation state
  2. Selects the appropriate workflow based on project maturity
  3. Executes the workflow to generate comprehensive documentation
  4. Creates or enhances AGENTS.md files for AI agent context
  5. Provides actionable recommendations for improvements
调用该技能后，将执行以下步骤：
  1. 项目分析：确定项目的文档完善程度
  2. 选择合适的工作流：根据项目成熟度选择对应的工作流
  3. 执行工作流：生成全面的项目文档
  4. 创建或优化AGENTS.md文件：为AI Agent提供上下文信息
  5. 提供可落地的改进建议

Workflow Selection

工作流选择

This skill uses different workflows based on the project's current state:
该技能会根据项目的当前状态使用不同的工作流：

Project State Detection

项目状态检测

The AI agent automatically analyzes the project to determine its documentation maturity level.
Detection Process:
  1. Search for AGENTS.md files using 
    file_search
  2. Search for constitution/guideline files (.cursorrules, CONTRIBUTING.md, etc.)
  3. Read and analyze README for depth and quality
  4. Apply classification rules with intelligent judgment
Classification States:
  • MATURE: AGENTS.md exists
  • ESTABLISHED: Constitution files + substantial README (>100 lines)
  • PARTIAL: Basic README (>50 lines) only
  • VANILLA: Minimal/no documentation (default)
Detection Logic:
  • Has AGENTS.md → 
    MATURE
  • Has constitution files + README >100 lines with depth → 
    ESTABLISHED
  • Has README >50 lines of meaningful content → 
    PARTIAL
  • Otherwise → 
    VANILLA
    (default)
The agent uses its intelligence to assess quality, not just quantity. A 60-line README with architecture details is better than a 150-line changelog.
AI Agent会自动分析项目，确定其文档成熟度等级。
检测流程：
  1. 使用
    file_search
    搜索AGENTS.md文件
  2. 搜索配置/指南文件（.cursorrules、CONTRIBUTING.md等）
  3. 读取并分析README的深度和质量
  4. 结合智能判断应用分类规则
分类状态：
  • 成熟（MATURE）：已存在AGENTS.md文件
  • 已建立（ESTABLISHED）：存在配置文件且README内容详实（超过100行）
  • 部分文档（PARTIAL）：仅存在基础README（超过50行）
  • 初始状态（VANILLA）：文档极少或无文档（默认状态）
检测逻辑：
  • 存在AGENTS.md → 成熟（MATURE）
  • 存在配置文件且README内容详实（超过100行） → 已建立（ESTABLISHED）
  • 存在基础README（超过50行有意义内容）但无配置文件 → 部分文档（PARTIAL）
  • 其他情况 → 初始状态（VANILLA）（默认）
Agent会智能评估文档质量，而非仅看数量。一份60行包含架构细节的README，比150行的变更日志更有价值。

Workflow Files

工作流文件

Based on the agent's assessment, one of these workflows is executed:
Project StateWorkflow FileTimeUse When
Vanillavanilla-project.md15-25 minNo/minimal docs, no constitutions
Partial Docspartial-documentation.md10-20 minHas README, no constitutions
Establishedestablished-project.md10-15 minGood docs, has constitutions, no AGENTS.md
Maturemature-project.md5-10 minAlready has AGENTS.md files
📖 For detailed workflow selection logic, see decision-guide.md
根据Agent的评估结果，将执行以下工作流之一：
项目状态工作流文件耗时适用场景
初始状态vanilla-project.md15-25分钟无文档或文档极少，无配置文件
部分文档partial-documentation.md10-20分钟有README，但无配置文件
已建立established-project.md10-15分钟文档完善，有配置文件，但无AGENTS.md
成熟mature-project.md5-10分钟已存在AGENTS.md文件
📖 工作流选择逻辑详情，请查看decision-guide.md

Core Workflow Phases

核心工作流阶段

All workflows execute these five phases (adapted to project state):
所有工作流都会执行以下五个阶段（根据项目状态调整）：

Phase 1: Project Discovery

阶段1：项目探索

  • Scan codebase structure
  • Identify technologies and frameworks
  • Discover features and entry points
  • Output: 
    .onboard/overview.md
  • 扫描代码库结构
  • 识别技术栈和框架
  • 发现功能和入口点
  • 输出：
    .onboard/overview.md

Phase 2: Architecture Analysis

阶段2：架构分析

  • Document technical stack
  • Identify architectural patterns
  • Map data flow
  • Output: 
    .onboard/architecture.md
  • 记录技术栈
  • 识别架构模式
  • 梳理数据流
  • 输出：
    .onboard/architecture.md

Phase 3: Design Assessment

阶段3：设计评估

  • Evaluate code quality
  • Identify technical debt
  • Propose improvements
  • Output: 
    .onboard/design_suggestions.md
  • 评估代码质量
  • 识别技术债务
  • 提出改进方案
  • 输出：
    .onboard/design_suggestions.md

Phase 4: Quality & Automation Review

阶段4：质量与自动化评审

  • Assess testing coverage
  • Evaluate CI/CD maturity
  • Recommend improvements
  • Output: 
    .onboard/guardrail_suggestions.md
  • 评估测试覆盖率
  • 评估CI/CD成熟度
  • 提出改进建议
  • 输出：
    .onboard/guardrail_suggestions.md

Phase 5: Agent Constitution Generation

阶段5：Agent配置文件生成

  • Detect/read existing constitutions
  • Generate or enhance AGENTS.md files
  • Create project-specific guidelines
  • Outputs: 
    AGENTS.md
    files + 
    .onboard/agent_constitution.md
  • 检测/读取现有配置文件
  • 生成或优化AGENTS.md文件
  • 创建项目专属指南
  • 输出：
    AGENTS.md
    文件 + 
    .onboard/agent_constitution.md

Execution Instructions

执行步骤

Step 1: Detect Project State

步骤1：检测项目状态

Analyze the project to determine its documentation maturity:
  1. Search for AGENTS.md: Use 
    file_search
    with pattern 
    **/AGENTS.md
    • If found → State is MATURE
  2. Search for constitution files: Use 
    file_search
    to look for:
    • .cursorrules
    • CONTRIBUTING.md
    • .github/CONSTITUTION.md
    • Linter configs (
      .eslintrc
      , 
      .prettierrc
      , etc.)
    • Style guides
  3. Analyze README: Use 
    read_file
    to check README.md
    • Count lines of meaningful content (exclude headers, badges, empty lines)
    • Assess depth: Does it explain architecture, setup, contribution guidelines?
  4. Classify based on findings:
    • Has AGENTS.md → MATURE
    • Has constitution files + substantial README (>100 lines) → ESTABLISHED
    • Has basic README (>50 lines) but no constitution → PARTIAL
    • Minimal/no README (<50 lines) → VANILLA (default)
分析项目以确定其文档成熟度：
  1. 搜索AGENTS.md：使用
    file_search
    ，匹配模式为
    **/AGENTS.md
    • 若找到 → 状态为成熟（MATURE）
  2. 搜索配置文件：使用
    file_search
    查找以下文件：
    • .cursorrules
    • CONTRIBUTING.md
    • .github/CONSTITUTION.md
    • 代码检查器配置文件（
      .eslintrc
      、
      .prettierrc
      等）
    • 风格指南
  3. 分析README：使用
    read_file
    读取README.md
    • 统计有意义内容的行数（排除标题、徽章、空行）
    • 评估深度：是否包含架构、搭建、贡献指南等内容？
  4. 根据检测结果分类：
    • 存在AGENTS.md → 成熟（MATURE）
    • 存在配置文件且README内容详实（超过100行） → 已建立（ESTABLISHED）
    • 存在基础README（超过50行）但无配置文件 → 部分文档（PARTIAL）
    • README内容极少（少于50行） → 初始状态（VANILLA）（默认）

Step 2: Load Appropriate Workflow

步骤2：加载对应工作流

Based on your assessment, read and execute the corresponding workflow:
  • MATURE → references/mature-project.md
  • ESTABLISHED → references/established-project.md
  • PARTIAL → references/partial-documentation.md
  • VANILLA → references/vanilla-project.md
根据评估结果，读取并执行对应的工作流：
  • 成熟（MATURE） → references/mature-project.md
  • 已建立（ESTABLISHED） → references/established-project.md
  • 部分文档（PARTIAL） → references/partial-documentation.md
  • 初始状态（VANILLA） → references/vanilla-project.md

Step 3: Execute Workflow

步骤3：执行工作流

Follow the instructions in the selected workflow file:
  • Each workflow provides detailed, phase-by-phase instructions
  • Each workflow adapts phases to the project's current state
  • Each workflow includes specific tool usage recommendations
遵循选中工作流文件中的说明：
  • 每个工作流都提供了详细的分阶段指导
  • 每个工作流会根据项目当前状态调整阶段内容
  • 每个工作流包含特定工具的使用建议

Step 4: Validate Outputs

步骤4：验证输出

Ensure all expected files are generated:
  • .onboard/overview.md
  • .onboard/architecture.md
  • .onboard/design_suggestions.md
  • .onboard/guardrail_suggestions.md
  • .onboard/agent_constitution.md
  • ./AGENTS.md
    (created or enhanced)
  • Subdirectory AGENTS.md files (if applicable)
确保生成所有预期文件：
  • .onboard/overview.md
  • .onboard/architecture.md
  • .onboard/design_suggestions.md
  • .onboard/guardrail_suggestions.md
  • .onboard/agent_constitution.md
  • ./AGENTS.md
    （新建或优化）
  • 子目录AGENTS.md文件（如适用）

Step 5: Provide Summary

步骤5：提供总结

Give user a comprehensive completion summary based on workflow type.
根据工作流类型，为用户提供全面的完成总结。

AGENTS.md Templates

AGENTS.md模板

This skill includes template files for generating AGENTS.md:
该技能包含用于生成AGENTS.md的模板文件：

Available Templates

可用模板

  1. root-agents-template.md
    • Project-wide context and coding principles
    • Placed at project root
  2. frontend-agents-template.md
    • Frontend-specific guidelines
    • UI/UX design system and accessibility
    • Placed in frontend directory
  3. backend-agents-template.md
    • Backend-specific guidelines
    • API design and security principles
    • Placed in backend directory
📖 For template usage details, see templates/README.md
  1. root-agents-template.md
    • 项目级上下文和编码原则
    • 放置在项目根目录
  2. frontend-agents-template.md
    • 前端专属指南
    • UI/UX设计系统和无障碍规范
    • 放置在前端目录
  3. backend-agents-template.md
    • 后端专属指南
    • API设计和安全原则
    • 放置在后端目录
📖 模板使用详情，请查看templates/README.md

Template Adaptation

模板适配

Templates are adapted based on:
  • Actual project structure and patterns
  • Discovered design tokens and conventions
  • Existing constitution file content
  • Tech stack and framework conventions
模板会根据以下内容进行适配：
  • 实际项目结构和模式
  • 已发现的设计规范和约定
  • 现有配置文件内容
  • 技术栈和框架约定

Key Principles

核心原则

1. Non-Destructive Enhancement

1. 非破坏性优化

  • Never overwrite existing documentation
  • Enhance and complement, don't replace
  • Preserve existing constitution files
  • Mark all additions clearly
  • 绝不覆盖现有文档
  • 补充和优化，而非替换
  • 保留现有配置文件
  • 清晰标记所有新增内容

2. Context-Aware Generation

2. 上下文感知生成

  • Generate content based on actual code analysis
  • Use project-specific examples
  • Adapt to detected patterns
  • Match existing documentation style
  • 基于实际代码分析生成内容
  • 使用项目专属示例
  • 适配已检测到的模式
  • 匹配现有文档风格

3. Workflow Adaptation

3. 工作流适配

  • Different approaches for different project maturities
  • Respect existing work and conventions
  • Focus effort where value is highest
  • Minimize disruption to established projects
  • 根据项目成熟度采用不同方法
  • 尊重现有工作和约定
  • 聚焦高价值领域投入精力
  • 最小化对已建立项目的干扰

4. AI Agent Optimization

4. AI Agent优化

  • Create machine-readable guidelines
  • Include validation checklists
  • Provide quick reference formats
  • Synthesize across multiple docs
  • 创建机器可读的指南
  • 包含验证检查清单
  • 提供快速参考格式
  • 整合多份文档的内容

Common Tools Used

常用工具

Across all workflows, these tools are commonly used:
所有工作流中常用的工具如下：

Discovery Tools

探索工具

  • list_dir
    - Explore directory structure
  • file_search
    - Find specific files by pattern (e.g., 
    **/AGENTS.md
    , 
    **/.cursorrules
    )
  • read_file
    - Read documentation and config files (README, CONTRIBUTING, etc.)
  • list_dir
    - 浏览目录结构
  • file_search
    - 按模式查找特定文件（如
    **/AGENTS.md
    、
    **/.cursorrules
    ）
  • read_file
    - 读取文档和配置文件（README、CONTRIBUTING等）

Analysis Tools

分析工具

  • semantic_search
    - Find features and concepts
  • grep_search
    - Pattern-based code search
  • list_code_usages
    - Understand code relationships
  • semantic_search
    - 查找功能和概念
  • grep_search
    - 基于模式的代码搜索
  • list_code_usages
    - 理解代码间的关联

Validation Tools

验证工具

  • get_errors
    - Identify existing issues
  • Code analysis for patterns and anti-patterns
  • get_errors
    - 识别现有问题
  • 代码分析以检测模式和反模式

Output Directory Structure

输出目录结构

After execution, the workspace contains:
.onboard/
├── overview.md              # Project structure and features
├── architecture.md          # Technical stack and architecture
├── design_suggestions.md    # Improvement recommendations
├── guardrail_suggestions.md # Testing and CI/CD recommendations
└── agent_constitution.md    # Constitution generation summary

AGENTS.md                    # Root project constitution
[frontend]/AGENTS.md         # Frontend guidelines (if applicable)
[backend]/AGENTS.md          # Backend guidelines (if applicable)
执行完成后，工作区将包含以下结构：
.onboard/
├── overview.md              # 项目结构和功能
├── architecture.md          # 技术栈和架构
├── design_suggestions.md    # 改进建议
├── guardrail_suggestions.md # 测试和CI/CD改进建议
└── agent_constitution.md    # 配置文件生成总结

AGENTS.md                    # 项目根目录配置文件
[frontend]/AGENTS.md         # 前端指南（如适用）
[backend]/AGENTS.md          # 后端指南（如适用）

Notes & Best Practices

注意事项与最佳实践

  • Comprehensive Analysis: Take time to thoroughly explore before documenting
  • Be Specific: Include file paths and concrete examples
  • Prioritize: Rank suggestions by impact and effort
  • Actionable: Provide implementable recommendations
  • Context-Aware: Tailor to project size, domain, and maturity
  • Positive Framing: Start with strengths before improvements
  • Realistic Estimates: Provide effort estimates for planning
  • Agent-Friendly: Enable AI agents to validate their work
  • Respect Existing Constitutions: Enhance rather than replace
  • Non-Destructive: Always preserve existing content when merging
  • Context-Rich Constitutions: Make AGENTS.md comprehensive with project-specific details
  • 全面分析：在记录前花时间彻底探索项目
  • 具体明确：包含文件路径和具体示例
  • 优先级排序：根据影响和投入成本对建议排序
  • 可落地：提供可执行的改进建议
  • 上下文感知：根据项目规模、领域和成熟度调整内容
  • 积极表述：先强调优势再提出改进方向
  • 合理估算：为规划提供投入成本估算
  • Agent友好：让AI Agent能够验证自身工作
  • 尊重现有配置：优化而非替换现有配置文件
  • 非破坏性：合并时始终保留现有内容
  • 上下文丰富的配置：让AGENTS.md包含全面的项目专属细节

Common Pitfalls to Avoid

常见误区

  • ❌ Generating superficial documentation without deep analysis
  • ❌ Making technology recommendations without understanding constraints
  • ❌ Suggesting major rewrites instead of incremental improvements
  • ❌ Ignoring existing documentation or architectural decisions
  • ❌ Providing generic advice that doesn't apply to the specific project
  • ❌ Overwhelming with too many suggestions without prioritization
  • ❌ Missing critical security or performance issues
  • ❌ Overwriting existing constitution files without preserving original content
  • ❌ Creating generic AGENTS.md templates without project-specific context
  • ❌ Skipping UI/UX principles analysis for frontend projects
  • ❌ 未深入分析就生成表面化文档
  • ❌ 未理解约束就提出技术建议
  • ❌ 建议重大重写而非增量改进
  • ❌ 忽略现有文档或架构决策
  • ❌ 提供不适用于特定项目的通用建议
  • ❌ 提出过多建议而不排序优先级
  • ❌ 遗漏关键安全或性能问题
  • ❌ 覆盖现有配置文件而不保留原始内容
  • ❌ 创建无项目专属上下文的通用AGENTS.md模板
  • ❌ 跳过前端项目的UI/UX原则分析

Extension Points

扩展方向

This skill can be extended to include:
  • Security Audit: Dedicated security vulnerability assessment
  • Performance Profiling: Performance bottleneck identification
  • Accessibility Review: WCAG compliance checking for web apps
  • API Documentation: Automated API documentation generation
  • Database Analysis: Schema design review and optimization suggestions
  • UI/UX Deep Dive: Integration with ui-ux-pro-max skill for comprehensive UI/UX principles
  • Dependency Audit: Automated dependency security and license checking
  • Constitution Compliance: Automated checking of code against AGENTS.md guidelines
该技能可扩展以下功能：
  • 安全审计：专门的安全漏洞评估
  • 性能分析：识别性能瓶颈
  • 无障碍评审：Web应用的WCAG合规性检查
  • API文档：自动生成API文档
  • 数据库分析：数据库设计评审和优化建议
  • UI/UX深度分析：与ui-ux-pro-max技能集成，生成全面的UI/UX原则
  • 依赖审计：自动检查依赖的安全性和许可证
  • 配置合规性：自动检查代码是否符合AGENTS.md指南

Related Skills

相关技能

  • ui-ux-pro-max: Can be invoked for comprehensive UI/UX analysis to enhance frontend AGENTS.md files
  • openspec-constitution-guard: Can validate code changes against generated AGENTS.md constitutions
  • issue-fixer: Uses project context from AGENTS.md files to fix issues more effectively
  • retrospect: References AGENTS.md for project-specific context during retrospective analysis
  • ui-ux-pro-max：可调用该技能进行全面UI/UX分析，以优化前端AGENTS.md文件
  • openspec-constitution-guard：可根据生成的AGENTS.md配置文件验证代码变更
  • issue-fixer：利用AGENTS.md中的项目上下文更高效地修复问题
  • retrospect：在回顾分析时参考AGENTS.md中的项目专属上下文

Reference Documentation

参考文档

Workflow References

工作流参考

  • decision-guide.md - How to choose the right workflow
  • vanilla-project.md - Workflow for minimal documentation
  • partial-documentation.md - Workflow for basic README projects
  • established-project.md - Workflow for well-documented projects
  • mature-project.md - Workflow for projects with existing AGENTS.md
  • decision-guide.md - 如何选择合适的工作流
  • vanilla-project.md - 适用于文档极少的项目工作流
  • partial-documentation.md - 适用于仅含基础README的项目工作流
  • established-project.md - 适用于文档完善的项目工作流
  • mature-project.md - 适用于已存在AGENTS.md的项目工作流

Template References

模板参考

  • templates/README.md - Template usage guide
  • templates/root-agents-template.md - Root constitution template
  • templates/frontend-agents-template.md - Frontend constitution template
  • templates/backend-agents-template.md - Backend constitution template
  • templates/README.md - 模板使用指南
  • templates/root-agents-template.md - 根目录配置文件模板
  • templates/frontend-agents-template.md - 前端配置文件模板
  • templates/backend-agents-template.md - 后端配置文件模板

Examples

示例

  • phase5-example.md - Complete Phase 5 execution example
  • phase5-example.md - 完整的阶段5执行示例

Quick Start

快速开始

To use this skill:
  1. User invokes: "Help me understand this project" or "Run brownfield onboarding"
  2. Detect project state: Analyze project to determine maturity level (MATURE/ESTABLISHED/PARTIAL/VANILLA)
  3. Load workflow: Read the appropriate workflow file from 
    references/
  4. Execute phases: Follow workflow instructions for all 5 phases
  5. Generate outputs: Create all documentation and AGENTS.md files
  6. Provide summary: Give user comprehensive results and next steps
The workflow files contain all detailed instructions - this main SKILL.md serves as the orchestration guide.
使用该技能的步骤：
  1. 用户调用：“帮我理解这个项目”或“运行遗留项目上手流程”
  2. 检测项目状态：分析项目以确定成熟度等级（成熟/已建立/部分文档/初始状态）
  3. 加载工作流：从
    references/
    目录读取对应的工作流文件
  4. 执行阶段任务：遵循工作流说明完成所有5个阶段
  5. 生成输出：创建所有文档和AGENTS.md文件
  6. 提供总结：为用户提供全面的结果和下一步建议
工作流文件包含所有详细说明 - 本SKILL.md作为总览指南。