# What Is the Difference Between _profile.md and _shared.md Customization in Career-Ops?

> Understand the difference between _profile.md and _shared.md customization in Career-Ops. Learn how _shared.md handles engine logic and _profile.md stores user data for seamless upgrades.

- Repository: [Santiago Fernández de Valderrama/career-ops](https://github.com/santifer/career-ops)
- Tags: how-to-guide
- Published: 2026-06-09

---

**Career-Ops separates system-wide configuration from personalized user data through a layered architecture where [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) contains auto-updatable engine logic and [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) stores persistent user customizations that survive system upgrades.**

Career-Ops employs a dual-file customization strategy to balance flexible personal configuration with stable system updates. Understanding the distinction between [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) and [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) customization ensures your career data persists while the underlying scoring engine remains current. This guide explains how these files function within the santifer/career-ops repository.

## Understanding _shared.md: System-Wide Configuration

The file [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) serves as the **system context** that powers the Career-Ops engine. This Markdown file contains the core, auto-updatable logic that the system relies on for evaluation workflows.

### Purpose and Content

[`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) defines the universal rules and infrastructure that apply to all users of the repository. According to the source code, it contains:

- **Sources of Truth** – Lists the canonical files ([`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md), [`article-digest.md`](https://github.com/santifer/career-ops/blob/main/article-digest.md), [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md)) that the system reads during evaluation
- **Scoring System** – Defines the six evaluation blocks and global score calculation methodology
- **Archetype Detection** – Maps job description keywords to internal archetypes used for matching
- **Global Rules** – "NEVER" and "ALWAYS" directives that enforce safe, consistent behavior across the engine

### Lifecycle and Auto-Updates

This file **must never contain personal data** because it is updated automatically when the project is upgraded. Running `node update-system.mjs` overwrites [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) with the latest upstream logic, ensuring you receive improvements to scoring algorithms and rule definitions without manual intervention.

## Understanding _profile.md: User Profile Context

The file [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) represents the **user context** layer where all personal career information resides. This file is generated from [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) and captures your unique professional narrative.

### Purpose and Content

Unlike the system file, [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) stores everything a person wants to customize about their job search:

- **Your Target Roles** – A table mapping archetypes to specific job titles you are pursuing
- **Your Adaptive Framing** – Projects mapped to each archetype with pointers to source files like [`cv.md`](https://github.com/santifer/career-ops/blob/main/cv.md)
- **Your Negotiation Scripts** – Personalized salary-range language and push-back messages
- **Your Location Policy** – Availability, timezone preferences, and remote-work requirements
- **Your Comp Targets** – Market-research guidance and compensation goals

### Persistence Across Updates

Created from the template on first run, [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) is **never auto-updated**. Only you (or an assistant) edit this file, ensuring that customizations survive system upgrades. When `node update-system.mjs` executes, it leaves your personal profile untouched while refreshing the underlying engine logic.

## How the Layered Architecture Processes Both Files

The engine follows a deterministic loading order that enables safe customization. During evaluation, Career-Ops first reads [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) to load default scoring logic and system rules. Immediately after, it reads [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) to overlay your personal overrides.

As implemented in line 23 of [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md), the system processes [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) after [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md). This sequencing ensures that any matching keys in your user profile win over the defaults. You can safely tune the system to your career without risking loss of changes when the repository is updated.

## Practical Customization Examples

### Accessing Both Files from a Script

When building tooling around Career-Ops, you can load both configuration layers to understand the complete context:

```javascript
import { readFile } from 'fs/promises';

async function loadContext() {
  const shared = await readFile('modes/_shared.md', 'utf8');
  const profile = await readFile('modes/_profile.md', 'utf8');
  // shared provides defaults, profile provides overrides
  return { shared, profile };
}

```

### Adding a Custom Archetype

Extend your targeting without modifying system files by editing only [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md):

```markdown

## Your Target Roles

| Archetype | Thematic axes | What they buy |
| --------- | ------------- | ------------- |
| **Data Engineering** | Pipelines, streaming, observability | Engineers who reliably ship data pipelines at scale |

```

The scoring logic in [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) automatically recognizes this new archetype during evaluation because the user layer extends the system definitions.

### Overriding System Defaults

To implement a stricter remote-work policy than the default, add to [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md):

```markdown

## Your Location Policy

- **Remote preference:** Only fully-remote roles (no hybrid).
- **Timezone overlap:** Must overlap ≥ 6 hours with EST.

```

The engine honors these values because they appear in the user layer, while the generic rule in [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) remains unchanged for future updates.

## Summary

- **[`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md)** holds auto-updatable system logic including scoring rules, archetype detection, and global constraints that are overwritten during `node update-system.mjs`
- **[`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md)** stores personal career data like target roles, negotiation scripts, and location policies that persist across system upgrades
- The engine reads [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) first, then overlays [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) values (as referenced in line 23 of the shared configuration)
- Generate your initial profile from [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) and edit only [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) to ensure customizations survive updates

## Frequently Asked Questions

### What happens if I accidentally edit _shared.md?

Any changes to [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) will be permanently lost the next time you run `node update-system.mjs`. The update script fetches the latest system logic and overwrites this file completely. If you need to customize behavior, use [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) instead, which the system reads after [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md) and which survives updates.

### How do I create my initial _profile.md?

Career-Ops generates [`modes/_profile.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.md) automatically from [`modes/_profile.template.md`](https://github.com/santifer/career-ops/blob/main/modes/_profile.template.md) on your first run of the system. You should copy the template structure and fill in your specific target roles, compensation targets, and narrative framing. Never edit the template file directly; work only in your generated [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md).

### Can I override scoring rules from _shared.md in my _profile.md?

Yes. The layered architecture explicitly supports this workflow. Because the engine processes [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) after [`_shared.md`](https://github.com/santifer/career-ops/blob/main/_shared.md), any configuration keys or narrative instructions you define in your profile take precedence over the system defaults. This allows you to customize evaluation behavior without forking the core logic.

### Where does the engine read these files in the source code?

The system references these files within the `modes/` directory hierarchy. Specifically, line 23 of [`modes/_shared.md`](https://github.com/santifer/career-ops/blob/main/modes/_shared.md) documents the loading sequence where [`_profile.md`](https://github.com/santifer/career-ops/blob/main/_profile.md) is read after the shared configuration. Additional structured data lives in [`config/profile.yml`](https://github.com/santifer/career-ops/blob/main/config/profile.yml), which the system also accesses alongside these Markdown context files.