feat(agents): add language context snippets for 11 non-code file types

Add language context snippets for markdown, yaml, json, sql, dockerfile,
terraform, graphql, protobuf, shell, html, and css. Each snippet follows
the existing typescript.md/python.md pattern with Key Concepts, Notable
File Patterns, Edge Patterns, and Summary Style sections. These snippets
are injected into the architecture analyzer prompt to improve layer
assignments for non-code files.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Lum1104
2026-03-28 18:56:14 +08:00
Unverified
parent 8ac3a2096a
commit e7ebc600aa
11 changed files with 387 additions and 0 deletions
@@ -0,0 +1,37 @@
# CSS Language Prompt Snippet
## Key Concepts
- **Selectors**: Element, class (`.name`), ID (`#name`), attribute (`[attr]`), and pseudo-class (`:hover`) targeting
- **Specificity**: Inline > ID > Class > Element cascade priority determining which rules win
- **Box Model**: `margin`, `border`, `padding`, `content` dimensions controlling element sizing
- **Flexbox**: `display: flex` with `justify-content`, `align-items` for one-dimensional layouts
- **Grid**: `display: grid` with `grid-template-columns/rows` for two-dimensional layouts
- **Custom Properties (Variables)**: `--name: value` with `var(--name)` for reusable design tokens
- **Media Queries**: `@media (max-width: ...)` for responsive design breakpoints
- **SCSS/Sass Features**: Nesting, `$variables`, `@mixin`, `@include`, `@extend`, `@use`, `@forward`
- **CSS Modules**: Scoped class names (`.module.css`) preventing global style collisions
- **Cascade Layers**: `@layer` for explicit control over cascade ordering
## Notable File Patterns
- `*.css` — Standard CSS stylesheets
- `*.scss` / `*.sass` — Sass/SCSS preprocessor files
- `*.less` — Less preprocessor files
- `*.module.css` / `*.module.scss` — CSS Modules (scoped styles)
- `globals.css` / `reset.css` / `normalize.css` — Global base styles
- `tailwind.config.js` — Tailwind CSS configuration (though a JS file)
- `variables.scss` / `_variables.scss` — Design token definitions
## Edge Patterns
- CSS files `configures` the visual appearance of HTML or component files that import them
- SCSS partial files (`_*.scss`) are `depends_on` by the main stylesheet that `@use`s them
- CSS variable definition files `configures` all stylesheets that reference those variables
- CSS Modules are `related` to the component files that import them
## Summary Style
> "Global stylesheet defining CSS custom properties for the design system color palette and typography."
> "Responsive layout styles with flexbox and grid for the dashboard page across 3 breakpoints."
> "SCSS partial defining shared mixins for spacing, shadows, and media query breakpoints."
@@ -0,0 +1,34 @@
# Dockerfile Language Prompt Snippet
## Key Concepts
- **Multi-Stage Builds**: Multiple `FROM` statements to separate build and runtime stages, reducing image size
- **Layer Caching**: Each instruction creates a layer; order instructions from least to most frequently changing for cache efficiency
- **Base Images**: `FROM image:tag` selects the starting image; prefer slim/alpine variants for smaller images
- **COPY vs ADD**: `COPY` for local files (preferred), `ADD` for URLs and tar extraction
- **Build Arguments**: `ARG` for build-time variables, `ENV` for runtime environment variables
- **Health Checks**: `HEALTHCHECK` instruction for container orchestrator readiness probes
- **Entry Point vs CMD**: `ENTRYPOINT` sets the executable, `CMD` provides default arguments
- **User Permissions**: `USER` instruction to run as non-root for security
- **Ignore Patterns**: `.dockerignore` excludes files from the build context (like `.gitignore`)
## Notable File Patterns
- `Dockerfile` — Primary container image definition (at project root)
- `Dockerfile.dev` / `Dockerfile.prod` — Environment-specific Dockerfiles
- `docker-compose.yml` — Multi-container application orchestration
- `docker-compose.override.yml` — Local development overrides
- `.dockerignore` — Build context exclusion patterns
## Edge Patterns
- Dockerfile `deploys` the application entry point it packages (COPY/CMD target)
- docker-compose `depends_on` Dockerfile(s) it references for building
- Dockerfile `depends_on` package manifests (package.json, requirements.txt) it copies for dependency installation
- docker-compose services create `related` edges between co-deployed components
## Summary Style
> "Multi-stage Docker build producing a minimal Node.js production image with N build stages."
> "Docker Compose configuration orchestrating N services with shared networking and persistent volumes."
> "Development Dockerfile with hot-reload support and mounted source volumes."
@@ -0,0 +1,35 @@
# GraphQL Language Prompt Snippet
## Key Concepts
- **Type System**: Strongly typed schema defining the API contract with scalar, object, enum, and union types
- **Queries**: Read operations fetching data with field-level selection (no over-fetching)
- **Mutations**: Write operations for creating, updating, and deleting data
- **Subscriptions**: Real-time data push over WebSocket connections
- **Resolvers**: Functions mapping schema fields to data sources (database, API, cache)
- **Fragments**: Reusable field selections reducing query duplication across operations
- **Directives**: `@deprecated`, `@include`, `@skip` for conditional field inclusion and schema metadata
- **Input Types**: `input` keyword for complex mutation arguments
- **Interfaces and Unions**: Polymorphic types for shared fields across multiple object types
- **Schema Stitching / Federation**: Composing multiple GraphQL services into a unified graph
## Notable File Patterns
- `schema.graphql` / `*.graphql` — Schema definition files
- `*.gql` — Alternative extension for GraphQL files
- `schema/*.graphql` — Split schema files by domain (users.graphql, orders.graphql)
- `*.resolvers.ts` / `*.resolvers.js` — Resolver implementations (TypeScript/JavaScript convention)
- `codegen.yml` — GraphQL Code Generator configuration
## Edge Patterns
- GraphQL schema files `defines_schema` for the resolver code that implements query/mutation handlers
- Type definitions create `related` edges between types connected by field references
- Schema files `defines_schema` for client-side query/mutation files that consume the API
- Codegen config `configures` the schema-to-code generation pipeline
## Summary Style
> "GraphQL schema defining N types, M queries, and K mutations for the user management API."
> "API schema with type definitions for products, orders, and payment processing with pagination."
> "Subscription schema enabling real-time notifications for order status updates."
@@ -0,0 +1,34 @@
# HTML Language Prompt Snippet
## Key Concepts
- **Semantic Elements**: `<main>`, `<nav>`, `<header>`, `<footer>`, `<article>`, `<section>` for meaningful structure
- **Document Structure**: `<!DOCTYPE html>`, `<html>`, `<head>`, `<body>` forming the page skeleton
- **Forms**: `<form>`, `<input>`, `<select>`, `<textarea>` for user data collection with validation attributes
- **Accessibility**: `aria-*` attributes, `role`, `alt` text, and semantic markup for screen readers
- **Meta Tags**: `<meta>` for viewport, charset, description, Open Graph, and SEO metadata
- **Script and Style Loading**: `<script>`, `<link>`, `<style>` for JavaScript and CSS inclusion
- **Data Attributes**: `data-*` custom attributes for storing element-specific data
- **Template Syntax**: Framework-specific templating (`{{ }}` for Jinja/Django, `<%= %>` for ERB)
- **Web Components**: `<template>`, `<slot>`, Custom Elements for encapsulated reusable components
## Notable File Patterns
- `index.html` — Application entry point or SPA shell
- `*.html` / `*.htm` — Static HTML pages
- `templates/**/*.html` — Server-side template files (Django, Jinja2, Go templates)
- `public/index.html` — SPA root document (React, Vue)
- `*.ejs` / `*.hbs` / `*.pug` — Templating engine files
## Edge Patterns
- HTML files `depends_on` JavaScript and CSS files they include via `<script>` and `<link>` tags
- Template HTML files `depends_on` the server-side code that renders them
- HTML entry points are `deploys` targets for build systems and web servers
- HTML files `related` to the components or routes they render
## Summary Style
> "Single-page application shell with viewport meta, CSS reset, and React root mount point."
> "Server-rendered template with navigation, content area, and footer using Django template inheritance."
> "Static landing page with responsive layout, form, and third-party script integrations."
@@ -0,0 +1,34 @@
# JSON Language Prompt Snippet
## Key Concepts
- **Strict Syntax**: No trailing commas, no comments (unlike JSONC or JSON5), double-quoted strings only
- **Data Types**: Objects, arrays, strings, numbers, booleans, and null — no undefined or date types
- **Nested Structure**: Arbitrary nesting depth for hierarchical configuration or data
- **Schema Validation**: JSON Schema (`$schema` keyword) for validating structure and types
- **JSONC**: JSON with Comments variant used by VS Code, tsconfig.json, and other tooling
- **JSON5**: Extended JSON allowing comments, trailing commas, unquoted keys, and more
- **JSON Lines** (`.jsonl`): One JSON object per line for streaming data processing
## Notable File Patterns
- `package.json` — Node.js project manifest with dependencies, scripts, and metadata
- `tsconfig.json` — TypeScript compiler configuration (actually JSONC)
- `.eslintrc.json` — ESLint linting rules and configuration
- `*.schema.json` — JSON Schema definitions for validation
- `composer.json` — PHP Composer project manifest
- `appsettings.json` — .NET application configuration
- `manifest.json` — Browser extension or PWA manifest
## Edge Patterns
- `package.json` `configures` the build toolchain and defines project dependencies
- `tsconfig.json` `configures` TypeScript compilation for all `.ts` files
- JSON Schema files `defines_schema` for API request/response validation
- Config JSON files `configures` the runtime behavior of the application
## Summary Style
> "Node.js project manifest defining N dependencies, build scripts, and project metadata."
> "TypeScript compiler configuration enabling strict mode with path aliases for monorepo packages."
> "JSON Schema defining the request/response structure for the user API endpoint."
@@ -0,0 +1,34 @@
# Markdown Language Prompt Snippet
## Key Concepts
- **Heading Hierarchy**: `#` through `######` for document structure, with h1 as the title
- **Front Matter**: YAML metadata between `---` delimiters at the top of the file
- **Fenced Code Blocks**: Triple backticks with optional language identifier for syntax highlighting
- **Reference-Style Links**: `[text][ref]` with `[ref]: url` definitions, useful for repeated URLs
- **Tables**: Pipe-delimited columns with alignment markers (`:---`, `:---:`, `---:`)
- **Admonitions**: Blockquote-based callouts (`> **Note:**`, `> **Warning:**`) for emphasis
- **Task Lists**: `- [ ]` and `- [x]` for checklists in issue trackers and READMEs
- **HTML Embedding**: Raw HTML allowed inline for features Markdown does not support natively
## Notable File Patterns
- `README.md` — Project overview and entry point for new contributors (high-value)
- `CONTRIBUTING.md` — Contribution guidelines, code style, PR process
- `CHANGELOG.md` — Version history following Keep a Changelog or similar format
- `docs/**/*.md` — Documentation directory with guides, API references, tutorials
- `*.md` in source directories — Co-located documentation for modules or packages
- `ADR-*.md` or `adr/*.md` — Architecture Decision Records
## Edge Patterns
- Markdown files `documents` the code components they describe or reference
- Links to other `.md` files create `related` edges between documentation nodes
- Code block references mentioning file paths may imply `documents` edges to those files
- README files in subdirectories typically `documents` the module at that path
## Summary Style
> "Project overview documentation with N sections covering installation, usage, and API reference."
> "Architecture Decision Record documenting the choice of [technology] for [purpose]."
> "Contributing guide with code style rules, testing requirements, and pull request process."
@@ -0,0 +1,34 @@
# Protobuf Language Prompt Snippet
## Key Concepts
- **Message Types**: `message` blocks defining structured data with typed, numbered fields
- **Field Numbers**: Permanent identifiers (1-536870911) — never reuse deleted numbers for backward compatibility
- **Scalar Types**: `int32`, `int64`, `string`, `bytes`, `bool`, `float`, `double`, and more
- **Enums**: Named integer constants for categorical values
- **Services**: `service` blocks defining RPC (Remote Procedure Call) method signatures
- **Oneof**: Mutually exclusive field groups — only one field in the group can be set
- **Repeated Fields**: `repeated` keyword for list/array fields
- **Maps**: `map<key_type, value_type>` for dictionary/hash fields
- **Packages and Imports**: Namespace organization and cross-file references
- **Proto2 vs Proto3**: Proto3 (current) removes required/optional distinction and defaults all fields
## Notable File Patterns
- `*.proto` — Protocol Buffer definition files
- `proto/**/*.proto` — Organized proto definitions by service or domain
- `buf.yaml` / `buf.gen.yaml` — Buf tool configuration for linting and code generation
- `*_pb2.py` / `*.pb.go` / `*_pb.ts` — Generated code (should be excluded from analysis)
## Edge Patterns
- Protobuf files `defines_schema` for the gRPC service handlers that implement the declared RPCs
- Message type references create `related` edges between proto files sharing types
- Proto `import` statements create `depends_on` edges between proto files
- Generated code files are `depends_on` the proto source that produces them
## Summary Style
> "Protocol Buffer definitions for N message types and M RPC services in the user authentication domain."
> "Shared proto types defining common request/response envelopes and error codes."
> "gRPC service definition with N methods for real-time data streaming and batch processing."
@@ -0,0 +1,36 @@
# Shell Language Prompt Snippet
## Key Concepts
- **Shebang Line**: `#!/bin/bash` or `#!/usr/bin/env bash` specifying the interpreter
- **Variables**: `VAR=value` assignment, `$VAR` or `${VAR}` expansion, no spaces around `=`
- **Functions**: `function name()` or `name()` for reusable command groups
- **Conditionals**: `if [[ condition ]]; then ... fi` with `[[ ]]` for extended tests
- **Loops**: `for item in list`, `while condition`, `until condition` iteration patterns
- **Pipes and Redirection**: `|` for chaining commands, `>` / `>>` / `2>&1` for output redirection
- **Exit Codes**: `$?` captures last command status; `set -e` exits on any failure
- **Strict Mode**: `set -euo pipefail` for robust error handling (exit on error, undefined vars, pipe failures)
- **Command Substitution**: `$(command)` captures command output as a string
- **Here Documents**: `<<EOF ... EOF` for multi-line string input to commands
## Notable File Patterns
- `*.sh` / `*.bash` — Shell script files
- `scripts/*.sh` — Project automation scripts (build, deploy, setup)
- `entrypoint.sh` — Docker container entry point script
- `install.sh` / `setup.sh` — Environment setup scripts
- `.bashrc` / `.bash_profile` / `.zshrc` — Shell configuration files
- `Makefile` — Build automation with Make (though technically its own language)
## Edge Patterns
- Shell scripts `triggers` other scripts or build processes they invoke
- Entry point scripts `deploys` the application they start
- Setup scripts `configures` the development environment
- Build scripts `depends_on` the source files they compile or package
## Summary Style
> "Build automation script compiling TypeScript, running tests, and packaging the release artifact."
> "Docker entry point script handling signal forwarding and graceful shutdown."
> "Environment setup script installing dependencies and configuring development tools."
@@ -0,0 +1,36 @@
# SQL Language Prompt Snippet
## Key Concepts
- **DDL (Data Definition)**: `CREATE TABLE`, `ALTER TABLE`, `DROP TABLE` for schema management
- **DML (Data Manipulation)**: `SELECT`, `INSERT`, `UPDATE`, `DELETE` for data operations
- **Normalization**: Organizing tables to reduce redundancy through 1NF, 2NF, 3NF relationships
- **Foreign Keys**: `REFERENCES` constraints enforcing referential integrity between tables
- **Indexes**: `CREATE INDEX` for query performance optimization on frequently queried columns
- **Migrations**: Numbered, sequential schema changes applied in order for version control
- **Transactions**: `BEGIN`/`COMMIT`/`ROLLBACK` for atomic multi-statement operations
- **Views**: Named queries (`CREATE VIEW`) providing virtual tables for complex joins
- **Stored Procedures**: Server-side functions for encapsulating business logic in the database
- **Constraints**: `NOT NULL`, `UNIQUE`, `CHECK`, `DEFAULT` for data integrity rules
## Notable File Patterns
- `migrations/*.sql` — Numbered migration files (e.g., `001_create_users.sql`, `002_add_orders.sql`)
- `schema.sql` — Full database schema definition (often generated from migrations)
- `seeds/*.sql` — Seed data for development and testing environments
- `*.up.sql` / `*.down.sql` — Reversible migration pairs (up applies, down reverts)
- `init.sql` — Database initialization script for Docker or fresh setup
- `procedures/*.sql` — Stored procedure definitions
## Edge Patterns
- SQL migration files `migrates` the tables they create or alter
- Schema definition files `defines_schema` for the ORM models or data layer code that reads them
- Table definitions create implicit `related` edges between tables connected by foreign keys
- Seed files `depends_on` the migration files that create the tables they populate
## Summary Style
> "Database migration creating the users table with email, name, and authentication columns."
> "Schema definition with N tables covering user management, orders, and payment processing."
> "Seed data populating N tables with development fixtures for testing."
@@ -0,0 +1,38 @@
# Terraform Language Prompt Snippet
## Key Concepts
- **Declarative Infrastructure**: Define desired state; Terraform computes and applies the diff
- **Providers**: Plugins connecting to cloud APIs (AWS, GCP, Azure, Kubernetes, etc.)
- **Resources**: `resource "type" "name"` blocks declaring infrastructure components
- **Data Sources**: `data "type" "name"` blocks reading existing infrastructure state
- **Variables**: `variable` blocks for parameterizing configurations with defaults and validation
- **Outputs**: `output` blocks exposing values for cross-module references or human consumption
- **Modules**: Reusable, composable infrastructure packages with their own variables and outputs
- **State Management**: `.tfstate` files tracking real-world resource mapping (never commit to git)
- **Workspaces**: Isolated state environments for managing dev/staging/prod from one codebase
- **Plan and Apply**: `terraform plan` previews changes, `terraform apply` executes them
## Notable File Patterns
- `main.tf` — Primary resource definitions
- `variables.tf` — Input variable declarations with types and defaults
- `outputs.tf` — Output value definitions
- `providers.tf` — Provider configuration and version constraints
- `backend.tf` — Remote state backend configuration (S3, GCS, etc.)
- `modules/**/*.tf` — Reusable infrastructure modules
- `*.tfvars` — Variable value files for different environments
- `terraform.lock.hcl` — Provider version lock file
## Edge Patterns
- Terraform files `provisions` the infrastructure resources they define
- Module references create `depends_on` edges between terraform files
- Terraform `deploys` application code by referencing container images or deployment targets
- Variable files `configures` the terraform modules they parameterize
## Summary Style
> "Terraform configuration provisioning N AWS resources including VPC, ECS cluster, and RDS instance."
> "Infrastructure module defining a reusable Kubernetes namespace with RBAC and network policies."
> "Variable definitions for N environment-specific settings (region, instance type, scaling)."
@@ -0,0 +1,35 @@
# YAML Language Prompt Snippet
## Key Concepts
- **Indentation-Based Nesting**: Whitespace-sensitive structure (spaces only, no tabs) defining hierarchy
- **Anchors and Aliases**: `&anchor` defines a reusable block, `*anchor` references it to avoid duplication
- **Merge Keys**: `<<: *anchor` merges anchor contents into the current mapping
- **Multi-Line Strings**: Literal block (`|`) preserves newlines, folded block (`>`) joins lines
- **Document Separators**: `---` starts a new document, `...` ends one (multi-document streams)
- **Tags and Types**: `!!str`, `!!int`, `!!bool` for explicit typing; custom tags for application-specific types
- **Flow Style**: Inline JSON-like syntax `{key: value}` and `[item1, item2]` for compact notation
- **Environment Variable Substitution**: `${VAR}` patterns used in docker-compose and CI configs
## Notable File Patterns
- `docker-compose.yml` / `docker-compose.yaml` — Multi-container Docker application definition
- `.github/workflows/*.yml` — GitHub Actions CI/CD workflow definitions
- `.gitlab-ci.yml` — GitLab CI/CD pipeline configuration
- `kubernetes/*.yaml` / `k8s/*.yaml` — Kubernetes resource manifests
- `*.config.yaml` — Application configuration files
- `mkdocs.yml` — MkDocs documentation site configuration
- `serverless.yml` — Serverless Framework configuration
## Edge Patterns
- YAML config files `configures` the code modules they control (e.g., database settings affect data layer)
- CI/CD YAML files `triggers` build and deployment pipelines
- docker-compose YAML `deploys` services and `depends_on` Dockerfiles
- Kubernetes YAML `deploys` and `provisions` application services
## Summary Style
> "Docker Compose configuration defining N services with networking, volumes, and health checks."
> "GitHub Actions workflow running tests on push and deploying to production on merge to main."
> "Kubernetes deployment manifest with N replicas, resource limits, and liveness probes."