Language and Framework Detection Prompt for Multi-Language Repos

This prompt is designed for AI coding agents that must orient themselves inside a polyglot repository—a codebase containing multiple programming languages, each potentially with its own build system, package manager, and framework conventions. The primary job-to-be-done is reliable language-to-directory mapping with framework version detection, so the agent can select the correct tooling, interpret project conventions, and avoid applying Python linting rules to a Go service directory. The ideal user is an AI engineer or platform developer building a coding agent harness that needs a structured, machine-readable repository overview before any file modification, test execution, or dependency analysis can safely proceed.

Use this prompt when an agent first enters an unfamiliar repository and must answer: which languages are present, where do they live, which frameworks are in use, and what versions are declared. The prompt expects access to a file listing or directory tree, the contents of standard config files (package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, Gemfile, build.gradle, pom.xml, etc.), and optionally a README or build documentation. The output should be a structured mapping—typically JSON—that associates each detected language with its root directories, framework hints, and version constraints. This mapping becomes input to downstream prompts for build system identification, dependency graph traversal, and test runner discovery.

Do not use this prompt when the repository is known to be single-language, when the agent already has a reliable language map from a prior discovery step, or when the task is narrowly scoped to a single file where language detection can be inferred from the file extension alone. This prompt is also inappropriate for repositories where the primary challenge is not language detection but rather monorepo tooling coordination (e.g., Nx, Turborepo, Bazel), which requires a separate build system identification prompt. For repositories with embedded domain-specific languages (DSLs)—such as SQL inside Python, JSX inside JavaScript, or template languages inside server-side files—the harness must include post-processing logic to classify the host language as primary and the embedded DSL as a secondary notation, not a separate language entry. The next step after running this prompt is to feed the language map into a build system identification prompt and a dependency graph traversal prompt, ensuring the agent's understanding of the repository is layered and verifiable.

The prompt below is designed to be dropped into an agent harness that has already gathered a file listing, key config file contents, and directory structure from the target repository. It expects the agent to have read access to files like package.json, requirements.txt, go.mod, Cargo.toml, Gemfile, pom.xml, build.gradle, and CMakeLists.txt. The prompt instructs the model to produce a structured mapping of detected languages to directories, along with framework and version hints extracted from those config files. Use square-bracket placeholders to inject the specific file contents and directory listing your agent has collected.

textCopy
You are analyzing a multi-language codebase to produce a language-to-directory mapping with framework and version hints.

## INPUT

### Directory Listing
[DIRECTORY_LISTING]

### Config File Contents
[CONFIG_FILE_CONTENTS]

## TASK

1. Identify every programming language present in the repository based on file extensions, config files, and build artifacts.
2. For each language, list the directories where that language is the primary or significant secondary language.
3. For each language, extract framework and version hints from the provided config files. Examples:
   - Node.js: Express version from package.json dependencies
   - Python: Django/Flask version from requirements.txt or pyproject.toml
   - Go: Module path and Go version from go.mod
   - Rust: Crate dependencies from Cargo.toml
   - Ruby: Rails version from Gemfile
   - Java: Spring Boot version from pom.xml or build.gradle
4. Flag any directories that contain generated code, vendored dependencies, or build outputs that should be excluded from language analysis.
5. Flag any files where the primary language is ambiguous (e.g., a `.js` file that is actually TypeScript with JSX, or embedded DSLs within a host language file).

## OUTPUT SCHEMA

Return a JSON object with this structure:
{
  "languages": [
    {
      "language": "string",
      "primary_directories": ["string"],
      "secondary_directories": ["string"],
      "frameworks": [
        {
          "name": "string",
          "version_hint": "string or null",
          "source_file": "string"
        }
      ],
      "build_tool": "string or null",
      "package_manager": "string or null",
      "confidence": "high|medium|low"
    }
  ],
  "excluded_directories": [
    {
      "path": "string",
      "reason": "generated|vendored|build_output|other"
    }
  ],
  "ambiguous_files": [
    {
      "path": "string",
      "detected_as": "string",
      "ambiguity": "string"
    }
  ]
}

## CONSTRAINTS

