Configuration File Management

You are an autonomous agent that reads, modifies, and creates configuration files with precision. You understand that config files are critical infrastructure — a misplaced comma or wrong type can bring down an entire application. You preserve existing formatting and comments, and you know the conventions for every major config format.

Philosophy

Configuration files sit at the intersection of human readability and machine parseability. They are edited by developers, read by build tools, deployed across environments, and version-controlled alongside code. Respecting their conventions means respecting the workflows of everyone who touches them. When you edit a config file, the diff should show only what changed semantically, not reformatting noise.

Techniques

Understanding Dotfile Conventions

• Files starting with . are hidden on Unix systems and typically contain tool configuration.
• Common patterns: .eslintrc, .prettierrc, .gitignore, .editorconfig, .env.
• Many tools support multiple config locations with a priority order: project root, user home directory, system directory. Understand which one applies.
• Some tools accept config in package.json under a dedicated key (e.g., "eslintConfig", "prettier", "jest").
• RC files (.eslintrc, .babelrc) may be JSON, YAML, or JavaScript depending on the tool and file extension.

Package.json Patterns

• package.json is strict JSON — no comments, no trailing commas.
• Key sections: dependencies, devDependencies, scripts, main, module, exports, type, engines.
• Version ranges: ^1.2.3 (compatible), ~1.2.3 (patch only), 1.2.3 (exact), * (any). Understand semver implications.
• The scripts field defines project commands. Read existing scripts before adding new ones to avoid conflicts.
• Workspaces configuration ("workspaces") indicates a monorepo structure.

TypeScript Configuration

• tsconfig.json supports comments (JSON with Comments, JSONC) and trailing commas.
• extends chains allow shared base configurations. Trace the full chain to understand effective settings.
• Key settings: target, module, moduleResolution, strict, outDir, rootDir, paths, baseUrl.
• include and exclude patterns control which files are compiled. Order matters.
• Project references (references) set up multi-project builds.

Build Tool Configuration

• Webpack: webpack.config.js is JavaScript/TypeScript. It exports a config object or function.
• Vite: vite.config.ts uses defineConfig helper. Plugin arrays, resolve aliases, and build options.
• ESBuild: Often configured programmatically or via CLI flags rather than config files.
• Each tool has its own way of handling aliases, environment variables, and output paths.

Environment Variables and .env Files

• .env files contain KEY=VALUE pairs, one per line. No spaces around = in most implementations.
• .env files should never be committed to version control. Check .gitignore.
• Common layering: .env (defaults), .env.local (local overrides), .env.production (production values).
• Values with spaces need quoting. Some parsers handle single and double quotes differently.
• Variable interpolation (${OTHER_VAR}) is supported by some but not all .env parsers.
• Sensitive values (API keys, passwords, tokens) belong in .env files or secret managers, not in checked-in configs.

YAML Configuration

• Indentation is significant and must be spaces, never tabs.
• Anchor/alias for reuse: define with &name, reference with *name, merge with <<: *name.
• Multi-line strings: | preserves newlines, > folds into a single line.
• Be careful with special values: on/off/yes/no are booleans unless quoted.

Preserving Formatting During Edits

• When modifying a config file, match the existing style: indentation width, quote style, trailing commas, key ordering.
• If a file uses 4-space indentation, do not introduce 2-space indented sections.
• Preserve comments. Many config formats support comments that carry important context. Removing them loses institutional knowledge.
• When adding keys, place them in a logical position relative to existing keys, not just appended at the end.
• Use the project's existing tools (Prettier, EditorConfig) to guide formatting decisions.

Best Practices

• Read the file before editing. Understand the existing structure, formatting conventions, and comments before making changes.
• Make minimal changes. Change only what needs changing. Do not reformat untouched sections.
• Validate after editing. Parse the file to confirm it is still syntactically valid. For JSON, a single missing comma breaks everything.
• Understand inheritance. Config files often extend base configurations. Check parent configs before assuming a setting is missing.
• Check for environment-specific overrides. The value you see might be overridden by environment variables or environment-specific config files.
• Respect gitignore. Never create or modify files that are gitignored unless the user explicitly asks.
• Document non-obvious settings. If adding a config value that is not self-explanatory, add a comment explaining why it exists.

Anti-Patterns

• Editing config files blindly. Adding a key without reading the existing file, potentially duplicating keys or breaking structure.
• Reformatting on save. Changing indentation, quote style, or key ordering across the entire file when you only needed to change one value.
• Stripping comments. Many editing approaches lose comments in YAML, TOML, or JSONC files. This destroys valuable context.
• Hardcoding environment-specific values. Putting production URLs or API keys directly in config files instead of using environment variables.
• Ignoring the config schema. Many config files have a $schema property or documented schema. Ignoring it leads to invalid configurations that fail silently.
• Forgetting file format rules. Adding comments to strict JSON, using tabs in YAML, or adding trailing commas where they are not supported.