Programming projects contain many file types beyond normal source code. These files usually exist because tools need configuration, documentation, dependency metadata, database instructions, deployment rules, API contracts, environment variables, or structured AI prompts. Once you understand which tool reads the file, the file type becomes much easier to understand.
Short Answer
A file type tells the developer and the toolchain what kind of content is inside a file.
It usually answers four questions:
- Is this file configuration?
- Is this file documentation or content?
- Is this file structured data?
- Which tool is supposed to read this file?
| File Type | Main Purpose | Common Reader |
|---|---|---|
.json, .yaml, .toml, .ini | Configuration or structured data | App, framework, DevOps tool |
.xml | Strict structured markup | Maven, Android, SOAP, enterprise tools |
.md, .mdx | Documentation and rich content | Documentation site or blog engine |
.sql | Database schema and queries | Database engine |
.env | Environment variables | Application runtime |
Dockerfile, .dockerignore | Container build rules | Docker |
.sh, .ps1 | Automation scripts | Shell or PowerShell |
.proto, .graphql | API contracts | API tooling |
.lock files | Exact dependency versions | Package manager |
.pem, .crt, .key | Certificates and keys | TLS, SSH, infrastructure tools |
.prompt, .prompty, .poml | AI prompt structure | AI tooling or agent framework |
The extension is not decoration. It is a signal to the toolchain.
The Main Categories
Most non-source programming file types fit into a few practical groups.
- 1ConfigurationControls tools, frameworks, and runtime behavior
- 2ContentStores documentation, articles, and UI text
- 3DataMoves structured information between systems
- 4AutomationRuns build, deploy, and maintenance tasks
- 5ContractsDefines APIs, schemas, and communication formats
- 6Security FilesStores certificates, keys, and secure connection material
A backend project may contain pom.xml, application.properties, .sql, .env, Dockerfile, docker-compose.yml, .gitignore, .md, and lock files.
A frontend or documentation project may contain package.json, tsconfig.json, .mdx, .env, .svg, .json, .yaml, and lock files.
These files are not random. They separate different project responsibilities.
Configuration Files
Configuration files tell tools how to behave.
They are usually not business logic. They are instructions for frameworks, compilers, package managers, deployment systems, and runtime environments.
| File Type | Common File | Purpose |
|---|---|---|
.json | package.json | Node.js package metadata and scripts |
.json | tsconfig.json | TypeScript compiler config |
.js, .mjs, .cjs | next.config.mjs | Next.js configuration |
.yaml, .yml | docker-compose.yml | Multi-container local setup |
.yaml, .yml | GitHub Actions workflow | CI/CD pipeline |
.toml | pyproject.toml | Python project config |
.ini | config.ini | Simple key-value config |
.properties | application.properties | Java / Spring Boot config |
.gradle | build.gradle | Gradle build config |
.env | .env | Runtime environment variables |
Example package.json:
{
"scripts": {
"dev": "next dev",
"build": "next build"
},
"dependencies": {
"next": "^16.0.0",
"react": "^19.0.0"
}
}
Example .env:
DATABASE_URL=postgresql://user:password@localhost:5432/app
PORT=3000
The key difference is ownership. package.json is read by Node.js package managers. tsconfig.json is read by TypeScript. .env is loaded by the application runtime or environment loader.
JSON, YAML, TOML, and INI
These formats are often used for configuration and structured data.
They can store similar information, but they have different trade-offs.
| Format | Strength | Weakness | Common Use |
|---|---|---|---|
| JSON | Strict and machine-friendly | Standard JSON has no comments | APIs, Node config, data exchange |
| YAML | Easy to read for nested config | Indentation mistakes are common | DevOps, CI/CD, Kubernetes |
| TOML | Clear config format | Less common than JSON/YAML | Python, Rust, tool config |
| INI | Very simple key-value style | Weak for complex nested config | Older apps, simple config files |
Example JSON:
{
"name": "backend-service",
"port": 3000
}
Example YAML:
name: backend-service
port: 3000
Example TOML:
name = "backend-service"
port = 3000
Example INI:
name=backend-service
port=3000
JSON is common when machines exchange data. YAML is common when humans write infrastructure config. TOML is common in some modern language ecosystems. INI is common when the config is small and flat.
XML Files
XML means Extensible Markup Language.
XML is a strict markup format that represents structured data with tags.
Example:
<user>
<id>1001</id>
<name>Alex</name>
<role>admin</role>
</user>
XML is verbose, but it has several strengths:
- explicit opening and closing tags
- strict tree structure
- good support for schemas
- mature parser support
- common in older enterprise systems
- common in Java and Android ecosystems
You will often see XML in these places:
| File / Area | Why XML Appears |
|---|---|
pom.xml | Maven uses XML to define Java project builds and dependencies |
| Android layout files | Android historically used XML for UI layouts and app configuration |
| SOAP APIs | SOAP messages are XML-based |
| Enterprise integration | Older enterprise tools often standardize on XML |
| Office document formats | Some document formats use zipped XML internally |
| RSS feeds | Many feeds are XML documents |
| SVG files | SVG is XML-based vector graphics |
A common Java example is Maven's pom.xml.
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>demo-service</artifactId>
<version>1.0.0</version>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
This file tells Maven:
- what the project is called
- what version it is
- what dependencies it needs
- what plugins should run
- how the project should be packaged
The important point: XML is not only for data. In many ecosystems, XML is used as configuration, build definition, UI layout, and message format.
Markdown and MDX Files
Markdown is used for readable documentation.
| File Type | Purpose | Common Use |
|---|---|---|
.md | Plain Markdown | README, docs, notes |
.mdx | Markdown plus JSX components | Blog posts, component docs, interactive documentation |
Example Markdown:
## Installation
Run this from the project root:
```bash
npm install
MDX adds component support.
Example MDX:
```mdx
<CardGrid columns={2}>
<InfoCard title="Measure First">
Find the bottleneck before changing the architecture.
</InfoCard>
<InfoCard title="Fix the Highest Cost">
Optimize the part that creates the most user-visible delay.
</InfoCard>
</CardGrid>
In a normal documentation repo, .md is enough.
In a blog or documentation site that needs custom UI components, .mdx is more useful.
The risk is that MDX can break the build if JSX is invalid or required components are missing.
Database Files
Database-related files define schema, queries, migrations, seed data, and exports.
| File Type | Purpose | Common Use |
|---|---|---|
.sql | SQL commands | Schema, queries, migrations |
.prisma | Prisma schema | Database models and generated client |
.csv | Tabular data | Exports, imports, seed data |
.sqlite, .db | Database file | Local SQLite database |
.dump | Database dump | Backup and restore |
Example SQL migration:
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
This file is usually read by the database engine or migration tool.
A .sql file is not application code, but it can change the structure and behavior of the database. That makes it very important in backend projects.
API Contract Files
API contract files define how systems communicate.
| File Type | Purpose | Common Use |
|---|---|---|
.proto | Protocol Buffers schema | gRPC services |
.graphql | GraphQL schema or query | GraphQL APIs |
.wsdl | Web service definition | SOAP services |
.avsc | Avro schema | Kafka and data pipelines |
.json | OpenAPI document | REST API documentation |
.yaml | OpenAPI document | REST API documentation |
Example .proto:
syntax = "proto3";
service UserService {
rpc GetUser (GetUserRequest) returns (UserResponse);
}
message GetUserRequest {
string id = 1;
}
message UserResponse {
string id = 1;
string email = 2;
}
This file does not implement the service. It defines the contract.
The server and client can generate code from it so both sides agree on the same communication shape.
Automation and Shell Files
Automation files are used to run commands repeatedly and consistently.
| File Type | Purpose | Common Use |
|---|---|---|
.sh | Shell script | Linux/macOS automation |
.ps1 | PowerShell script | Windows automation |
.bat, .cmd | Windows command script | Older Windows automation |
Makefile | Task runner | Build and maintenance commands |
.github/workflows/*.yml | CI/CD workflow | GitHub Actions automation |
Example shell script:
#!/usr/bin/env bash
npm install
npm run build
Example PowerShell script:
npm install
npm run build
These files are useful because they reduce manual repetition.
Instead of remembering ten commands, the team can run one script.
Container and Deployment Files
Deployment files describe how the application runs outside the local machine.
| File Type | Purpose | Common Use |
|---|---|---|
Dockerfile | Build a container image | App containerization |
.dockerignore | Exclude files from Docker build context | Faster, cleaner Docker builds |
docker-compose.yml | Run multiple containers locally | App + database + Redis |
.tf | Terraform config | Cloud infrastructure |
.k8s.yml, .yaml | Kubernetes resources | Deployment, service, ingress |
nginx.conf | Nginx configuration | Reverse proxy, static serving, routing |
Example Dockerfile:
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]
This file is not application logic. It defines how to package and run the application environment.
Dependency and Lock Files
Dependency files tell the project what packages it needs.
Lock files record the exact resolved versions.
| File Type | Ecosystem | Purpose |
|---|---|---|
package.json | Node.js | Declares dependencies and scripts |
package-lock.json | npm | Locks exact dependency tree |
yarn.lock | Yarn | Locks exact dependency tree |
pnpm-lock.yaml | pnpm | Locks exact dependency tree |
pom.xml | Maven / Java | Declares Java dependencies and build config |
build.gradle | Gradle / Java | Declares dependencies and build logic |
requirements.txt | Python | Lists Python packages |
poetry.lock | Python Poetry | Locks exact dependency versions |
go.mod | Go | Declares Go module dependencies |
go.sum | Go | Verifies dependency checksums |
Cargo.toml | Rust | Declares Rust package metadata and dependencies |
Cargo.lock | Rust | Locks exact dependency versions |
Do not delete lock files randomly.
Lock files help make installs reproducible across machines, CI/CD, and production.
Git and Ignore Files
Git-related files control version history and what should not be committed.
| File Type | Purpose |
|---|---|
.gitignore | Tells Git which files to ignore |
.gitattributes | Controls Git behavior for file types |
.gitmodules | Tracks Git submodules |
Example .gitignore:
node_modules
.env
dist
.next
This prevents generated files, dependencies, and secrets from being committed.
A good .gitignore protects the repository from noise and accidental leaks.
Logs, Certificates, and Binary Files
Not every file in a project is source text.
Some files are generated outputs, runtime artifacts, or binary resources.
| File Type | Purpose | Common Use |
|---|---|---|
.log | Runtime logs | Debugging, server output |
.pem, .key, .crt | Certificates and keys | TLS, SSH, secure connections |
.png, .jpg, .webp | Images | UI assets |
.pdf | Document output | Reports, invoices |
.zip, .tar, .gz | Archives | Package or backup files |
.wasm | WebAssembly binary | Browser or edge runtime modules |
.map | Source map | Debug bundled JavaScript |
These files are often not meant to be manually edited.
Some should not be committed at all, especially private keys, local logs, and generated build artifacts.
AI and Prompt Files
Modern AI projects sometimes introduce prompt-specific files.
| File Type | Purpose | Common Use |
|---|---|---|
.prompt | Plain prompt text | Simple reusable prompts |
.prompty | Structured prompt file | Prompt engineering workflows |
.poml | Prompt orchestration markup | Structured AI instructions and agent behavior |
.json | Prompt config or evaluation data | Dataset, test case, config |
.yaml | Agent or workflow config | Tool routing, model settings |
A normal prompt can become hard to maintain when it contains:
- role definition
- task definition
- tool rules
- input variables
- output schema
- examples
- evaluation cases
That is why some teams move prompts into structured files.
A simplified POML-like shape may look like this:
<prompt>
<role>
You are a customer support assistant.
</role>
<task>
Answer using only the provided context.
</task>
<output-format>
Return a short answer with source references.
</output-format>
</prompt>
The goal is not to replace programming languages. The goal is to make prompt behavior easier to version, review, and reuse.
How to Read an Unknown File Type
When you see a file type you do not know, do not memorize it blindly.
Use this inspection workflow:
1. Check the File Name
Some filenames reveal ownership directly, such as tsconfig.json, pom.xml, Dockerfile, or package.json.
2. Check the Syntax
Braces suggest JSON or code. Indentation may suggest YAML. Tags suggest XML or HTML. SQL keywords suggest database scripts.
3. Check the Tool
Ask which tool reads the file. TypeScript reads tsconfig.json. Maven reads pom.xml. Docker reads Dockerfile.
4. Check Whether It Is Source or Generated
Source files should be edited. Generated files, lock files, logs, and build outputs should be handled more carefully.
The best question is:
Who consumes this file?
Once you know the consumer, the file type becomes much easier to understand.
Practical Decision Rule
Use this table when deciding what a file probably does.
| If the File Is For | It Is Usually |
|---|---|
| Tool settings | JSON, YAML, TOML, INI, properties |
| Java build and dependencies | pom.xml or build.gradle |
| Rich technical article | MDX |
| Plain documentation | Markdown |
| Database structure | SQL or ORM schema file |
| API contract | Proto, GraphQL, OpenAPI, WSDL |
| Deployment | Dockerfile, YAML, Terraform, Nginx config |
| Automation | Shell, PowerShell, Makefile |
| Secrets and runtime settings | .env, environment config |
| Exact dependency versions | Lock file |
| Prompt orchestration | Prompt file, Promty, POML |
| Certificates and secure connection material | PEM, CRT, KEY files |
File types are not random. They are boundaries between different responsibilities in a software project.
The Main Principle
Different file types exist because programming projects contain different kinds of information.
Configuration files control tools. Markdown explains. MDX renders rich content. XML represents strict structured markup. JSON and YAML move or configure structured data. SQL controls databases. Docker and CI files automate deployment. Lock files preserve dependency consistency. Certificate files support secure communication. Prompt files structure AI behavior.
When you see a new file type, do not ask only what the extension means. Ask which tool reads it, what responsibility it owns, and whether it is meant to be edited by humans or generated by machines.
编程项目里面除了普通源码以外，还会出现很多其他文件类型。这些文件通常是为了让工具读取配置、文档、依赖信息、数据库指令、部署规则、API contract、环境变量，或者结构化 AI prompt。只要你知道是哪一个工具读取这个文件，这个文件类型就会容易理解很多。
简短答案
文件类型会告诉 developer 和 toolchain：这个文件里面大概是什么内容。
它通常回答四个问题：
- 这个文件是不是配置？
- 这个文件是不是文档或内容？
- 这个文件是不是结构化数据？
- 哪一个工具应该读取这个文件？
| 文件类型 | 主要用途 | 常见读取者 |
|---|---|---|
.json, .yaml, .toml, .ini | 配置或结构化数据 | App、framework、DevOps tool |
.xml | 严格结构化标记 | Maven、Android、SOAP、企业工具 |
.md, .mdx | 文档和 rich content | 文档站或 blog engine |
.sql | 数据库 schema 和 query | Database engine |
.env | 环境变量 | Application runtime |
Dockerfile, .dockerignore | Container build rules | Docker |
.sh, .ps1 | 自动化脚本 | Shell 或 PowerShell |
.proto, .graphql | API contract | API tooling |
.lock files | 精确 dependency version | Package manager |
.pem, .crt, .key | Certificate 和 key | TLS、SSH、infra tool |
.prompt, .prompty, .poml | AI prompt structure | AI tooling 或 agent framework |
文件 extension 不是装饰。它是给 toolchain 的信号。
主要分类
大多数非源码文件类型都可以放进几个实际分类。
- 1配置控制工具、框架和运行时行为
- 2内容保存文档、文章和 UI 文案
- 3数据在系统之间传递结构化信息
- 4自动化执行构建、部署和维护任务
- 5契约定义 API、schema 和通信格式
- 6安全文件保存 certificate、key 和安全连接材料
一个 backend 项目可能有 pom.xml、application.properties、.sql、.env、Dockerfile、docker-compose.yml、.gitignore、.md、lock file。
一个 frontend 或 documentation 项目可能有 package.json、tsconfig.json、.mdx、.env、.svg、.json、.yaml、lock file。
这些文件不是随机出现的。它们是在拆分不同的项目责任。
配置文件
配置文件告诉工具应该怎样运行。
它们通常不是业务逻辑，而是给 framework、compiler、package manager、deployment system、runtime environment 的指令。
| 文件类型 | 常见文件 | 目的 |
|---|---|---|
.json | package.json | Node.js package metadata 和 scripts |
.json | tsconfig.json | TypeScript compiler config |
.js, .mjs, .cjs | next.config.mjs | Next.js configuration |
.yaml, .yml | docker-compose.yml | 本地多 container 配置 |
.yaml, .yml | GitHub Actions workflow | CI/CD pipeline |
.toml | pyproject.toml | Python project config |
.ini | config.ini | 简单 key-value config |
.properties | application.properties | Java / Spring Boot config |
.gradle | build.gradle | Gradle build config |
.env | .env | Runtime environment variables |
package.json 例子：
{
"scripts": {
"dev": "next dev",
"build": "next build"
},
"dependencies": {
"next": "^16.0.0",
"react": "^19.0.0"
}
}
.env 例子：
DATABASE_URL=postgresql://user:password@localhost:5432/app
PORT=3000
重点是 ownership。package.json 是给 Node.js package manager 读的。tsconfig.json 是给 TypeScript 读的。.env 是给 application runtime 或 environment loader 读的。
JSON、YAML、TOML、INI
这些格式经常被用来写配置和结构化数据。
它们可以保存类似的信息，但 trade-off 不一样。
| 格式 | 优点 | 缺点 | 常见用途 |
|---|---|---|---|
| JSON | 严格、适合机器读取 | 标准 JSON 不支持 comment | API、Node config、data exchange |
| YAML | 嵌套配置比较好读 | indentation 错误很常见 | DevOps、CI/CD、Kubernetes |
| TOML | 配置格式清楚 | 没有 JSON/YAML 那么常见 | Python、Rust、tool config |
| INI | 非常简单的 key-value 格式 | 不适合复杂嵌套配置 | 旧应用、简单 config |
JSON 例子：
{
"name": "backend-service",
"port": 3000
}
YAML 例子：
name: backend-service
port: 3000
TOML 例子：
name = "backend-service"
port = 3000
INI 例子：
name=backend-service
port=3000
JSON 常用于机器之间交换数据。YAML 常用于人手写 infrastructure config。TOML 在一些现代语言生态里比较常见。INI 适合很小、很平的配置。
XML 文件
XML 是 Extensible Markup Language。
XML 是一种严格的 markup format，用 tag 表示结构化数据。
例子：
<user>
<id>1001</id>
<name>Alex</name>
<role>admin</role>
</user>
XML 很啰嗦，但它有几个优点：
- opening tag 和 closing tag 很明确
- tree structure 严格
- schema 支持成熟
- parser 生态成熟
- 常见于旧企业系统
- 常见于 Java 和 Android 生态
你经常会在这些地方看到 XML：
| 文件 / 场景 | 为什么会出现 XML |
|---|---|
pom.xml | Maven 用 XML 定义 Java project build 和 dependency |
| Android layout files | Android 过去常用 XML 写 UI layout 和 app config |
| SOAP APIs | SOAP message 是基于 XML 的 |
| Enterprise integration | 旧企业工具经常标准化使用 XML |
| Office document formats | 一些文档格式内部是 zipped XML |
| RSS feeds | 很多 feed 是 XML document |
| SVG files | SVG 本质上是 XML-based vector graphics |
Java 里面常见例子是 Maven 的 pom.xml。
<project>
<modelVersion>4.0.0</modelVersion>
<groupId>com.example</groupId>
<artifactId>demo-service</artifactId>
<version>1.0.0</version>
<dependencies>
<dependency>
<groupId>org.springframework.boot</groupId>
<artifactId>spring-boot-starter-web</artifactId>
</dependency>
</dependencies>
</project>
这个文件告诉 Maven：
- project 叫什么
- 当前版本是什么
- 需要哪些 dependencies
- 要跑哪些 plugins
- 这个 project 应该怎样被 package
重点是：XML 不只是数据格式。在很多生态里面，XML 会被用作 configuration、build definition、UI layout 和 message format。
Markdown 和 MDX 文件
Markdown 用来写可读性高的文档。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.md | 普通 Markdown | README、docs、notes |
.mdx | Markdown 加 JSX component | Blog post、component docs、interactive documentation |
Markdown 例子：
## Installation
Run this from the project root:
```bash
npm install
MDX 增加了 component 支持。
MDX 例子：
```mdx
<CardGrid columns={2}>
<InfoCard title="Measure First">
Find the bottleneck before changing the architecture.
</InfoCard>
<InfoCard title="Fix the Highest Cost">
Optimize the part that creates the most user-visible delay.
</InfoCard>
</CardGrid>
普通 documentation repo 用 .md 就够了。
如果是需要 custom UI component 的 blog 或 documentation site，.mdx 更有用。
风险是：MDX 不是纯文字。如果 JSX 写错，或者 component 不存在，build 可能会直接失败。
数据库文件
数据库相关文件用来定义 schema、query、migration、seed data 和 export。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.sql | SQL command | Schema、query、migration |
.prisma | Prisma schema | Database model 和 generated client |
.csv | 表格数据 | Export、import、seed data |
.sqlite, .db | Database file | 本地 SQLite database |
.dump | Database dump | Backup 和 restore |
SQL migration 例子：
CREATE TABLE users (
id SERIAL PRIMARY KEY,
email TEXT NOT NULL UNIQUE,
created_at TIMESTAMP NOT NULL DEFAULT NOW()
);
这个文件通常是给 database engine 或 migration tool 读取的。
.sql 不是 application code，但它可以改变数据库结构和行为。所以在 backend 项目里面，它非常重要。
API Contract 文件
API contract 文件定义系统之间怎样沟通。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.proto | Protocol Buffers schema | gRPC service |
.graphql | GraphQL schema 或 query | GraphQL API |
.wsdl | Web service definition | SOAP service |
.avsc | Avro schema | Kafka 和 data pipeline |
.json | OpenAPI document | REST API documentation |
.yaml | OpenAPI document | REST API documentation |
.proto 例子：
syntax = "proto3";
service UserService {
rpc GetUser (GetUserRequest) returns (UserResponse);
}
message GetUserRequest {
string id = 1;
}
message UserResponse {
string id = 1;
string email = 2;
}
这个文件不是在实现 service。它是在定义 contract。
server 和 client 可以根据它 generate code，让两边同意同一个 communication shape。
自动化和脚本文件
自动化文件用来重复、稳定地执行命令。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.sh | Shell script | Linux/macOS automation |
.ps1 | PowerShell script | Windows automation |
.bat, .cmd | Windows command script | 较旧的 Windows automation |
Makefile | Task runner | Build 和 maintenance commands |
.github/workflows/*.yml | CI/CD workflow | GitHub Actions automation |
Shell script 例子：
#!/usr/bin/env bash
npm install
npm run build
PowerShell script 例子：
npm install
npm run build
这些文件的价值是减少手动重复。
比起每次记十条 command，团队可以直接运行一个 script。
Container 和 Deployment 文件
部署文件描述应用离开本地电脑之后应该怎样运行。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
Dockerfile | Build container image | App containerization |
.dockerignore | 排除 Docker build context 里的文件 | 更快、更干净的 Docker build |
docker-compose.yml | 本地跑多个 container | App + database + Redis |
.tf | Terraform config | Cloud infrastructure |
.k8s.yml, .yaml | Kubernetes resources | Deployment、service、ingress |
nginx.conf | Nginx configuration | Reverse proxy、static serving、routing |
Dockerfile 例子：
FROM node:22-alpine
WORKDIR /app
COPY package*.json ./
RUN npm install
COPY . .
RUN npm run build
CMD ["npm", "start"]
这个文件不是业务逻辑。它定义的是 application environment 应该怎样被 package 和运行。
Dependency 和 Lock 文件
Dependency 文件告诉项目需要哪些 packages。
Lock 文件记录已经解析出来的精确版本。
| 文件类型 | 生态 | 目的 |
|---|---|---|
package.json | Node.js | 声明 dependency 和 scripts |
package-lock.json | npm | 锁定精确 dependency tree |
yarn.lock | Yarn | 锁定精确 dependency tree |
pnpm-lock.yaml | pnpm | 锁定精确 dependency tree |
pom.xml | Maven / Java | 声明 Java dependency 和 build config |
build.gradle | Gradle / Java | 声明 dependency 和 build logic |
requirements.txt | Python | 列出 Python packages |
poetry.lock | Python Poetry | 锁定精确 dependency version |
go.mod | Go | 声明 Go module dependency |
go.sum | Go | 验证 dependency checksum |
Cargo.toml | Rust | 声明 Rust package metadata 和 dependency |
Cargo.lock | Rust | 锁定精确 dependency version |
不要随便删除 lock file。
Lock file 可以让不同机器、CI/CD、production 安装到一致的 dependency version。
Git 和 Ignore 文件
Git 相关文件控制 version history，以及哪些东西不应该被 commit。
| 文件类型 | 目的 |
|---|---|
.gitignore | 告诉 Git 哪些文件要忽略 |
.gitattributes | 控制 Git 对不同文件类型的行为 |
.gitmodules | 记录 Git submodule |
.gitignore 例子：
node_modules
.env
dist
.next
这可以防止 generated files、dependencies 和 secrets 被 commit。
好的 .gitignore 可以让 repository 更干净，也可以降低 accidental leak 的风险。
Log、证书和 Binary 文件
项目里面不是所有文件都是源码文本。
有些文件是 generated output、runtime artifact 或 binary resource。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.log | Runtime logs | Debug、server output |
.pem, .key, .crt | Certificate 和 key | TLS、SSH、安全连接 |
.png, .jpg, .webp | 图片 | UI assets |
.pdf | 文档输出 | Report、invoice |
.zip, .tar, .gz | Archive | Package 或 backup |
.wasm | WebAssembly binary | Browser 或 edge runtime module |
.map | Source map | Debug bundled JavaScript |
这些文件很多时候不是给人手动编辑的。
有些甚至不应该 commit，尤其是 private key、本地 log、generated build artifact。
AI 和 Prompt 文件
现代 AI 项目有时会出现 prompt 相关文件。
| 文件类型 | 目的 | 常见用途 |
|---|---|---|
.prompt | 普通 prompt text | 简单可复用 prompt |
.prompty | 结构化 prompt file | Prompt engineering workflow |
.poml | Prompt orchestration markup | 结构化 AI instruction 和 agent behavior |
.json | Prompt config 或 evaluation data | Dataset、test case、config |
.yaml | Agent 或 workflow config | Tool routing、model settings |
普通 prompt 在变复杂之后会很难维护，例如它可能包含：
- role definition
- task definition
- tool rules
- input variables
- output schema
- examples
- evaluation cases
所以有些团队会把 prompt 移到结构化文件里。
简化后的 POML-like 形状可能像这样：
<prompt>
<role>
You are a customer support assistant.
</role>
<task>
Answer using only the provided context.
</task>
<output-format>
Return a short answer with source references.
</output-format>
</prompt>
目标不是取代 programming language。目标是让 prompt behavior 更容易 version、review 和 reuse。
看到不认识的文件类型时怎么判断
遇到不认识的 file type，不要死背 extension。
用这个流程判断：
1. 看文件名
有些文件名直接暴露 ownership，例如 tsconfig.json、pom.xml、Dockerfile、package.json。
2. 看语法形状
大括号通常是 JSON 或代码。缩进可能是 YAML。tag 通常是 XML 或 HTML。SQL keyword 通常是数据库脚本。
3. 看是哪一个工具读取
TypeScript 读取 tsconfig.json。Maven 读取 pom.xml。Docker 读取 Dockerfile。
4. 判断是源码还是生成物
源码通常可以编辑。Generated file、lock file、log、build output 要更小心处理。
最重要的问题是：
谁会消费这个文件？
知道 consumer 之后，文件类型就容易理解很多。
实用判断规则
看到一个文件时，可以用这张表快速判断它大概负责什么。
| 如果文件是为了 | 通常属于 |
|---|---|
| 工具设置 | JSON、YAML、TOML、INI、properties |
| Java build 和 dependency | pom.xml 或 build.gradle |
| Rich technical article | MDX |
| 普通文档 | Markdown |
| 数据库结构 | SQL 或 ORM schema file |
| API contract | Proto、GraphQL、OpenAPI、WSDL |
| 部署 | Dockerfile、YAML、Terraform、Nginx config |
| 自动化 | Shell、PowerShell、Makefile |
| Secret 和 runtime setting | .env、environment config |
| 精确 dependency version | Lock file |
| Prompt orchestration | Prompt file、Prompty、POML |
| Certificate 和安全连接材料 | PEM、CRT、KEY files |
文件类型不是随机的。它们是软件项目中不同责任的边界。
核心原则
不同文件类型存在，是因为编程项目里面有不同种类的信息。
配置文件控制工具。Markdown 解释东西。MDX 渲染 rich content。XML 表示严格结构化 markup。JSON 和 YAML 传递或配置结构化数据。SQL 控制数据库。Docker 和 CI 文件自动化部署。Lock file 保证 dependency 一致性。Certificate 文件支持安全通信。Prompt 文件结构化 AI 行为。
看到新的 file type 时，不要只问 extension 是什么意思。要问是哪一个工具读取它、它负责哪一层、它是给人编辑的，还是机器生成的。