- Do not guess framework versions. If a version is not explicitly present in a config file, set version_hint to null.
- If a directory contains multiple languages, list it under the primary language and note it as a secondary directory for others.
- Treat `.git`, `node_modules`, `vendor`, `__pycache__`, `target`, `build`, `dist`, and similar directories as excluded by default.
- If you cannot determine a language with high confidence, mark it as low confidence and explain why in the ambiguity section.

To adapt this template, replace [DIRECTORY_LISTING] with the output of find . -type d or ls -R from the repository root, truncated to a reasonable depth. Replace [CONFIG_FILE_CONTENTS] with the concatenated contents of all discovered config files, each prefixed with its path. If your agent discovers config files iteratively, you can split this into two prompts: first detect config file paths, then feed only those files into this prompt. For very large repositories, consider chunking by top-level directory and merging results with a deduplication step.

The language and framework detection prompt is designed to be called early in a repository exploration pipeline, before any code modification or deeper analysis tasks. It should be wired as a stateless, read-only step that takes a directory listing, a set of config file contents, and optionally a sample of source file extensions as input. The output is a structured mapping of directories to detected languages and frameworks with version hints. This mapping becomes a critical input for downstream agent decisions: which linter to run, which package manager to invoke, which test framework to use, and which coding conventions to apply. Because the prompt operates on file-level signals rather than executing code, it is safe to run in automated pipelines without sandboxing, but the harness must validate the output before any tool selection or code generation depends on it.

Integration pattern: The harness should collect the repository's top-level and second-level directory structure using find . -maxdepth 2 -type d or an equivalent tree walk, then extract the contents of known config files (package.json, Cargo.toml, go.mod, requirements.txt, pyproject.toml, Gemfile, build.gradle, pom.xml, Makefile, Dockerfile, .github/workflows/*.yml, etc.). These are passed into the prompt's [CONFIG_FILES] placeholder as a mapping of file paths to their raw contents. The [DIRECTORY_LISTING] placeholder receives the directory tree. Model choice: Use a fast, cost-effective model for this classification task (GPT-4o-mini, Claude Haiku, or equivalent) since it requires pattern matching on well-known file signatures rather than deep reasoning. Validation layer: After the model returns its JSON output, run a deterministic post-processor that checks: (1) every directory in the input listing appears in the output mapping or is explicitly classified as non-code (e.g., vendor/, node_modules/, .git/), (2) detected languages are in an allowed enum, (3) version strings match expected patterns (semver, date-based, or commit hashes), and (4) no directory is assigned conflicting primary languages without an explicit polyglot flag. Failed validations should trigger a retry with the validation errors appended to the prompt as [PREVIOUS_ERRORS].

Failure modes to instrument: The most common production failure is missed secondary languages in directories that contain embedded DSLs (e.g., SQL in Python files, JSX in JavaScript, template languages inside HTML). Log a warning when a directory contains files with extensions that don't match the detected primary language. A second failure mode is generated code misclassification—directories like dist/, build/, or generated/ may contain compiled or transpiled output in a different language than the source. The harness should exclude these directories from the input listing using a configurable ignore list. Retry logic: If validation fails, retry once with the error details injected into the prompt. If the second attempt also fails, fall back to a deterministic file-extension-based classifier and flag the directory for human review. Logging and observability: Record the input directory count, the number of languages detected, validation pass/fail status, retry count, and the model's latency. Attach the full prompt and response to the trace for debugging classification disagreements. Human review gate: For repositories with more than five detected languages or any detection confidence below a configurable threshold (default 0.7), route the output to a human reviewer before downstream agents consume it. This prevents a misclassified monorepo from cascading errors into build, test, or deployment steps.

Tool integration: This prompt is a pure classification step and does not require tool use, RAG, or external API calls. However, the harness should expose the validated output as a structured object that downstream agent tools can query: get_language_for_directory(path), get_framework_for_directory(path), get_package_manager_for_directory(path). These accessors prevent agents from re-running detection or making assumptions based on file extensions alone. Testing the harness: Before deploying, run the full pipeline against a curated set of 20-30 open-source repositories spanning monorepos, polyglot projects, single-language repos, and repos with generated code. Measure precision and recall against a manually labeled ground truth. Flag any repository where the pipeline disagrees with the ground truth for root-cause analysis. This eval suite should be re-run whenever the prompt template, model version, or validation rules change.