claude-md-master
---
name: claude-md-master
description: Master skill for CLAUDE.md lifecycle - create, update, improve with repo-verified content and multi-module support. Use when creating or updating CLAUDE.md files.
---
# CLAUDE.md Master (Create/Update/Improver)
## When to use
- User asks to create, improve, update, or standardize CLAUDE.md files.
## Core rules
- Only include info verified in repo or config.
- Never include secrets, tokens, credentials, or user data.
- Never include task-specific or temporary instructions.
- Keep concise: root <= 200 lines, module <= 120 lines.
- Use bullets; avoid long prose.
- Commands must be copy-pasteable and sourced from repo docs/scripts/CI.
- Skip empty sections; avoid filler.
## Mandatory inputs (analyze before generating)
- Build/package config relevant to detected stack (root + modules).
- Static analysis config used in repo (if present).
- Actual module structure and source patterns (scan real dirs/files).
- Representative source roots per module to extract:
package/feature structure, key types, and annotations in use.
## Discovery (fast + targeted)
1. Locate existing CLAUDE.md variants: `CLAUDE.md`, `.claude.md`, `.claude.local.md`.
2. Identify stack and entry points via minimal reads:
- `README.md`, relevant `docs/*`
- Build/package files (see stack references)
- Runtime/config: `Dockerfile`, `docker-compose.yml`, `.env.example`, `config/*`
- CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*`
3. Extract commands only if they exist in repo scripts/config/docs.
4. Detect multi-module structure:
- Android/Gradle: read `settings.gradle` or `settings.gradle.kts` includes.
- iOS: detect multiple targets/workspaces in `*.xcodeproj`/`*.xcworkspace`.
- If more than one module/target has `src/` or build config, plan module CLAUDE.md files.
5. For each module candidate, read its build file + minimal docs to capture
module-specific purpose, entry points, and commands.
6. Scan source roots for:
- Top-level package/feature folders and layer conventions.
- Key annotations/types in use (per stack reference).
- Naming conventions used in the codebase.
7. Capture non-obvious workflows/gotchas from docs or code patterns.
Performance:
- Prefer file listing + targeted reads.
- Avoid full-file reads when a section or symbol is enough.
- Skip large dirs: `node_modules`, `vendor`, `build`, `dist`.
## Stack-specific references (Pattern 2)
Read the relevant reference only when detection signals appear:
- Android/Gradle → `references/android.md`
- iOS/Xcode/Swift → `references/ios.md`
- PHP → `references/php.md`
- Go → `references/go.md`
- React (web) → `references/react-web.md`
- React Native → `references/react-native.md`
- Rust → `references/rust.md`
- Python → `references/python.md`
- Java/JVM → `references/java.md`
- Node tooling → `references/node.md`
- .NET/C# → `references/dotnet.md`
- Dart/Flutter → `references/flutter.md`
- Ruby/Rails → `references/ruby.md`
- Elixir/Erlang → `references/elixir.md`
- C/C++/CMake → `references/cpp.md`
- Other/Unknown → `references/generic.md` (fallback when no specific reference matches)
If multiple stacks are detected, read multiple references.
If no stack is recognized, use the generic reference.
## Multi-module output policy (mandatory when detected)
- Always create a root `CLAUDE.md`.
- Also create `CLAUDE.md` inside each meaningful module/target root.
- "Meaningful" = has its own build config and `src/` (or equivalent).
- Skip tooling-only dirs like `buildSrc`, `gradle`, `scripts`, `tools`.
- Module file must be module-specific and avoid duplication:
- Include purpose, key paths, entry points, module tests, and module
commands (if any).
- Reference shared info via `@/CLAUDE.md`.
## Business module CLAUDE.md policy (all stacks)
For monorepo business logic directories (`src/`, `lib/`, `packages/`, `internal/`):
- Create `CLAUDE.md` for modules with >5 files OR own README
- Skip utility-only dirs: `Helper`, `Utils`, `Common`, `Shared`, `Exception`, `Trait`, `Constants`
- Layered structure not required; provide module info regardless of architecture
- Max 120 lines per module CLAUDE.md
- Reference root via `@/CLAUDE.md` for shared architecture/patterns
- Include: purpose, structure, key classes, dependencies, entry points
## Mandatory output sections (per module CLAUDE.md)
Include these sections if detected in codebase (skip only if not present):
- **Feature/component inventory**: list top-level dirs under source root
- **Core/shared modules**: utility, common, or shared code directories
- **Navigation/routing structure**: navigation graphs, routes, or routers
- **Network/API layer pattern**: API clients, endpoints, response wrappers
- **DI/injection pattern**: modules, containers, or injection setup
- **Build/config files**: module-specific configs (proguard, manifests, etc.)
See stack-specific references for exact patterns to detect and report.
## Update workflow (must follow)
1. Propose targeted additions only; show diffs per file.
2. Ask for approval before applying updates:
**Cursor IDE:**
Use the AskQuestion tool with these options:
- id: "approval"
- prompt: "Apply these CLAUDE.md updates?"
- options: [{"id": "yes", "label": "Yes, apply"}, {"id": "no", "label": "No, cancel"}]
**Claude Code (Terminal):**
Output the proposed changes and ask:
"Do you approve these updates? (yes/no)"
Stop and wait for user response before proceeding.
**Other Environments (Fallback):**
If no structured question tool is available:
1. Display proposed changes clearly
2. Ask: "Do you approve these updates? Reply 'yes' to apply or 'no' to cancel."
3. Wait for explicit user confirmation before proceeding
3. Apply updates, preserving custom content.
If no CLAUDE.md exists, propose a new file for approval.
## Content extraction rules (mandatory)
- From codebase only:
- Extract: type/class/annotation names used, real path patterns,
naming conventions.
- Never: hardcoded values, secrets, API keys, business-specific logic.
- Never: code snippets in Do/Do Not rules.
## Verification before writing
- [ ] Every rule references actual types/paths from codebase
- [ ] No code examples in Do/Do Not sections
- [ ] Patterns match what's actually in the codebase (not outdated)
## Content rules
- Include: commands, architecture summary, key paths, testing, gotchas, workflow quirks.
- Exclude: generic best practices, obvious info, unverified statements.
- Use `@path/to/file` imports to avoid duplication.
- Do/Do Not format is optional; keep only if already used in the file.
- Avoid code examples except short copy-paste commands.
## Existing file strategy
Detection:
- If `<!-- Generated by claude-md-editor skill -->` exists → subsequent run
- Else → first run
First run + existing file:
- Backup `CLAUDE.md` → `CLAUDE.md.bak`
- Use `.bak` as a source and extract only reusable, project-specific info
- Generate a new concise file and add the marker
Subsequent run:
- Preserve custom sections and wording unless outdated or incorrect
- Update only what conflicts with current repo state
- Add missing sections only if they add real value
Never modify `.claude.local.md`.
## Output
After updates, print a concise report:
```
## CLAUDE.md Update Report
- /CLAUDE.md [CREATED | BACKED_UP+CREATED | UPDATED]
- /<module>/CLAUDE.md [CREATED | UPDATED]
- Backups: list any `.bak` files
```
## Validation checklist
- Description is specific and includes trigger terms
- No placeholders remain
- No secrets included
- Commands are real and copy-pasteable
- Report-first rule respected
- References are one level deep
FILE:README.md
# claude-md-master
Master skill for the CLAUDE.md lifecycle: create, update, and improve files
using repo-verified data, with multi-module support and stack-specific rules.
## Overview
- Goal: produce accurate, concise `CLAUDE.md` files from real repo data
- Scope: root + meaningful modules, with stack-specific detection
- Safeguards: no secrets, no filler, explicit approval before writes
## How the AI discovers and uses this skill
- Discovery: the tool learns this skill because it exists in the
repo skills catalog (installed/available in the environment)
- Automatic use: when a request includes "create/update/improve
CLAUDE.md", the tool selects this skill as the best match
- Manual use: the operator can explicitly invoke `/claude-md-master`
to force this workflow
- Run behavior: it scans repo docs/config/source, proposes changes,
and waits for explicit approval before writing files
## Audience
- AI operators using skills in Cursor/Claude Code
- Maintainers who evolve the rules and references
## What it does
- Generates or updates `CLAUDE.md` with verified, repo-derived content
- Enforces strict safety and concision rules (no secrets, no filler)
- Detects multi-module repos and produces module-level `CLAUDE.md`
- Uses stack-specific references to capture accurate patterns
## When to use
- A user asks to create, improve, update, or standardize `CLAUDE.md`
- A repo needs consistent, verified guidance for AI workflows
## Inputs required (must be analyzed)
- Repo docs: `README.md`, `docs/*` (if present)
- Build/config files relevant to detected stack(s)
- Runtime/config: `Dockerfile`, `.env.example`, `config/*` (if present)
- CI: `.github/workflows/*`, `.gitlab-ci.yml`, `.circleci/*` (if present)
- Source roots to extract real structure, types, annotations, naming
## Output
- Root `CLAUDE.md` (always)
- Module `CLAUDE.md` for meaningful modules (build config + `src/`)
- Concise update report listing created/updated files and backups
## Workflow (high level)
1. Locate existing `CLAUDE.md` variants and detect first vs. subsequent run
2. Identify stack(s) and multi-module structure
3. Read relevant docs/configs/CI for real commands and workflow
4. Scan source roots for structure, key types, annotations, patterns
5. Generate root + module files, avoiding duplication via `@/CLAUDE.md`
6. Request explicit approval before applying updates
7. Apply changes and print the update report
## Core rules and constraints
- Only include info verified in repo; never add secrets
- Keep concise: root <= 200 lines, module <= 120 lines
- Commands must be real and copy-pasteable from repo docs/scripts/CI
- Skip empty sections; avoid generic guidance
- Never modify `.claude.local.md`
- Avoid code examples in Do/Do Not sections
## Multi-module policy (summary)
- Always create root `CLAUDE.md`
- Create module-level files only for meaningful modules
- Skip tooling-only dirs (e.g., `buildSrc`, `gradle`, `scripts`, `tools`)
- Business modules get their own file when >5 files or own README
## References (stack-specific guides)
Each reference defines detection signals, pre-gen sources, codebase scan
targets, mandatory output items, command sources, and key paths.
- `references/android.md` — Android/Gradle
- `references/ios.md` — iOS/Xcode/Swift
- `references/react-web.md` — React web apps
- `references/react-native.md` — React Native
- `references/node.md` — Node tooling (generic)
- `references/python.md` — Python
- `references/java.md` — Java/JVM
- `references/dotnet.md` — .NET (C#/F#)
- `references/go.md` — Go
- `references/rust.md` — Rust
- `references/flutter.md` — Dart/Flutter
- `references/ruby.md` — Ruby/Rails
- `references/php.md` — PHP (Laravel/Symfony/CI/Phalcon)
- `references/elixir.md` — Elixir/Erlang
- `references/cpp.md` — C/C++
- `references/generic.md` — Fallback when no stack matches
## Extending the skill
- Add a new `references/<stack>.md` using the same template
- Keep detection signals and mandatory outputs specific and verifiable
- Do not introduce unverified commands or generic advice
## Quality checklist
- Every rule references actual types/paths from the repo
- No placeholders remain
- No secrets included
- Commands are real and copy-pasteable
- Report-first rule respected; references are one level deep
FILE:references/android.md
# Android (Gradle)
## Detection signals
- `settings.gradle` or `settings.gradle.kts`
- `build.gradle` or `build.gradle.kts`
- `gradle.properties`
- `gradle/libs.versions.toml`
- `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `app/src/main/AndroidManifest.xml`
## Multi-module signals
- Multiple `include(...)` or `includeBuild(...)` entries in `settings.gradle*`
- More than one module dir with `build.gradle*` and `src/`
- Common module roots like `feature/`, `core/`, `library/` (if present)
## Before generating, analyze these sources
- `settings.gradle` or `settings.gradle.kts`
- `build.gradle` or `build.gradle.kts` (root and modules)
- `gradle/libs.versions.toml`
- `gradle.properties`
- `config/detekt/detekt.yml` (if present)
- `app/src/main/AndroidManifest.xml` (or module manifests)
## Codebase scan (Android-specific)
- Source roots per module: `*/src/main/java/`, `*/src/main/kotlin/`
- Package tree for feature/layer folders (record only if present):
`features/`, `core/`, `common/`, `data/`, `domain/`, `presentation/`,
`ui/`, `di/`, `navigation/`, `network/`
- Annotation usage (record only if present):
Hilt (`@HiltAndroidApp`, `@AndroidEntryPoint`, `@HiltViewModel`,
`@Module`, `@InstallIn`, `@Provides`, `@Binds`),
Compose (`@Composable`, `@Preview`),
Room (`@Entity`, `@Dao`, `@Database`),
WorkManager (`@HiltWorker`, `ListenableWorker`, `CoroutineWorker`),
Serialization (`@Serializable`, `@Parcelize`),
Retrofit (`@GET`, `@POST`, `@PUT`, `@DELETE`, `@Body`, `@Query`)
- Navigation patterns (record only if present): `NavHost`, `composable`
## Mandatory output (Android module CLAUDE.md)
Include these if detected (list actual names found):
- **Features inventory**: list dirs under `features/` (e.g., homepage, payment, auth)
- **Core modules**: list dirs under `core/` (e.g., data, network, localization)
- **Navigation graphs**: list `*Graph.kt` or `*Navigator*.kt` files
- **Hilt modules**: list `@Module` classes or `di/` package contents
- **Retrofit APIs**: list `*Api.kt` interfaces
- **Room databases**: list `@Database` classes
- **Workers**: list `@HiltWorker` classes
- **Proguard**: mention `proguard-rules.pro` if present
## Command sources
- README/docs or CI invoking Gradle wrapper
- Repo scripts that call `./gradlew`
- `./gradlew assemble`, `./gradlew test`, `./gradlew lint` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `app/src/main/`, `app/src/main/res/`
- `app/src/main/java/`, `app/src/main/kotlin/`
- `app/src/test/`, `app/src/androidTest/`
FILE:references/cpp.md
# C / C++
## Detection signals
- `CMakeLists.txt`
- `meson.build`
- `Makefile`
- `conanfile.*`, `vcpkg.json`
- `compile_commands.json`
- `src/`, `include/`
## Multi-module signals
- `CMakeLists.txt` with `add_subdirectory(...)`
- Multiple `CMakeLists.txt` or `meson.build` in subdirs
- `libs/`, `apps/`, or `modules/` with their own build files
## Before generating, analyze these sources
- `CMakeLists.txt` / `meson.build` / `Makefile`
- `conanfile.*`, `vcpkg.json` (if present)
- `compile_commands.json` (if present)
- `src/`, `include/`, `tests/`, `libs/`
## Codebase scan (C/C++-specific)
- Source roots: `src/`, `include/`, `tests/`, `libs/`
- Library/app split (record only if present):
`src/lib`, `src/app`, `src/bin`
- Namespaces and class prefixes (record only if present)
- CMake targets (record only if present):
`add_library`, `add_executable`
## Mandatory output (C/C++ module CLAUDE.md)
Include these if detected (list actual names found):
- **Libraries**: list library targets
- **Executables**: list executable targets
- **Headers**: list public header directories
- **Modules/components**: list subdirectories with build files
- **Dependencies**: list Conan/vcpkg dependencies (if any)
## Command sources
- README/docs or CI invoking `cmake`, `ninja`, `make`, or `meson`
- Repo scripts that call build tools
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `include/`
- `tests/`, `libs/`
FILE:references/dotnet.md
# .NET (C# / F#)
## Detection signals
- `*.sln`
- `*.csproj`, `*.fsproj`, `*.vbproj`
- `global.json`
- `Directory.Build.props`, `Directory.Build.targets`
- `nuget.config`
- `Program.cs`
- `Startup.cs`
- `appsettings*.json`
## Multi-module signals
- `*.sln` with multiple project entries
- Multiple `*.*proj` files under `src/` and `tests/`
- `Directory.Build.*` managing shared settings across projects
## Before generating, analyze these sources
- `*.sln`, `*.csproj` / `*.fsproj` / `*.vbproj`
- `Directory.Build.props`, `Directory.Build.targets`
- `global.json`, `nuget.config`
- `Program.cs` / `Startup.cs`
- `appsettings*.json`
## Codebase scan (.NET-specific)
- Source roots: `src/`, `tests/`, project folders with `*.csproj`
- Layer folders (record only if present):
`Controllers`, `Services`, `Repositories`, `Domain`, `Infrastructure`
- ASP.NET attributes (record only if present):
`[ApiController]`, `[Route]`, `[HttpGet]`, `[HttpPost]`, `[Authorize]`
- EF Core usage (record only if present):
`DbContext`, `Migrations`, `[Key]`, `[Table]`
## Mandatory output (.NET module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list `[ApiController]` classes
- **Services**: list service classes
- **Repositories**: list repository classes
- **Entities**: list EF Core entity classes
- **DbContext**: list database context classes
- **Middleware**: list custom middleware
- **Configuration**: list config sections or options classes
## Command sources
- README/docs or CI invoking `dotnet`
- Repo scripts like `build.ps1`, `build.sh`
- `dotnet run`, `dotnet test` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `tests/`
- `appsettings*.json`
- `Controllers/`, `Models/`, `Views/`, `wwwroot/`
FILE:references/elixir.md
# Elixir / Erlang
## Detection signals
- `mix.exs`, `mix.lock`
- `config/config.exs`
- `lib/`, `test/`
- `apps/` (umbrella)
- `rel/`
## Multi-module signals
- Umbrella with `apps/` containing multiple `mix.exs`
- Root `mix.exs` with `apps_path`
## Before generating, analyze these sources
- Root `mix.exs`, `mix.lock`
- `config/config.exs`
- `apps/*/mix.exs` (umbrella)
- `lib/`, `test/`, `rel/`
## Codebase scan (Elixir-specific)
- Source roots: `lib/`, `test/`, `apps/*/lib` (umbrella)
- Phoenix structure (record only if present):
`lib/*_web/`, `controllers`, `views`, `channels`, `routers`
- Ecto usage (record only if present):
`schema`, `Repo`, `migrations`
- Contexts/modules (record only if present):
`lib/*/` context modules and `*_context.ex`
## Mandatory output (Elixir module CLAUDE.md)
Include these if detected (list actual names found):
- **Contexts**: list context modules
- **Schemas**: list Ecto schema modules
- **Controllers**: list Phoenix controller modules
- **Channels**: list Phoenix channel modules
- **Workers**: list background job modules (Oban, etc.)
- **Umbrella apps**: list apps under umbrella (if any)
## Command sources
- README/docs or CI invoking `mix`
- Repo scripts that call `mix`
- Only include commands present in repo
## Key paths to mention (only if present)
- `lib/`, `test/`, `config/`
- `apps/`, `rel/`
FILE:references/flutter.md
# Dart / Flutter
## Detection signals
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `lib/`
- `android/`, `ios/`, `web/`, `macos/`, `windows/`, `linux/`
## Multi-module signals
- `melos.yaml` (Flutter monorepo)
- Multiple `pubspec.yaml` under `packages/`, `apps/`, or `plugins/`
## Before generating, analyze these sources
- `pubspec.yaml`, `pubspec.lock`
- `analysis_options.yaml`
- `melos.yaml` (if monorepo)
- `lib/`, `test/`, and platform folders (`android/`, `ios/`, etc.)
## Codebase scan (Flutter-specific)
- Source roots: `lib/`, `test/`
- Entry point (record only if present): `lib/main.dart`
- Layer folders (record only if present):
`features/`, `core/`, `data/`, `domain/`, `presentation/`
- State management (record only if present):
`Bloc`, `Cubit`, `ChangeNotifier`, `Provider`, `Riverpod`
- Widget naming (record only if present):
`*Screen`, `*Page`
## Mandatory output (Flutter module CLAUDE.md)
Include these if detected (list actual names found):
- **Features**: list dirs under `features/` or `lib/`
- **Core modules**: list dirs under `core/` (if present)
- **State management**: list Bloc/Cubit/Provider setup
- **Repositories**: list repository classes
- **Data sources**: list remote/local data source classes
- **Widgets**: list shared widget directories
## Command sources
- README/docs or CI invoking `flutter`
- Repo scripts that call `flutter` or `dart`
- `flutter run`, `flutter test`, `flutter pub get` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `lib/`, `test/`
- `android/`, `ios/`
FILE:references/generic.md
# Generic / Unknown Stack
Use this reference when no specific stack reference matches.
## Detection signals (common patterns)
- `README.md`, `CONTRIBUTING.md`
- `Makefile`, `Taskfile.yml`, `justfile`
- `Dockerfile`, `docker-compose.yml`
- `.env.example`, `config/`
- CI files: `.github/workflows/`, `.gitlab-ci.yml`, `.circleci/`
## Before generating, analyze these sources
- `README.md` - project overview, setup instructions, commands
- Build/package files in root (any recognizable format)
- `Makefile`, `Taskfile.yml`, `justfile`, `scripts/` (if present)
- CI/CD configs for build/test commands
- `Dockerfile` for runtime info
## Codebase scan (generic)
- Identify source root: `src/`, `lib/`, `app/`, `pkg/`, or root
- Layer folders (record only if present):
`controllers`, `services`, `models`, `handlers`, `utils`, `config`
- Entry points: `main.*`, `index.*`, `app.*`, `server.*`
- Test location: `tests/`, `test/`, `spec/`, `__tests__/`, or co-located
## Mandatory output (generic CLAUDE.md)
Include these if detected (list actual names found):
- **Entry points**: main files, startup scripts
- **Source structure**: top-level dirs under source root
- **Config files**: environment, settings, secrets template
- **Build system**: detected build tool and config location
- **Test setup**: test framework and run command
## Command sources
- README setup/usage sections
- `Makefile` targets, `Taskfile.yml` tasks, `justfile` recipes
- CI workflow steps (build, test, lint)
- `scripts/` directory
- Only include commands present in repo
## Key paths to mention (only if present)
- Source root and its top-level structure
- Config/environment files
- Test directory
- Documentation location
- Build output directory
FILE:references/go.md
# Go
## Detection signals
- `go.mod`, `go.sum`, `go.work`
- `cmd/`, `internal/`
- `main.go`
- `magefile.go`
- `Taskfile.yml`
## Multi-module signals
- `go.work` with multiple module paths
- Multiple `go.mod` files in subdirs
- `apps/` or `services/` each with its own `go.mod`
## Before generating, analyze these sources
- `go.work`, `go.mod`, `go.sum`
- `cmd/`, `internal/`, `pkg/` layout
- `Makefile`, `Taskfile.yml`, `magefile.go` (if present)
## Codebase scan (Go-specific)
- Source roots: `cmd/`, `internal/`, `pkg/`, `api/`
- Layer folders (record only if present):
`handler`, `service`, `repository`, `store`, `config`
- Framework markers (record only if present):
`gin`, `echo`, `fiber`, `chi` imports
- Entry points (record only if present):
`cmd/*/main.go`, `main.go`
## Mandatory output (Go module CLAUDE.md)
Include these if detected (list actual names found):
- **Commands**: list binaries under `cmd/`
- **Handlers**: list HTTP handler packages
- **Services**: list service packages
- **Repositories**: list repository or store packages
- **Models**: list domain model packages
- **Config**: list config loading packages
## Command sources
- README/docs or CI
- `Makefile`, `Taskfile.yml`, or repo scripts invoking Go tools
- `go test ./...`, `go run` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `cmd/`, `internal/`, `pkg/`, `api/`
- `tests/` or `*_test.go` layout
FILE:references/ios.md
# iOS (Xcode/Swift)
## Detection signals
- `Package.swift`
- `*.xcodeproj` or `*.xcworkspace`
- `Podfile`, `Cartfile`
- `Project.swift`, `Tuist/`
- `fastlane/Fastfile`
- `*.xcconfig`
- `Sources/` or `Tests/` (SPM layouts)
## Multi-module signals
- Multiple targets/projects in `*.xcworkspace` or `*.xcodeproj`
- `Package.swift` with multiple targets/products
- `Sources/<TargetName>` and `Tests/<TargetName>` layout
- `Project.swift` defining multiple targets (Tuist)
## Before generating, analyze these sources
- `Package.swift` (SPM)
- `*.xcodeproj/project.pbxproj` or `*.xcworkspace/contents.xcworkspacedata`
- `Podfile`, `Cartfile` (if present)
- `Project.swift` / `Tuist/` (if present)
- `fastlane/Fastfile` (if present)
- `Sources/` and `Tests/` layout for targets
## Codebase scan (iOS-specific)
- Source roots: `Sources/`, `Tests/`, `ios/` (if present)
- Feature/layer folders (record only if present):
`Features/`, `Core/`, `Services/`, `Networking/`, `UI/`, `Domain/`, `Data/`
- SwiftUI usage (record only if present):
`@main`, `App`, `@State`, `@StateObject`, `@ObservedObject`,
`@Environment`, `@EnvironmentObject`, `@Binding`
- UIKit/lifecycle (record only if present):
`UIApplicationDelegate`, `SceneDelegate`, `UIViewController`
- Combine/concurrency (record only if present):
`@Published`, `Publisher`, `AnyCancellable`, `@MainActor`, `Task`
## Mandatory output (iOS module CLAUDE.md)
Include these if detected (list actual names found):
- **Features inventory**: list dirs under `Features/` or feature targets
- **Core modules**: list dirs under `Core/`, `Services/`, `Networking/`
- **Navigation**: list coordinators, routers, or SwiftUI navigation files
- **DI container**: list DI setup (Swinject, Factory, manual containers)
- **Network layer**: list API clients or networking services
- **Persistence**: list CoreData models or other storage classes
## Command sources
- README/docs or CI invoking Xcode or Swift tooling
- Repo scripts that call Xcode/Swift tools
- `xcodebuild`, `swift build`, `swift test` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `Sources/`, `Tests/`
- `fastlane/`
- `ios/` (React Native or multi-platform repos)
FILE:references/java.md
# Java / JVM
## Detection signals
- `pom.xml` or `build.gradle*`
- `settings.gradle`, `gradle.properties`
- `mvnw`, `gradlew`
- `gradle/wrapper/gradle-wrapper.properties`
- `src/main/java`, `src/test/java`, `src/main/kotlin`
- `src/main/resources/application.yml`, `src/main/resources/application.properties`
## Multi-module signals
- `settings.gradle*` includes multiple modules
- Parent `pom.xml` with `<modules>` (packaging `pom`)
- Multiple `build.gradle*` or `pom.xml` files in subdirs
## Before generating, analyze these sources
- `settings.gradle*` and `build.gradle*` (if Gradle)
- Parent and module `pom.xml` (if Maven)
- `gradle/libs.versions.toml` (if present)
- `gradle.properties` / `mvnw` / `gradlew`
- `src/main/resources/application.yml|application.properties` (if present)
## Codebase scan (Java/JVM-specific)
- Source roots: `src/main/java`, `src/main/kotlin`, `src/test/java`, `src/test/kotlin`
- Package/layer folders (record only if present):
`controller`, `service`, `repository`, `domain`, `model`, `dto`, `config`, `client`
- Framework annotations (record only if present):
`@SpringBootApplication`, `@RestController`, `@Controller`, `@Service`,
`@Repository`, `@Component`, `@Configuration`, `@Bean`, `@Transactional`
- Persistence/validation (record only if present):
`@Entity`, `@Table`, `@Id`, `@OneToMany`, `@ManyToOne`, `@Valid`, `@NotNull`
- Entry points (record only if present):
`*Application` classes with `main`
## Mandatory output (Java/JVM module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list `@RestController` or `@Controller` classes
- **Services**: list `@Service` classes
- **Repositories**: list `@Repository` classes or JPA interfaces
- **Entities**: list `@Entity` classes
- **Configuration**: list `@Configuration` classes
- **Security**: list security config or auth filters
- **Profiles**: list Spring profiles in use
## Command sources
- Maven/Gradle wrapper scripts
- README/docs or CI
- `./mvnw spring-boot:run`, `./gradlew bootRun` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/main/java`, `src/test/java`
- `src/main/kotlin`, `src/test/kotlin`
- `src/main/resources`, `src/test/resources`
- `src/main/java/**/controller`, `src/main/java/**/service`, `src/main/java/**/repository`
FILE:references/node.md
# Node Tooling (generic)
## Detection signals
- `package.json`
- `package-lock.json`, `pnpm-lock.yaml`, `yarn.lock`
- `.nvmrc`, `.node-version`
- `tsconfig.json`
- `.npmrc`, `.yarnrc.yml`
- `next.config.*`, `nuxt.config.*`
- `nest-cli.json`, `svelte.config.*`, `astro.config.*`
## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`, `rush.json`
- Root `package.json` with `workspaces`
- Multiple `package.json` under `apps/`, `packages/`
## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
`nx.json`, `turbo.json`, `rush.json`)
- `apps/*/package.json`, `packages/*/package.json` (if monorepo)
- `tsconfig.json` or `jsconfig.json`
- Framework config: `next.config.*`, `nuxt.config.*`, `nest-cli.json`,
`svelte.config.*`, `astro.config.*` (if present)
## Codebase scan (Node-specific)
- Source roots: `src/`, `lib/`, `apps/`, `packages/`
- Folder patterns (record only if present):
`routes`, `controllers`, `services`, `middlewares`, `handlers`,
`utils`, `config`, `models`, `schemas`
- Framework markers (record only if present):
Express (`express()`, `Router`), Koa (`new Koa()`),
Fastify (`fastify()`), Nest (`@Controller`, `@Module`, `@Injectable`)
- Full-stack layouts (record only if present):
Next/Nuxt (`pages/`, `app/`, `server/`)
## Mandatory output (Node module CLAUDE.md)
Include these if detected (list actual names found):
- **Routes/pages**: list route files or page components
- **Controllers/handlers**: list controller or handler files
- **Services**: list service classes or modules
- **Middlewares**: list middleware files
- **Models/schemas**: list data models or validation schemas
- **State management**: list store setup (Redux, Zustand, etc.)
- **API clients**: list external API client modules
## Command sources
- `package.json` scripts
- README/docs or CI
- `npm|yarn|pnpm` script usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `lib/`
- `tests/`
- `apps/`, `packages/` (monorepos)
- `pages/`, `app/`, `server/`, `api/`
- `controllers/`, `services/`
FILE:references/php.md
# PHP
## Detection signals
- `composer.json`, `composer.lock`
- `public/index.php`
- `artisan`, `spark`, `bin/console` (framework entry points)
- `phpunit.xml`, `phpstan.neon`, `phpstan.neon.dist`, `psalm.xml`
- `config/app.php`
- `routes/web.php`, `routes/api.php`
- `config/packages/` (Symfony)
- `app/Config/` (CI4)
- `ext-phalcon` in composer.json (Phalcon)
- `phalcon/ide-stubs`, `phalcon/devtools` (Phalcon)
## Multi-module signals
- `modules/` or `app/Modules/` (HMVC style)
- `app/Config/Modules.php`, `app/Config/Autoload.php` (CI4)
- Multiple PSR-4 roots in `composer.json`
- Multiple `composer.json` under `packages/` or `apps/`
- `apps/` with subdirectories containing `Module.php` or `controllers/`
## Before generating, analyze these sources
- `composer.json`, `composer.lock`
- `config/` and `routes/` (framework configs)
- `app/Config/*` (CI4)
- `modules/` or `app/Modules/` (if HMVC)
- `phpunit.xml`, `phpstan.neon*`, `psalm.xml` (if present)
- `bin/worker.php`, `bin/console.php` (CLI entry points)
## Codebase scan (PHP-specific)
- Source roots: `app/`, `src/`, `modules/`, `packages/`, `apps/`
- Laravel structure (record only if present):
`app/Http/Controllers`, `app/Models`, `database/migrations`,
`routes/*.php`, `resources/views`
- Symfony structure (record only if present):
`src/Controller`, `src/Entity`, `config/packages`, `templates`
- CodeIgniter structure (record only if present):
`app/Controllers`, `app/Models`, `app/Views`, `app/Config/Routes.php`,
`app/Database/Migrations`
- Phalcon structure (record only if present):
`apps/*/controllers/`, `apps/*/Module.php`, `models/`
- Attributes/annotations (record only if present):
`#[Route]`, `#[Entity]`, `#[ORM\\Column]`
## Business module discovery
Scan these paths based on detected framework:
- Laravel: `app/Services/`, `app/Domains/`, `app/Modules/`, `packages/`
- Symfony: `src/` top-level directories
- CodeIgniter: `app/Modules/`, `modules/`
- Phalcon: `src/`, `apps/*/`
- Generic: `src/`, `lib/`
For each path:
- List top 5-10 largest modules by file count
- For each significant module (>5 files), note its purpose if inferable from name
- Identify layered patterns if present: `*/Repository/`, `*/Service/`, `*/Controller/`, `*/Action/`
## Module-level CLAUDE.md signals
Scan these paths for significant modules (framework-specific):
- `src/` - Symfony, Phalcon, custom frameworks
- `app/Services/`, `app/Domains/` - Laravel domain-driven
- `app/Modules/`, `modules/` - Laravel/CI4 HMVC
- `packages/` - Laravel internal packages
- `apps/` - Phalcon multi-app
Create `<path>/<Module>/CLAUDE.md` when:
- Threshold: module has >5 files OR has own `README.md`
- Skip utility dirs: `Helper/`, `Exception/`, `Trait/`, `Contract/`, `Interface/`, `Constants/`, `Support/`
- Layered structure not required; provide module info regardless of architecture
### Module CLAUDE.md content (max 120 lines)
- Purpose: 1-2 sentence module description
- Structure: list subdirectories (Service/, Repository/, etc.)
- Key classes: main service/manager/action classes
- Dependencies: other modules this depends on (via use statements)
- Entry points: main public interfaces/facades
- Framework-specific: ServiceProvider (Laravel), Module.php (Phalcon/CI4)
## Worker/Job detection
- `bin/worker.php` or similar worker entry points
- `*/Job/`, `*/Jobs/`, `*/Worker/` directories
- Queue config files (`queue.php`, `rabbitmq.php`, `amqp.php`)
- List job classes if present
## API versioning detection
- `routes_v*.php` or `routes/v*/` patterns
- `controllers/v*/` directory structure
- Note current/active API version from route files or config
## Mandatory output (PHP module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list controller directories/classes
- **Models**: list model/entity classes or directory
- **Services**: list service classes or directory
- **Repositories**: list repository classes or directory
- **Routes**: list route files and versioning pattern
- **Migrations**: mention migrations dir and file count
- **Middleware**: list middleware classes
- **Views/templates**: mention view engine and layout
- **Workers/Jobs**: list job classes if present
- **Business modules**: list top modules from detected source paths by size
## Command sources
- `composer.json` scripts
- README/docs or CI
- `php artisan`, `bin/console` usage in docs/scripts
- `bin/worker.php` commands
- Only include commands present in repo
## Key paths to mention (only if present)
- `app/`, `src/`, `apps/`
- `public/`, `routes/`, `config/`, `database/`
- `app/Http/`, `resources/`, `storage/` (Laravel)
- `templates/` (Symfony)
- `app/Controllers/`, `app/Views/` (CI4)
- `apps/*/controllers/`, `models/` (Phalcon)
- `tests/`, `tests/acceptance/`, `tests/unit/`
FILE:references/python.md
# Python
## Detection signals
- `pyproject.toml`
- `requirements.txt`, `requirements-dev.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`
- `setup.py`, `setup.cfg`
- `settings.py`, `urls.py` (Django)
## Multi-module signals
- Multiple `pyproject.toml`/`setup.py`/`setup.cfg` in subdirs
- `packages/` or `apps/` each with its own package config
- Django-style `apps/` with multiple `apps.py` (if present)
## Before generating, analyze these sources
- `pyproject.toml` or `setup.py` / `setup.cfg`
- `requirements*.txt`, `Pipfile`, `poetry.lock`
- `tox.ini`, `pytest.ini`
- `manage.py`, `settings.py`, `urls.py` (if Django)
- Package roots under `src/`, `app/`, `packages/` (if present)
## Codebase scan (Python-specific)
- Source roots: `src/`, `app/`, `packages/`, `tests/`
- Folder patterns (record only if present):
`api`, `routers`, `views`, `services`, `repositories`,
`models`, `schemas`, `utils`, `config`
- Django structure (record only if present):
`apps.py`, `models.py`, `views.py`, `urls.py`, `migrations/`, `settings.py`
- FastAPI/Flask markers (record only if present):
`FastAPI()`, `APIRouter`, `@app.get`, `@router.post`,
`Flask(__name__)`, `Blueprint`
- Type model usage (record only if present):
`pydantic.BaseModel`, `TypedDict`, `dataclass`
## Mandatory output (Python module CLAUDE.md)
Include these if detected (list actual names found):
- **Routers/views**: list API router or view files
- **Services**: list service modules
- **Models/schemas**: list data models (Pydantic, SQLAlchemy, Django)
- **Repositories**: list repository or DAO modules
- **Migrations**: mention migrations dir
- **Middleware**: list middleware classes
- **Django apps**: list installed apps (if Django)
## Command sources
- `pyproject.toml` tool sections
- README/docs or CI
- Repo scripts invoking Python tools
- `python manage.py`, `pytest`, `tox` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `app/`, `scripts/`
- `templates/`, `static/`
- `tests/`
FILE:references/react-native.md
# React Native
## Detection signals
- `package.json` with `react-native`
- `react-native.config.js`
- `metro.config.js`
- `ios/`, `android/`
- `babel.config.js`, `app.json`, `app.config.*`
- `eas.json`, `expo` in `package.json`
## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Root `package.json` with `workspaces`
- `packages/` or `apps/` each with `package.json`
## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
`nx.json`, `turbo.json`)
- `react-native.config.js`, `metro.config.js`
- `ios/` and `android/` native folders
- `app.json` / `app.config.*` / `eas.json` (if Expo)
## Codebase scan (React Native-specific)
- Source roots: `src/`, `app/`
- Entry points (record only if present):
`index.js`, `index.ts`, `App.tsx`
- Native folders (record only if present): `ios/`, `android/`
- Navigation/state (record only if present):
`react-navigation`, `redux`, `mobx`
- Native module patterns (record only if present):
`NativeModules`, `TurboModule`
## Mandatory output (React Native module CLAUDE.md)
Include these if detected (list actual names found):
- **Screens/navigators**: list screen components and navigators
- **Components**: list shared component directories
- **Services/API**: list API client modules
- **State management**: list store setup
- **Native modules**: list custom native modules
- **Platform folders**: mention ios/ and android/ setup
## Command sources
- `package.json` scripts
- README/docs or CI
- Native build files in `ios/` and `android/`
- `expo` script usage in docs/scripts (if Expo)
- Only include commands present in repo
## Key paths to mention (only if present)
- `ios/`, `android/`
- `src/`, `app/`
FILE:references/react-web.md
# React (Web)
## Detection signals
- `package.json`
- `src/`, `public/`
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json`
- `turbo.json`
- `app/` or `pages/` (Next.js)
## Multi-module signals
- `pnpm-workspace.yaml`, `lerna.json`, `nx.json`, `turbo.json`
- Root `package.json` with `workspaces`
- `apps/` and `packages/` each with `package.json`
## Before generating, analyze these sources
- Root `package.json` and workspace config (`pnpm-workspace.yaml`, `lerna.json`,
`nx.json`, `turbo.json`)
- `apps/*/package.json`, `packages/*/package.json` (if monorepo)
- `vite.config.*`, `next.config.*`, `webpack.config.*`
- `tsconfig.json` / `jsconfig.json`
## Codebase scan (React web-specific)
- Source roots: `src/`, `app/`, `pages/`, `components/`, `hooks/`, `services/`
- Folder patterns (record only if present):
`routes`, `store`, `state`, `api`, `utils`, `assets`
- Routing markers (record only if present):
React Router (`Routes`, `Route`), Next (`app/`, `pages/`)
- State management (record only if present):
`redux`, `zustand`, `recoil`
- Naming conventions (record only if present):
hooks `use*`, components PascalCase
## Mandatory output (React web module CLAUDE.md)
Include these if detected (list actual names found):
- **Pages/routes**: list page components or route files
- **Components**: list shared component directories
- **Hooks**: list custom hooks
- **Services/API**: list API client modules
- **State management**: list store setup (Redux, Zustand, etc.)
- **Utils**: list utility modules
## Command sources
- `package.json` scripts
- README/docs or CI
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `public/`
- `app/`, `pages/`, `components/`
- `hooks/`, `services/`
- `apps/`, `packages/` (monorepos)
FILE:references/ruby.md
# Ruby / Rails
## Detection signals
- `Gemfile`, `Gemfile.lock`
- `Rakefile`
- `config.ru`
- `bin/rails` or `bin/rake`
- `config/application.rb`
- `config/routes.rb`
## Multi-module signals
- Multiple `Gemfile` or `.gemspec` files in subdirs
- `gems/`, `packages/`, or `engines/` with separate gem specs
- Multiple Rails apps under `apps/` (each with `config/application.rb`)
## Before generating, analyze these sources
- `Gemfile`, `Gemfile.lock`, and any `.gemspec`
- `config/application.rb`, `config/routes.rb`
- `Rakefile` / `bin/rails` (if present)
- `engines/`, `gems/`, `apps/` (if multi-app/engine setup)
## Codebase scan (Ruby/Rails-specific)
- Source roots: `app/`, `lib/`, `engines/`, `gems/`
- Rails layers (record only if present):
`app/models`, `app/controllers`, `app/views`, `app/jobs`, `app/services`
- Config and initializers (record only if present):
`config/routes.rb`, `config/application.rb`, `config/initializers/`
- ActiveRecord/migrations (record only if present):
`db/migrate`, `ActiveRecord::Base`
- Tests (record only if present): `spec/`, `test/`
## Mandatory output (Ruby module CLAUDE.md)
Include these if detected (list actual names found):
- **Controllers**: list controller classes
- **Models**: list ActiveRecord models
- **Services**: list service objects
- **Jobs**: list background job classes
- **Routes**: summarize key route namespaces
- **Migrations**: mention db/migrate count
- **Engines**: list mounted engines (if any)
## Command sources
- README/docs or CI invoking `bundle`, `rails`, `rake`
- `Rakefile` tasks
- `bundle exec` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `app/`, `config/`, `db/`
- `app/controllers/`, `app/models/`, `app/views/`
- `spec/` or `test/`
FILE:references/rust.md
# Rust
## Detection signals
- `Cargo.toml`, `Cargo.lock`
- `rust-toolchain.toml`
- `src/main.rs`, `src/lib.rs`
- Workspace members in `Cargo.toml`, `crates/`
## Multi-module signals
- `[workspace]` with `members` in `Cargo.toml`
- Multiple `Cargo.toml` under `crates/` or `apps/`
## Before generating, analyze these sources
- Root `Cargo.toml`, `Cargo.lock`
- `rust-toolchain.toml` (if present)
- Workspace `Cargo.toml` in `crates/` or `apps/`
- `src/main.rs` / `src/lib.rs`
## Codebase scan (Rust-specific)
- Source roots: `src/`, `crates/`, `tests/`, `examples/`
- Module layout (record only if present):
`lib.rs`, `main.rs`, `mod.rs`, `src/bin/*`
- Serde usage (record only if present):
`#[derive(Serialize, Deserialize)]`
- Async/runtime (record only if present):
`tokio`, `async-std`
- Web frameworks (record only if present):
`axum`, `actix-web`, `warp`
## Mandatory output (Rust module CLAUDE.md)
Include these if detected (list actual names found):
- **Crates**: list workspace crates with purpose
- **Binaries**: list `src/bin/*` or `[[bin]]` targets
- **Modules**: list top-level `mod` declarations
- **Handlers/routes**: list web handler modules (if web app)
- **Models**: list domain model modules
- **Config**: list config loading modules
## Command sources
- README/docs or CI
- Repo scripts invoking `cargo`
- `cargo test`, `cargo run` usage in docs/scripts
- Only include commands present in repo
## Key paths to mention (only if present)
- `src/`, `crates/`
- `tests/`, `examples/`, `benches/`
Comprehensive Image Analysis Report
{
"meta": {
"source_image": "user_provided_image",
"analysis_timestamp": "2024-07-30T12:00:00Z",
"analysis_model": "image_to_json_v1.0",
"overall_confidence": 0.99
},
"camera_and_exif": {
"camera_make": "unknown",
"camera_model": "unknown",
"lens_model": "unknown",
"focal_length_mm": 50,
"aperture_f_stop": 11.0,
"shutter_speed_s": 0.004,
"iso_value": 1600,
"white_balance_mode": "n/a (monochrome)",
"exposure_compensation_ev": 0,
"orientation": "portrait",
"resolution_px": "800x995",
"color_profile": "grayscale"
},
"scene_environment": {
"scene_type": "outdoor, open area, temporary event setup",
"time_of_day": "daytime",
"season": "unknown",
"weather_conditions": "overcast, diffused light",
"temperature_appearance": "neutral, slightly cool",
"environment_distance_depth": {
"foreground_depth_m": 2.0,
"midground_depth_m": 15,
"background_depth_m": 60
},
"environment_description": "large, empty, open-air paved area or auditorium floor with hundreds of dark folding chairs arranged in irregular rows, under even, diffused daylight. A solitary figure is seated in the foreground, facing the chairs.",
"ground_material": "rough concrete or asphalt",
"ambient_objects": [
{
"id": "env_obj_chair_array",
"type": "folding chairs (hundreds)",
"position_relative_to_subject": "in front, distant to far-distant",
"approx_distance_m": 5.0,
"height_m": 0.8,
"width_m": 0.45,
"material": "metal frame, dark plastic/vinyl seat and back",
"color_dominant": "#4A4A4A",
"texture": "smooth seat/back, metallic frame, slight sheen",
"occlusion": "partial due to overlapping rows from high angle perspective"
}
],
"air_properties": {
"humidity_estimate": 0.6,
"haze_level": 0.15,
"fog_density": 0.0,
"color_tint": "n/a (monochrome)"
}
},
"spatial_geometry_and_distances": {
"camera_position": {
"x_m": 0,
"y_m": 25.0,
"z_m": -8.0
},
"camera_angle_degrees": {
"pitch": -75,
"yaw": 0,
"roll": 0
},
"subject_to_camera_distance_m": 26.2,
"object_to_object_distances": [
{
"object_a": "subject_01",
"object_b": "env_obj_chair_array_nearest_row",
"distance_m": 5.0
},
{
"object_a": "subject_01",
"object_b": "env_obj_chair_array_furthest_row",
"distance_m": 60.0
}
],
"height_reference_scale": {
"known_reference": "person",
"height_m": 1.75,
"pixel_to_meter_ratio": 0.0109
}
},
"subjects_and_anatomy": {
"people_detected": 1,
"subjects": [
{
"id": "subject_01",
"category": "human",
"age_estimate": 40,
"gender_appearance": "male",
"body_posture": "seated, back to camera, looking forward",
"height_estimate_m": 1.75,
"shoulder_width_m": 0.48,
"body_proportions": {
"head_height_ratio": 0.125,
"torso_to_leg_ratio": 0.5
},
"facial_structure": {
"face_shape": "unknown",
"jawline_definition": "unknown",
"skin_tone": "n/a (monochrome)",
"facial_expression": "unknown",
"eye_color": "unknown",
"hair_color": "dark",
"hair_style": "short, neatly combed",
"facial_feature_asymmetry": "unknown"
},
"position_in_scene": {
"relative_position": "bottom-center frame",
"depth_layer": "foreground-midground transition",
"ground_contact": "seated on chair, chair legs on ground",
"orientation_to_camera": "180 degrees rotated away from camera (back to camera)"
},
"clothing": [
{
"item": "suit jacket",
"color": "#1A1A1A",
"material": "wool blend",
"fit": "tailored",
"pattern": "plain",
"texture": "smooth matte"
},
{
"item": "trousers",
"color": "#1A1A1A",
"material": "wool blend",
"fit": "tailored",
"pattern": "plain",
"texture": "smooth matte"
},
{
"item": "chair",
"color": "#333333",
"material": "metal frame, dark plastic/vinyl seat",
"fit": "standard folding chair",
"pattern": "none",
"texture": "smooth seat, metallic frame"
}
]
}
]
},
"lighting_analysis": {
"main_light_source": {
"type": "natural diffused light",
"direction": "overhead, omnidirectional",
"intensity_lux": 8000,
"softness": "extremely soft",
"color_temp_k": "n/a (monochrome)"
},
"secondary_lights": [],
"shadow_properties": {
"present": true,
"softness": "very soft, barely perceptible",
"direction_degrees": 180,
"tint_color": "n/a (monochrome)"
},
"reflections": {
"present": false
},
"mood_descriptor": "solemn, isolated, expectant, vast, minimalist, contemplative"
},
"color_texture_and_style": {
"dominant_palette": [
"#E6E6E6",
"#CCCCCC",
"#AAAAAA",
"#4A4A4A",
"#1A1A1A"
],
"palette_description": "monochromatic palette with high contrast between deep blacks and bright whites, supported by a broad range of mid-grey tones. Overall impression is stark and graphic.",
"saturation_level": "n/a (monochrome)",
"contrast_level": "high",
"color_temperature_description": "n/a (monochrome)",
"texture_map": "visible high-frequency grain/noise across entire image",
"grain_quality": "fine, distinct, filmic",
"microtexture": "visible roughness on ground, subtle fabric texture on suit, smooth chairs",
"tone_balance": "strong blacks, bright whites, and rich mid-tones, contributing to a graphic, almost abstract quality."
},
"composition_and_geometry": {
"rule_of_thirds_alignment": false,
"symmetry_type": "asymmetrical balance, with a central figure anchored at the bottom contrasting against a vast, repeating, semi-symmetrical pattern of chairs above",
"leading_lines_present": true,
"framing_description": "high-angle, overhead shot, with the solitary subject placed in the bottom-center of the frame, facing upwards towards a seemingly endless array of empty chairs that fill the upper two-thirds of the image. The composition emphasizes scale, isolation, and anticipation.",
"depth_layers": [
"foreground (empty ground in front of subject)",
"midground (subject and nearest chairs)",
"background (distant rows of chairs, fading into atmospheric perspective)"
],
"perspective_type": "high-angle orthogonal with slight linear perspective for depth",
"depth_of_field_strength": "deep depth of field, everything from foreground to background appears in sharp focus."
},
"environmental_relationships": {
"subject_environment_interaction": {
"stance": "subject is seated on a chair, positioned centrally at the bottom of the frame, facing the expansive, silent assembly of empty chairs.",
"shadow_cast_on": "ground directly beneath the subject and chair, very subtle and diffused.",
"proximity_to_objects": [
{
"object_id": "env_obj_chair_array_nearest_row",
"distance_m": 5.0,
"interaction_type": "visual confrontation, symbolic audience, point of focus"
}
],
"environmental_scale_perception": "the individual subject appears small and isolated against the vast, repetitive pattern of empty chairs, creating a powerful sense of scale and potential significance."
},
"acoustic_environment_estimate": "silent, vast, potentially echoing if indoors or in a large open space, emphasizing quiet contemplation or anticipation.",
"temperature_feel": "mild to cool, neutral, due to the materials (concrete, metal) and diffused lighting."
},
"output_and_generation_parameters": {
"target_similarity": 0.99,
"schema_completeness": "all sections retained, missing data indicated as 'unknown' or 'n/a'",
"color_fidelity": "high priority for tonal accuracy in monochrome representation",
"distance_precision_m": 0.5,
"pose_accuracy": 0.05,
"facial_geometry_precision": 0.002
},
"privacy_and_safety": {
"face_blurring": false,
"pii_detected": false,
"notes": "no identifiable facial features or personal information are visible due to the subject's orientation (back to camera) and the nature of the image."
}
}
Comprehensive repository analysis
{
"task": "comprehensive_repository_analysis",
"objective": "Conduct exhaustive analysis of entire codebase to identify, prioritize, fix, and document ALL verifiable bugs, security vulnerabilities, and critical issues across any technology stack",
"analysis_phases": [
{
"phase": 1,
"name": "Repository Discovery & Mapping",
"steps": [
{
"step": "1.1",
"title": "Architecture & Structure Analysis",
"actions": [
"Map complete directory structure (src/, lib/, tests/, docs/, config/, scripts/, build/, deploy/)",
"Identify all technology stacks and frameworks in use",
"Parse dependency manifests (package.json, requirements.txt, go.mod, pom.xml, Gemfile, Cargo.toml, composer.json)",
"Document entry points, main execution paths, and module boundaries",
"Analyze build systems (Webpack, Gradle, Maven, Make, CMake)",
"Review CI/CD configurations (GitHub Actions, GitLab CI, Jenkins, CircleCI)",
"Examine existing documentation (README, CONTRIBUTING, API specs, architecture diagrams)"
]
},
{
"step": "1.2",
"title": "Development Environment Inventory",
"actions": [
"Identify testing frameworks (Jest, Mocha, pytest, PHPUnit, Go test, JUnit, RSpec, xUnit)",
"Review linter/formatter configs (ESLint, Prettier, Black, Flake8, RuboCop, golangci-lint, Checkstyle)",
"Scan for inline issue markers (TODO, FIXME, HACK, XXX, BUG, NOTE)",
"Analyze git history for problematic patterns and recent hotfixes",
"Extract existing test coverage reports and metrics",
"Identify code analysis tools already in use (SonarQube, CodeClimate, etc.)"
]
}
]
},
{
"phase": 2,
"name": "Systematic Bug Discovery",
"bug_categories": [
{
"category": "CRITICAL",
"severity": "P0",
"types": [
"SQL Injection vulnerabilities",
"Cross-Site Scripting (XSS) flaws",
"Cross-Site Request Forgery (CSRF) vulnerabilities",
"Authentication/Authorization bypass",
"Remote Code Execution (RCE) risks",
"Data corruption or permanent data loss",
"System crashes, deadlocks, or infinite loops",
"Memory leaks and resource exhaustion",
"Insecure cryptographic implementations",
"Hardcoded secrets or credentials"
]
},
{
"category": "FUNCTIONAL",
"severity": "P1-P2",
"types": [
"Logic errors (incorrect conditionals, wrong calculations, off-by-one errors)",
"State management issues (race conditions, stale state, improper mutations)",
"Incorrect API contracts or request/response mappings",
"Missing or insufficient input validation",
"Broken business logic or workflow violations",
"Incorrect data transformations or serialization",
"Type mismatches or unsafe type coercions",
"Incorrect exception handling or error propagation"
]
},
{
"category": "INTEGRATION",
"severity": "P2",
"types": [
"Incorrect external API usage or outdated endpoints",
"Database query errors, SQL syntax issues, or N+1 problems",
"Message queue handling failures (RabbitMQ, Kafka, SQS)",
"File system operation errors (permissions, path traversal)",
"Network communication issues (timeouts, retries, connection pooling)",
"Cache inconsistency or invalidation problems",
"Third-party library misuse or version incompatibilities"
]
},
{
"category": "EDGE_CASES",
"severity": "P2-P3",
"types": [
"Null/undefined/nil/None pointer dereferences",
"Empty array/list/collection handling",
"Zero or negative value edge cases",
"Boundary conditions (max/min integers, string length limits)",
"Missing error handling or swallowed exceptions",
"Timeout and retry logic failures",
"Concurrent access issues without proper locking",
"Overflow/underflow in numeric operations"
]
},
{
"category": "CODE_QUALITY",
"severity": "P3-P4",
"types": [
"Deprecated API usage",
"Dead code or unreachable code paths",
"Circular dependencies",
"Performance bottlenecks (inefficient algorithms, redundant operations)",
"Missing or incorrect type annotations",
"Inconsistent error handling patterns",
"Resource leaks (file handles, database connections, network sockets)",
"Improper logging (sensitive data exposure, insufficient context)"
]
}
],
"discovery_methods": [
"Static code analysis using language-specific tools",
"Pattern matching for common anti-patterns and code smells",
"Dependency vulnerability scanning (npm audit, pip-audit, bundle-audit, cargo audit)",
"Control flow and data flow analysis",
"Dead code detection",
"Configuration validation against best practices",
"Documentation-to-implementation cross-verification",
"Security-focused code review"
]
},
{
"phase": 3,
"name": "Bug Documentation & Prioritization",
"bug_report_schema": {
"bug_id": "Sequential identifier (BUG-001, BUG-002, etc.)",
"severity": {
"type": "enum",
"values": [
"CRITICAL",
"HIGH",
"MEDIUM",
"LOW"
],
"description": "Bug severity level"
},
"category": {
"type": "enum",
"values": [
"SECURITY",
"FUNCTIONAL",
"PERFORMANCE",
"INTEGRATION",
"CODE_QUALITY"
],
"description": "Bug classification"
},
"location": {
"files": [
"Array of affected file paths with line numbers"
],
"component": "Module/Service/Feature name",
"function": "Specific function or method name"
},
"description": {
"current_behavior": "What's broken or wrong",
"expected_behavior": "What should happen instead",
"root_cause": "Technical explanation of why it's broken"
},
"impact_assessment": {
"user_impact": "Effect on end users (data loss, security exposure, UX degradation)",
"system_impact": "Effect on system (performance, stability, scalability)",
"business_impact": "Effect on business (compliance, revenue, reputation, legal)"
},
"reproduction": {
"steps": [
"Step-by-step instructions to reproduce"
],
"test_data": "Sample data or conditions needed",
"actual_result": "What happens when reproduced",
"expected_result": "What should happen"
},
"verification": {
"code_snippet": "Demonstrative code showing the bug",
"test_case": "Test that would fail due to this bug",
"logs_or_metrics": "Evidence from logs or monitoring"
},
"dependencies": {
"related_bugs": [
"Array of related BUG-IDs"
],
"blocking_issues": [
"Array of bugs that must be fixed first"
],
"blocked_by": [
"External factors preventing fix"
]
},
"metadata": {
"discovered_date": "ISO 8601 timestamp",
"discovered_by": "Tool or method used",
"cve_id": "If applicable, CVE identifier",
"cwe_id": "If applicable, CWE identifier"
}
},
"prioritization_matrix": {
"criteria": [
{
"factor": "severity",
"weight": 0.4,
"scale": "CRITICAL=100, HIGH=70, MEDIUM=40, LOW=10"
},
{
"factor": "user_impact",
"weight": 0.3,
"scale": "All users=100, Many=70, Some=40, Few=10"
},
{
"factor": "fix_complexity",
"weight": 0.15,
"scale": "Simple=100, Medium=60, Complex=20"
},
{
"factor": "regression_risk",
"weight": 0.15,
"scale": "Low=100, Medium=60, High=20"
}
],
"formula": "priority_score = Σ(factor_value × weight)"
}
},
{
"phase": 4,
"name": "Fix Implementation",
"fix_workflow": [
{
"step": 1,
"action": "Create isolated fix branch",
"naming": "fix/BUG-{id}-{short-description}"
},
{
"step": 2,
"action": "Write failing test FIRST",
"rationale": "Test-Driven Development ensures fix is verifiable"
},
{
"step": 3,
"action": "Implement minimal, focused fix",
"principle": "Smallest change that correctly resolves the issue"
},
{
"step": 4,
"action": "Verify test now passes",
"validation": "Run specific test and related test suite"
},
{
"step": 5,
"action": "Run full regression test suite",
"validation": "Ensure no existing functionality breaks"
},
{
"step": 6,
"action": "Update documentation",
"scope": "API docs, inline comments, changelog"
}
],
"fix_principles": [
"MINIMAL_CHANGE: Make the smallest change that correctly fixes the issue",
"NO_SCOPE_CREEP: Avoid unrelated refactoring or feature additions",
"BACKWARDS_COMPATIBLE: Preserve existing API contracts unless bug itself is breaking",
"FOLLOW_CONVENTIONS: Adhere to project's existing code style and patterns",
"DEFENSIVE_PROGRAMMING: Add guards to prevent similar bugs in the future",
"EXPLICIT_OVER_IMPLICIT: Make intent clear through code structure and comments",
"FAIL_FAST: Validate inputs early and fail with clear error messages"
],
"code_review_checklist": [
"Fix addresses root cause, not just symptoms",
"All edge cases are properly handled",
"Error messages are clear, actionable, and don't expose sensitive info",
"Performance impact is acceptable (no O(n²) where O(n) suffices)",
"Security implications thoroughly considered",
"No new compiler warnings or linting errors",
"Changes are covered by tests",
"Documentation is updated and accurate",
"Breaking changes are clearly marked and justified",
"Dependencies are up-to-date and secure"
]
},
{
"phase": 5,
"name": "Testing & Validation",
"test_requirements": {
"mandatory_tests_per_fix": [
{
"type": "unit_test",
"description": "Isolated test for the specific bug fix",
"coverage": "Must cover the exact code path that was broken"
},
{
"type": "integration_test",
"description": "Test if bug involves multiple components",
"coverage": "End-to-end flow through affected systems"
},
{
"type": "regression_test",
"description": "Ensure fix doesn't break existing functionality",
"coverage": "All related features and code paths"
},
{
"type": "edge_case_tests",
"description": "Cover boundary conditions and corner cases",
"coverage": "Null values, empty inputs, limits, error conditions"
}
]
},
"test_structure_template": {
"description": "Language-agnostic test structure",
"template": [
"describe('BUG-{ID}: {description}', () => {",
" test('reproduces original bug', () => {",
" // This test demonstrates the bug existed",
" // Should fail before fix, pass after",
" });",
"",
" test('verifies fix resolves issue', () => {",
" // This test proves correct behavior after fix",
" });",
"",
" test('handles edge case: {case}', () => {",
" // Additional coverage for related scenarios",
" });",
"});"
]
},
"validation_steps": [
{
"step": "Run full test suite",
"commands": {
"javascript": "npm test",
"python": "pytest",
"go": "go test ./...",
"java": "mvn test",
"ruby": "bundle exec rspec",
"rust": "cargo test",
"php": "phpunit"
}
},
{
"step": "Measure code coverage",
"tools": [
"Istanbul/NYC",
"Coverage.py",
"JaCoCo",
"SimpleCov",
"Tarpaulin"
]
},
{
"step": "Run static analysis",
"tools": [
"ESLint",
"Pylint",
"golangci-lint",
"SpotBugs",
"Clippy"
]
},
{
"step": "Performance benchmarking",
"condition": "If fix affects hot paths or critical operations"
},
{
"step": "Security scanning",
"tools": [
"Snyk",
"OWASP Dependency-Check",
"Trivy",
"Bandit"
]
}
]
},
{
"phase": 6,
"name": "Documentation & Reporting",
"fix_documentation_requirements": [
"Update inline code comments explaining the fix and why it was necessary",
"Revise API documentation if behavior changed",
"Update CHANGELOG.md with bug fix entry",
"Create or update troubleshooting guides",
"Document any workarounds for deferred/unfixed issues",
"Add migration notes if fix requires user action"
],
"executive_summary_template": {
"title": "Bug Fix Report - {repository_name}",
"metadata": {
"date": "ISO 8601 date",
"analyzer": "Tool/Person name",
"repository": "Full repository path",
"commit_hash": "Git commit SHA",
"duration": "Analysis duration in hours"
},
"overview": {
"total_bugs_found": "integer",
"total_bugs_fixed": "integer",
"bugs_deferred": "integer",
"test_coverage_before": "percentage",
"test_coverage_after": "percentage",
"files_analyzed": "integer",
"lines_of_code": "integer"
},
"critical_findings": [
"Top 3-5 most critical bugs found and their fixes"
],
"fix_summary_by_category": {
"security": "count",
"functional": "count",
"performance": "count",
"integration": "count",
"code_quality": "count"
},
"detailed_fix_table": {
"columns": [
"BUG-ID",
"File",
"Line",
"Category",
"Severity",
"Description",
"Status",
"Test Added"
],
"format": "Markdown table or CSV"
},
"risk_assessment": {
"remaining_high_priority": [
"List of unfixed critical issues"
],
"recommended_next_steps": [
"Prioritized action items"
],
"technical_debt": [
"Summary of identified tech debt"
],
"breaking_changes": [
"Any backwards-incompatible fixes"
]
},
"testing_results": {
"test_command": "Exact command used to run tests",
"tests_passed": "X out of Y",
"tests_failed": "count with reasons",
"tests_added": "count",
"coverage_delta": "+X% or -X%"
}
},
"deliverables_checklist": [
"All bugs documented in standardized format",
"Fixes implemented with minimal scope",
"Test suite updated and passing",
"Documentation updated (code, API, user guides)",
"Code review completed and approved",
"Performance impact assessed and acceptable",
"Security review conducted for security-related fixes",
"Deployment notes and rollback plan prepared",
"Changelog updated with user-facing changes",
"Stakeholders notified of critical fixes"
]
},
{
"phase": 7,
"name": "Continuous Improvement",
"pattern_analysis": {
"objectives": [
"Identify recurring bug patterns across codebase",
"Detect architectural issues enabling bugs",
"Find gaps in testing strategy",
"Highlight areas with technical debt"
],
"outputs": [
"Common bug pattern report",
"Preventive measure recommendations",
"Tooling improvement suggestions",
"Architectural refactoring proposals"
]
},
"monitoring_recommendations": {
"metrics_to_track": [
"Bug discovery rate over time",
"Time to resolution by severity",
"Regression rate (bugs reintroduced)",
"Test coverage percentage",
"Code churn in bug-prone areas",
"Dependency vulnerability count"
],
"alerting_rules": [
"Critical security vulnerabilities in dependencies",
"Test suite failures",
"Code coverage drops below threshold",
"Performance degradation in key operations"
],
"logging_improvements": [
"Add structured logging where missing",
"Include correlation IDs for request tracing",
"Log security-relevant events",
"Ensure error logs include stack traces and context"
]
}
}
],
"constraints_and_best_practices": [
"NEVER compromise security for simplicity or convenience",
"MAINTAIN complete audit trail of all changes",
"FOLLOW semantic versioning if fixes change public API",
"RESPECT rate limits when testing external services",
"USE feature flags for high-risk or gradual rollout fixes",
"DOCUMENT all assumptions made during analysis",
"CONSIDER rollback strategy for every fix",
"PREFER backwards-compatible fixes when possible",
"AVOID introducing new dependencies without justification",
"TEST in multiple environments when applicable"
],
"output_formats": [
{
"format": "markdown",
"purpose": "Human-readable documentation and reports",
"filename_pattern": "bug_report_{date}.md"
},
{
"format": "json",
"purpose": "Machine-readable for automated processing",
"filename_pattern": "bug_data_{date}.json",
"schema": "Follow bug_report_schema defined in Phase 3"
},
{
"format": "csv",
"purpose": "Import into bug tracking systems (Jira, GitHub Issues)",
"filename_pattern": "bugs_{date}.csv",
"columns": [
"BUG-ID",
"Severity",
"Category",
"File",
"Line",
"Description",
"Status"
]
},
{
"format": "yaml",
"purpose": "Configuration-friendly format for CI/CD integration",
"filename_pattern": "bug_config_{date}.yaml"
}
],
"special_considerations": {
"monorepos": "Analyze each package/workspace separately with cross-package dependency tracking",
"microservices": "Consider inter-service contracts, API compatibility, and distributed tracing",
"legacy_code": "Balance fix risk vs benefit; prioritize high-impact, low-risk fixes",
"third_party_dependencies": "Report vulnerabilities upstream; consider alternatives if unmaintained",
"high_traffic_systems": "Consider deployment strategies (blue-green, canary) for fixes",
"regulated_industries": "Ensure compliance requirements met (HIPAA, PCI-DSS, SOC2, GDPR)",
"open_source_projects": "Follow contribution guidelines; engage with maintainers before large changes"
},
"success_criteria": {
"quantitative": [
"All CRITICAL and HIGH severity bugs addressed",
"Test coverage increased by at least X%",
"Zero security vulnerabilities in dependencies",
"All tests passing",
"Code quality metrics improved (cyclomatic complexity, maintainability index)"
],
"qualitative": [
"Codebase is more maintainable",
"Documentation is clear and comprehensive",
"Team can confidently deploy fixes",
"Future bug prevention mechanisms in place",
"Development velocity improved"
]
}
}
