Analyze Project Context
Overview
Build comprehensive, evidence-based understanding of ANY project type (code, documentation, content, mixed) before making changes. Works for technical projects, content projects, documentation repositories, and everything in between.
Core principle: Discover what exists, infer patterns, document best practices, establish constitution.
When to Use
Use when:
- Starting work on a new project
- User asks to "analyze the project" or "understand the codebase"
- Before making significant changes
- Need to understand project structure and conventions
- Setting up AI agent workflow for a project
Works for:
- Software projects (Node.js, Python, Go, etc.)
- Documentation repositories
- Content projects (marketing, writing, guides)
- Mixed projects (docs + code)
- Design projects (templates, assets)
- Any organized file structure
Core Principles
- Evidence Over Assumption: Discover what exists, don't assume structure
- Pattern Recognition: Infer conventions from existing files
- Universal Applicability: Works for any project type
- Document Findings: Create AGENTS.md and constitution.md
- Depth Control: Use discovery budget (max 2-3 tool calls per category) to avoid analysis paralysis
Workflow
1. Project Type Detection
Action: Identify project type from file structure
Discovery:
- Check for README.md, README, or similar (project overview)
- Look for technical indicators:
package.json, requirements.txt, Cargo.toml, go.mod, pom.xml, etc.
- Look for content indicators:
docs/, content/, posts/, guides/, templates/
- Check for existing AI/agent files:
.claude/, .specify/
Classify as:
- Technical: Has package managers, source code, build configs
- Content: Primarily markdown, templates, media files
- Documentation: Organized docs structure, no executable code
- Mixed: Contains both code and significant content/docs
2. Structural Discovery
Action: Map the project organization
Universal Checks:
- README.md or equivalent (purpose, structure, getting started)
- Directory structure (identify main folders and their purposes)
- File naming patterns (kebab-case, camelCase, snake_case)
- Organization principles (by feature, by type, by topic)
Technical Projects (if detected):
- Package manager files (
package.json, requirements.txt, etc.)
- Source directories (
src/, lib/, app/)
- Test directories (
test/, __tests__/, spec/)
- Build configs and tooling
Content Projects (if detected):
- Content organization (
docs/, content/, posts/, guides/)
- Templates and reusable components
- Media assets (
images/, assets/, static/)
- Style guides or brand guidelines
3. Pattern & Convention Discovery
Action: Infer project conventions from existing files
Sample 3-5 representative files to extract:
- Naming conventions (files, directories, identifiers)
- Structural patterns (how are similar things organized?)
- Documentation patterns (inline comments, separate docs, both?)
- Metadata usage (frontmatter, headers, tags)
For Technical Projects:
- Code style (linters, formatters, config files)
- Testing patterns (framework, file locations, naming)
- Import/module patterns
- Error handling conventions
For Content Projects:
- Content structure (headings, sections, metadata)
- Cross-referencing patterns (links, includes, references)
- Asset organization and naming
- Version control patterns (drafts, published, archived)
4. Standards Documentation Discovery
Action: Find existing standards, guidelines, or best practices
Check for:
- CONTRIBUTING.md (contribution guidelines)
- STYLE.md or style guides
- ARCHITECTURE.md or technical docs
- AGENTS.md (AI agent best practices) - if exists
- constitution.md (project principles) - if exists
- Templates or examples directory
Extract existing standards from these files (don't reinvent what exists)
5. Technology Analysis (If Technical Project)
Action: Identify actual technology stack
Sources:
- Package manager files (dependencies, dev dependencies)
- Config files (tsconfig, babel, webpack, etc.)
- Import/require statements in source files
- Build scripts and deployment configs
Optional Validation:
- For major frameworks, verify version-specific patterns
- Check if code matches current best practices for that version
- Identify deprecated patterns or outdated dependencies
Skip this section for non-technical projects
6. Create AGENTS.md (Best Practices for AI Agents)
Action: Generate or update .claude/AGENTS.md with project-specific best practices
Structure:
# AI Agent Best Practices: [Project Name]
**Generated:** [Date]
**Project Type:** [Technical/Content/Documentation/Mixed]
## Project Overview
[From README - purpose, goals, audience]
## Working with This Project
### File Organization
- [Pattern 1]: [Explanation and examples]
- [Pattern 2]: [Explanation and examples]
### Naming Conventions
- Files: [Convention with examples]
- [Other identifiers]: [Convention with examples]
### Common Tasks
1. [Task]: [How to do it correctly]
2. [Task]: [How to do it correctly]
### Quality Standards
- [Standard 1]: [What to check]
- [Standard 2]: [What to check]
### What NOT to Do
- ❌ [Anti-pattern]: [Why to avoid]
- ❌ [Anti-pattern]: [Why to avoid]
### Technology-Specific Notes
[Only if technical project - framework versions, patterns, gotchas]
## Related Files
- Constitution: `.specify/memory/constitution.md` (if exists)
- [Other relevant docs]
Base content on discovered patterns - this is project-specific, not generic advice
7. Create/Update Constitution (Project Principles)
Action: Trigger speckit-constitution skill to create or update .specify/memory/constitution.md
If constitution doesn't exist:
- Invoke
speckit-constitution skill
- Suggest principles based on discovered patterns
- Let user refine interactively
If constitution exists:
- Report path and note it was found
- Validate current project follows constitution
- Report any violations or gaps
Constitution should capture:
- Non-negotiable project principles (MUST)
- Strong recommendations (SHOULD)
- Forbidden patterns or approaches
- Quality gates and standards
- Technology constraints (if technical project)
8. Synthesis & Report
Action: Generate structured analysis report
Format:
# Project Analysis: [Project Name]
## Executive Summary
- **Project Type:** [Type]
- **Primary Purpose:** [From README]
- **Key Characteristics:** [3-5 bullet points]
## Structure
[Directory tree or organization description]
## Conventions & Patterns
[Key patterns discovered]
## Standards & Guidelines
- Existing: [List of found docs]
- Created: AGENTS.md with project best practices
- Constitution: [Created/Updated/Found at path]
## Recommendations
1. [Action]: [Reason]
2. [Action]: [Reason]
## Next Steps
[Suggested actions - use existing skills, workflows, or custom tasks]
Present options to user:
- Review AGENTS.md and constitution.md
- Start implementing features (use speckit workflow)
- Run specific analysis (code quality, documentation coverage, etc.)
Anti-Patterns (What NOT to Do)
Universal Anti-Patterns
- NEVER assume project structure without verification
- NEVER create AGENTS.md with generic, non-specific advice
- NEVER skip constitution creation/update
- NEVER hallucinate file paths that don't exist
- NEVER overwrite existing standards without reviewing them first
Technical Project Anti-Patterns
- NEVER assume framework patterns without checking versions (e.g., Next.js App Router vs Pages)
- NEVER skip validation of major dependencies
- NEVER guess package manager (could be npm, yarn, pnpm, bun)
Content Project Anti-Patterns
- NEVER ignore existing content organization patterns
- NEVER assume markdown is the only format (could be MDX, AsciiDoc, reStructuredText)
- NEVER overlook asset organization and naming conventions
Common Mistakes
| Mistake |
Reality |
| "All projects have package.json" |
Content projects, docs repos don't have code dependencies |
| "I'll skip AGENTS.md for simple projects" |
Even simple projects benefit from documented patterns |
| "Constitution is only for code projects" |
ALL projects need principles (quality, style, structure) |
| "Generic best practices are enough" |
Project-specific patterns are what make AGENTS.md valuable |
| "I can infer everything from README" |
READMEs often incomplete - inspect actual files |
Quick Reference
| Project Type |
Key Discovery |
Constitution Focus |
| Technical |
Package manager, tech stack, code patterns |
Code quality, tech constraints, testing |
| Content |
Content structure, frontmatter, assets |
Style, tone, structure, publishing |
| Documentation |
Doc organization, cross-references |
Accuracy, consistency, completeness |
| Mixed |
Both code and content patterns |
Both technical and content standards |
Success Indicators
Analysis is complete when:
- ✅ Project type correctly identified
- ✅ Key directories and organization patterns discovered
- ✅ File naming and structure conventions documented
- ✅ AGENTS.md created with project-specific best practices
- ✅ Constitution created or verified
- ✅ Report generated with actionable next steps
- ✅ No assumptions made without evidence
Output
Created Files:
.claude/
└── AGENTS.md # Project-specific AI agent best practices
.specify/memory/
└── constitution.md # Project principles (created or updated)
Analysis Report:
- Project classification
- Structure and conventions
- Standards documentation
- Recommendations and next steps
Related Skills
- speckit-constitution - Create/update project constitution (invoked automatically)
- speckit - Full spec-driven development workflow (suggested next step for features)
- brainstorming - Explore requirements before making changes
1---2name: analyze-project-context-43description: Use when starting work on any project (technical or non-technical) to understand structure, standards, and best practices before making changes4metadata:5 source: https://skillmd.com/skills/majiayu000/analyze-project-context-46---78# Analyze Project Context910## Overview1112Build comprehensive, evidence-based understanding of ANY project type (code, documentation, content, mixed) before making changes. Works for technical projects, content projects, documentation repositories, and everything in between.1314**Core principle:** Discover what exists, infer patterns, document best practices, establish constitution.1516## When to Use1718Use when:19- Starting work on a new project20- User asks to "analyze the project" or "understand the codebase"21- Before making significant changes22- Need to understand project structure and conventions23- Setting up AI agent workflow for a project2425Works for:26- Software projects (Node.js, Python, Go, etc.)27- Documentation repositories28- Content projects (marketing, writing, guides)29- Mixed projects (docs + code)30- Design projects (templates, assets)31- Any organized file structure3233## Core Principles3435- **Evidence Over Assumption:** Discover what exists, don't assume structure36- **Pattern Recognition:** Infer conventions from existing files37- **Universal Applicability:** Works for any project type38- **Document Findings:** Create AGENTS.md and constitution.md39- **Depth Control:** Use discovery budget (max 2-3 tool calls per category) to avoid analysis paralysis4041## Workflow4243### 1. Project Type Detection4445**Action:** Identify project type from file structure4647**Discovery:**48- Check for README.md, README, or similar (project overview)49- Look for technical indicators: `package.json`, `requirements.txt`, `Cargo.toml`, `go.mod`, `pom.xml`, etc.50- Look for content indicators: `docs/`, `content/`, `posts/`, `guides/`, `templates/`51- Check for existing AI/agent files: `.claude/`, `.specify/`5253**Classify as:**54- **Technical:** Has package managers, source code, build configs55- **Content:** Primarily markdown, templates, media files56- **Documentation:** Organized docs structure, no executable code57- **Mixed:** Contains both code and significant content/docs5859### 2. Structural Discovery6061**Action:** Map the project organization6263**Universal Checks:**64- README.md or equivalent (purpose, structure, getting started)65- Directory structure (identify main folders and their purposes)66- File naming patterns (kebab-case, camelCase, snake_case)67- Organization principles (by feature, by type, by topic)6869**Technical Projects (if detected):**70- Package manager files (`package.json`, `requirements.txt`, etc.)71- Source directories (`src/`, `lib/`, `app/`)72- Test directories (`test/`, `__tests__/`, `spec/`)73- Build configs and tooling7475**Content Projects (if detected):**76- Content organization (`docs/`, `content/`, `posts/`, `guides/`)77- Templates and reusable components78- Media assets (`images/`, `assets/`, `static/`)79- Style guides or brand guidelines8081### 3. Pattern & Convention Discovery8283**Action:** Infer project conventions from existing files8485**Sample 3-5 representative files** to extract:86- Naming conventions (files, directories, identifiers)87- Structural patterns (how are similar things organized?)88- Documentation patterns (inline comments, separate docs, both?)89- Metadata usage (frontmatter, headers, tags)9091**For Technical Projects:**92- Code style (linters, formatters, config files)93- Testing patterns (framework, file locations, naming)94- Import/module patterns95- Error handling conventions9697**For Content Projects:**98- Content structure (headings, sections, metadata)99- Cross-referencing patterns (links, includes, references)100- Asset organization and naming101- Version control patterns (drafts, published, archived)102103### 4. Standards Documentation Discovery104105**Action:** Find existing standards, guidelines, or best practices106107**Check for:**108- CONTRIBUTING.md (contribution guidelines)109- STYLE.md or style guides110- ARCHITECTURE.md or technical docs111- AGENTS.md (AI agent best practices) - if exists112- constitution.md (project principles) - if exists113- Templates or examples directory114115**Extract existing standards** from these files (don't reinvent what exists)116117### 5. Technology Analysis (If Technical Project)118119**Action:** Identify actual technology stack120121**Sources:**122- Package manager files (dependencies, dev dependencies)123- Config files (tsconfig, babel, webpack, etc.)124- Import/require statements in source files125- Build scripts and deployment configs126127**Optional Validation:**128- For major frameworks, verify version-specific patterns129- Check if code matches current best practices for that version130- Identify deprecated patterns or outdated dependencies131132**Skip this section** for non-technical projects133134### 6. Create AGENTS.md (Best Practices for AI Agents)135136**Action:** Generate or update `.claude/AGENTS.md` with project-specific best practices137138**Structure:**139```markdown140# AI Agent Best Practices: [Project Name]141142**Generated:** [Date]143**Project Type:** [Technical/Content/Documentation/Mixed]144145## Project Overview146[From README - purpose, goals, audience]147148## Working with This Project149150### File Organization151- [Pattern 1]: [Explanation and examples]152- [Pattern 2]: [Explanation and examples]153154### Naming Conventions155- Files: [Convention with examples]156- [Other identifiers]: [Convention with examples]157158### Common Tasks1591. [Task]: [How to do it correctly]1602. [Task]: [How to do it correctly]161162### Quality Standards163- [Standard 1]: [What to check]164- [Standard 2]: [What to check]165166### What NOT to Do167- ❌ [Anti-pattern]: [Why to avoid]168- ❌ [Anti-pattern]: [Why to avoid]169170### Technology-Specific Notes171[Only if technical project - framework versions, patterns, gotchas]172173## Related Files174- Constitution: `.specify/memory/constitution.md` (if exists)175- [Other relevant docs]176```177178**Base content on discovered patterns** - this is project-specific, not generic advice179180### 7. Create/Update Constitution (Project Principles)181182**Action:** Trigger `speckit-constitution` skill to create or update `.specify/memory/constitution.md`183184**If constitution doesn't exist:**185- Invoke `speckit-constitution` skill186- Suggest principles based on discovered patterns187- Let user refine interactively188189**If constitution exists:**190- Report path and note it was found191- Validate current project follows constitution192- Report any violations or gaps193194**Constitution should capture:**195- Non-negotiable project principles (MUST)196- Strong recommendations (SHOULD)197- Forbidden patterns or approaches198- Quality gates and standards199- Technology constraints (if technical project)200201### 8. Synthesis & Report202203**Action:** Generate structured analysis report204205**Format:**206```markdown207# Project Analysis: [Project Name]208209## Executive Summary210- **Project Type:** [Type]211- **Primary Purpose:** [From README]212- **Key Characteristics:** [3-5 bullet points]213214## Structure215[Directory tree or organization description]216217## Conventions & Patterns218[Key patterns discovered]219220## Standards & Guidelines221- Existing: [List of found docs]222- Created: AGENTS.md with project best practices223- Constitution: [Created/Updated/Found at path]224225## Recommendations2261. [Action]: [Reason]2272. [Action]: [Reason]228229## Next Steps230[Suggested actions - use existing skills, workflows, or custom tasks]231```232233**Present options to user:**2341. Review AGENTS.md and constitution.md2352. Start implementing features (use speckit workflow)2363. Run specific analysis (code quality, documentation coverage, etc.)237238## Anti-Patterns (What NOT to Do)239240### Universal Anti-Patterns241- **NEVER** assume project structure without verification242- **NEVER** create AGENTS.md with generic, non-specific advice243- **NEVER** skip constitution creation/update244- **NEVER** hallucinate file paths that don't exist245- **NEVER** overwrite existing standards without reviewing them first246247### Technical Project Anti-Patterns248- **NEVER** assume framework patterns without checking versions (e.g., Next.js App Router vs Pages)249- **NEVER** skip validation of major dependencies250- **NEVER** guess package manager (could be npm, yarn, pnpm, bun)251252### Content Project Anti-Patterns253- **NEVER** ignore existing content organization patterns254- **NEVER** assume markdown is the only format (could be MDX, AsciiDoc, reStructuredText)255- **NEVER** overlook asset organization and naming conventions256257## Common Mistakes258259| Mistake | Reality |260|---------|---------|261| "All projects have package.json" | Content projects, docs repos don't have code dependencies |262| "I'll skip AGENTS.md for simple projects" | Even simple projects benefit from documented patterns |263| "Constitution is only for code projects" | ALL projects need principles (quality, style, structure) |264| "Generic best practices are enough" | Project-specific patterns are what make AGENTS.md valuable |265| "I can infer everything from README" | READMEs often incomplete - inspect actual files |266267## Quick Reference268269| Project Type | Key Discovery | Constitution Focus |270|--------------|---------------|-------------------|271| **Technical** | Package manager, tech stack, code patterns | Code quality, tech constraints, testing |272| **Content** | Content structure, frontmatter, assets | Style, tone, structure, publishing |273| **Documentation** | Doc organization, cross-references | Accuracy, consistency, completeness |274| **Mixed** | Both code and content patterns | Both technical and content standards |275276## Success Indicators277278Analysis is complete when:279- ✅ Project type correctly identified280- ✅ Key directories and organization patterns discovered281- ✅ File naming and structure conventions documented282- ✅ AGENTS.md created with project-specific best practices283- ✅ Constitution created or verified284- ✅ Report generated with actionable next steps285- ✅ No assumptions made without evidence286287## Output288289**Created Files:**290```291.claude/292└── AGENTS.md # Project-specific AI agent best practices293294.specify/memory/295└── constitution.md # Project principles (created or updated)296```297298**Analysis Report:**299- Project classification300- Structure and conventions301- Standards documentation302- Recommendations and next steps303304## Related Skills305306- **speckit-constitution** - Create/update project constitution (invoked automatically)307- **speckit** - Full spec-driven development workflow (suggested next step for features)308- **brainstorming** - Explore requirements before making changes