Adentrándonos en el proceso de desarrollo con IA generativa con Claude Code

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Project Overview

This is a **CMBD (Conjunto Mínimo Básico de Datos) Error Management System** — a Spanish healthcare data validation tool for hospital discharge records. The application validates records against CMBD standards (ICD-10-ES medical coding, patient demographics, administrative data) and produces structured error reports.

The processing engine is a **Microsoft Access 2007 database** (`Gestion de Errores CMBD_Access07v1_0_1.mdb`) containing embedded VBA macros and validation rules. There is no compiled source code in this repository.

## Running the Application

The application is driven by opening the `.mdb` file in Microsoft Access and importing the input pipe-delimited text file. No CLI commands or build steps exist.

**Input:** Pipe-delimited (`|`) flat file (e.g., `HOS990426.txt`) containing hospital discharge records.

**Outputs generated:**
- `HOS990426-(VALIDOS).log` — Records that passed all validation checks
- `HOS990426-(DETALLES).log` — Record-by-record error detail with error codes
- `HOS990426-(RESUMEN).LOG` — Aggregate error frequency statistics
- `HOS990426-(RECHAZADOS).LOG` — Records rejected outright (eliminatory errors)

## Architecture & Data Flow

```
HOS######.txt (input)
      ↓
Access .mdb (validation rules + VBA)
      ↓
┌─────────────────────────────────────────────────────┐
│  (VALIDOS).log   (DETALLES).log   (RESUMEN).LOG     │
│  (RECHAZADOS).LOG                                   │
└─────────────────────────────────────────────────────┘
```

### Input Record Format

Each record is a pipe-delimited row with ~200+ fields covering:
- Hospital and episode identifiers
- Patient demographics (gender, date of birth, nationality, ID type)
- Admission/discharge dates and times
- ICD-10-ES diagnosis codes (primary + secondary)
- ICD-10-ES procedure codes with dates and urgency flags
- Administrative data (transfer hospital, emergency order, ward)

### Error Classification

Errors fall into three severity tiers:

| Code prefix | Severity | Meaning |
|---|---|---|
| `E-` | Eliminatory | Record is rejected entirely (e.g., E-000102: overlapping episodes) |
| `X-` | Error | Record is flagged but retained; the field value is invalid |
| `W-` | Warning | Possible error; may indicate data quality issue |

High-frequency error codes seen in sample data:
- `X-001301` — Birth country code invalid
- `X-100101` — Main diagnosis code missing or invalid (ICD-10-ES)
- `X-310101` / `X-310201` — Procedure date-time missing or wrong format
- `X-320102` / `X-320202` — Procedure urgency flag out of range
- `X-000501` — Emergency identifier invalid
- `X-000701` — Patient ID type code invalid

### Summary Report Structure

The `(RESUMEN).LOG` file reports:
- Total records sent / processed / valid / invalid
- Records with zero errors vs. records with at least one error
- Per-error-code counts and percentages

## Project Goal

The goal is NOT to maintain the Access application.

The goal is to reverse engineer the Access database and VBA logic and migrate the solution into a modern web platform.

Target architecture:

- Frontend: React
- Backend: FastAPI
- Database: MySQL
- Containerization: Docker Compose

Migration strategy:

1. Discover Access structures.
2. Document business rules.
3. Extract validation logic.
4. Design REST APIs.
5. Build equivalent backend services.
6. Build web frontend.
7. Decommission Access.

Claude must always prioritize:
- Documentation first
- Architecture before coding
- Incremental delivery
- Clean code
- Testability

/docs
    project-context.md
    architecture.md
    business-rules.md
    database-analysis.md
    decisions.md

mkdir -p docs && touch docs/{project-context,architecture,business-rules,database-analysis,decisions}.md

Claude, after completing any task:
1. Review the work performed.
2. Identify any errors, corrections, or decisions made.
3. Determine if there is a risk of repeating them.
4. Automatically update:
   - MEMORY.md
   - docs/decisions.md
   - docs/lessons-learned.md
5. Propose new rules if you detect repetitive patterns.
6. Show a summary of the changes made.

Perform a project retrospective.

Review:

* recent work
* errors encountered
* user corrections
* failed assumptions
* architectural deviations

Update:

* MEMORY.md
* docs/decisions.md
* docs/lessons-learned.md

If needed:

* propose new project rules
* propose CLAUDE.md improvements

Output:

1. Findings
2. Updates performed
3. New recommendations

Claude:

Clasifica los hallazgos de la retrospectiva en:

- Reglas permanentes
- Decisiones técnicas
- Riesgos
- Deuda técnica
- Hipótesis pendientes de validar

Actualiza la documentación correspondiente.

No modifiques código.
No cambies arquitectura.

Record a project checkpoint.

Summarize:
- Current progress
- Findings
- Pending tasks

Do not update permanent decisions.
Do not modify MEMORY.md unless relevant findings are identified.

This is a new session.

Before performing any work:

1. Read the /docs folder
2. Analyze the documentation.
3. Produce a concise summary containing:
   * Main architecture blocks
   * Key architectural decisions
   * Assumptions made
   * Avoided risks
   * Main migration risks
   * Open questions still unresolved
4. Highlight any assumption that could significantly impact the roadmap.

Do not generate a roadmap yet.

Wait for approval before proceeding.

Create a migration roadmap.

Output:

Phase 1: Discovery
Phase 2: Documentation
Phase 3: Database design
Phase 4: API design
Phase 5: Backend implementation
Phase 6: Frontend implementation
Phase 7: Testing
Phase 8: Deployment

For each phase include:
- Deliverables
- Risks
- Dependencies
- Estimated timeline or story points

Store in:
docs/roadmap.md

Read:

* architecture-v1.md
* decisions.md
* sprint-01.md

Execute the complete lifecycle of the selected user story:

1. Analyze the story
2. Propose implementation approach
3. Review the approach
4. Refine the approach
5. Implement the story
6. Validate against acceptance criteria
7. Generate implementation report
8. Update project memory if required

Do not continue with any other user story.

Stop after completing the selected story.

Run the complete three-phase workflow for user story: $ARGUMENTS

Execute each phase in sequence. After Phase 1 and Phase 2, stop and wait for explicit user approval before proceeding.

---

## Phase 1 — Analysis

Read:

* docs/architecture-v1.md
* docs/decisions.md
* docs/mvp-backlog.md

Focus only on user story: **$ARGUMENTS**

Analyze:

1. Goal of the user story
2. Acceptance criteria
3. Technical approach
4. Required files and folders
5. Dependencies
6. Risks
7. Open questions

Produce:

* Proposed implementation approach
* List of files to create or modify
* Definition of done

Do not generate code or files yet.

**Stop here. Wait for the user to explicitly approve the implementation approach before continuing to Phase 2.**

---

## Phase 2 — Design Review

*(Execute only after Phase 1 is approved)*

Review the proposed implementation approach acting as a senior architect.

Verify:

* Acceptance criteria coverage
* Simplicity
* Maintainability
* Security
* Docker best practices
* Development experience

Identify:

* Overengineering
* Missing components
* Unnecessary complexity
* Risks

Do not redesign. Only review.

**Stop here. Wait for the user to explicitly approve the design before continuing to Phase 3.**

---

## Phase 3 — Implementation

*(Execute only after Phase 2 is approved)*

Implement the approved user story: **$ARGUMENTS**

Requirements:

* Satisfy all acceptance criteria.
* Follow the approved implementation approach.
* Create only the files required for this story.
* Do not implement future user stories.
* Keep the solution simple.
* Document important decisions.

At the end provide:

1. Files created
2. Files modified
3. Acceptance criteria checklist
4. Manual verification steps

Analyze user story: $ARGUMENTS

Read:

* docs/architecture-v1.md
* docs/decisions.md
* docs/mvp-backlog.md

Focus only on user story: **$ARGUMENTS**

Analyze:

1. Goal of the user story
2. Acceptance criteria
3. Technical approach
4. Required files and folders
5. Dependencies on other stories or services
6. Risks
7. Open questions

Produce:

* Proposed implementation approach
* List of files to create or modify
* Definition of done

Do not generate code or files yet.

Wait for explicit user approval before proceeding.

Review the proposed implementation approach for the current user story.

Act as a senior architect.

Verify:

* Acceptance criteria coverage — does the approach address every criterion?
* Simplicity — is there a simpler path to the same result?
* Maintainability — will this be easy to change in six months?
* Security — any exposed secrets, unvalidated inputs, or unsafe defaults?
* Docker best practices — images, volumes, networking, env vars
* Development experience — does this keep the local workflow clean?

Identify:

* Overengineering — abstractions or patterns not justified by current requirements
* Missing components — anything the acceptance criteria require that is not in the plan
* Unnecessary complexity — layers, files, or indirection that add no value
* Risks — anything that could block delivery or cause regressions

Do not redesign. Do not produce new code or files.

Only review. State findings clearly and concisely.

Wait for explicit user approval before proceeding to implementation.

Implement user story: $ARGUMENTS

Requirements:

* Satisfy all acceptance criteria.
* Follow the approved implementation approach exactly.
* Create only the files required for this story — nothing more.
* Do not implement logic belonging to future user stories.
* Keep the solution simple.
* Document decisions that are non-obvious or constrained by external factors.

At the end provide:

1. **Files created** — path and one-line purpose for each
2. **Files modified** — path and summary of changes for each
3. **Acceptance criteria checklist** — each criterion marked DONE or PENDING
4. **Manual verification steps** — exact commands or UI actions to confirm the story works

Validate user story: $ARGUMENTS

Objective: confirm the implemented story meets every acceptance criterion before marking it done.

Steps:

1. Read the story definition from docs/mvp-backlog.md and extract all acceptance criteria for **$ARGUMENTS**.

2. Start the application if not already running:

   ```
   docker compose up -d
   ```

3. For each acceptance criterion, verify it by:
   * calling the relevant API endpoint, or
   * observing the relevant UI behavior, or
   * inspecting generated files or database state.

4. Check for regressions: confirm that previously working stories are unaffected.

Produce a validation report:

| # | Acceptance criterion | Result | Notes |
|---|---|---|---|
| 1 | … | PASS / FAIL / PARTIAL | … |

Overall verdict: **DONE** or **BLOCKED**

If any criterion fails, list the specific failures with enough detail to open a fix task. Do not fix issues inline — keep validation and implementation separate.

Orchestrate the complete story workflow for: $ARGUMENTS

For each phase below, read the corresponding command file and execute its instructions.
Stop at each GATE and wait for explicit user approval before continuing.

---

## Phase 1 — Analysis

Read `.claude/commands/analyze-story.md` and execute its instructions for story **$ARGUMENTS**.

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 2 — Design Review

Read `.claude/commands/review-design.md` and execute its instructions.

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 3 — Implementation

Read `.claude/commands/implement-story.md` and execute its instructions for story **$ARGUMENTS**.

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 4 — Validation

Read `.claude/commands/validate-story.md` and execute its instructions for story **$ARGUMENTS**.

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 5 — Retrospective

Read `.claude/commands/retrospective.md` and execute its instructions.

docs/
    stories/
        US-001/
            analysis.md
            design-review.md
            design.md
            implementation.md
            retrospective.md
            validation.md
        US-002/
            ...

Analyze user story: $ARGUMENTS

Read:

* docs/architecture-v1.md
* docs/decisions.md
* docs/mvp-backlog.md

Focus only on user story: **$ARGUMENTS**

Analyze:

1. Goal of the user story
2. Acceptance criteria
3. Technical approach
4. Required files and folders
5. Dependencies on other stories or services
6. Risks
7. Open questions

Produce:

* Proposed implementation approach
* List of files to create or modify
* Definition of done

Do not generate code or files yet.

---

## Output files

After completing the analysis, create the directory `docs/stories/$ARGUMENTS/` if it does not exist, then write two files:

**`docs/stories/$ARGUMENTS/analysis.md`**

```markdown
# $ARGUMENTS — Analysis

## Objetivo
<goal of the user story>

## Acceptance Criteria
<numbered list of acceptance criteria>

## Dependencias
<list of stories, services, or data this story depends on>

## Riesgos
<list of risks with brief description>

## Definición de Done
<checklist of conditions that must be true before the story is closed>
```

**`docs/stories/$ARGUMENTS/design.md`**

```markdown
# $ARGUMENTS — Diseño propuesto

## Enfoque
<summary of the implementation approach>

## Componentes
<list of components, modules, or layers involved>

## Ficheros
<list of files to create or modify with one-line purpose each>

## Trade-offs
<decisions made and alternatives discarded with brief rationale>
```

---

Wait for explicit user approval before proceeding.

Implement user story: $ARGUMENTS

Read:

* `docs/stories/$ARGUMENTS/analysis.md` — acceptance criteria and definition of done
* `docs/stories/$ARGUMENTS/design.md` — approved implementation approach
* `docs/stories/$ARGUMENTS/design-review.md` — conditions and recommendations to apply

Requirements:

* Satisfy all acceptance criteria.
* Follow the approved implementation approach exactly.
* Apply any conditions listed in the design review.
* Create only the files required for this story.
* Do not implement logic belonging to future user stories.
* Keep the solution simple.
* Document decisions that are non-obvious or externally constrained.

---

## Output file

After completing the implementation, write:

**`docs/stories/$ARGUMENTS/implementation.md`**

```markdown
# $ARGUMENTS — Implementation

## Ficheros creados
| Path | Purpose |
|---|---|
| … | … |

## Ficheros modificados
| Path | Summary of changes |
|---|---|
| … | … |

## Cambios realizados
<narrative summary of what was built and any non-obvious decisions made>
```

---

Provide manual verification steps in the chat so the user can test before proceeding.

Review the proposed implementation approach for story: $ARGUMENTS

Act as a senior architect.

Read `docs/stories/$ARGUMENTS/design.md` to retrieve the proposed approach.

Verify:

* Acceptance criteria coverage — does the approach address every criterion?
* Simplicity — is there a simpler path to the same result?
* Maintainability — will this be easy to change in six months?
* Security — any exposed secrets, unvalidated inputs, or unsafe defaults?
* Docker best practices — images, volumes, networking, env vars
* Development experience — does this keep the local workflow clean?

Identify:

* Overengineering — abstractions or patterns not justified by current requirements
* Missing components — anything the acceptance criteria require that is not in the plan
* Unnecessary complexity — layers, files, or indirection that add no value
* Risks — anything that could block delivery or cause regressions

Do not redesign. Do not produce code or files. Only review.

---

## Output file

After completing the review, write:

**`docs/stories/$ARGUMENTS/design-review.md`**

```markdown
# $ARGUMENTS — Design Review

## Problemas detectados
<numbered list of issues found; empty if none>

## Recomendaciones
<numbered list of concrete recommendations>

## Aprobación
[ ] Approved — ready to implement
[ ] Approved with conditions — list conditions
[ ] Rejected — list blocking reasons
```

---

Wait for explicit user approval before proceeding to implementation.

Validate user story: $ARGUMENTS

Read `docs/stories/$ARGUMENTS/analysis.md` to extract the acceptance criteria.

Start the application if not already running:

```
docker compose up -d
```

For each acceptance criterion, verify it by:

* calling the relevant API endpoint, or
* observing the relevant UI behavior, or
* inspecting generated files or database state.

Check for regressions: confirm that previously working stories are unaffected.

---

## Output file

After completing validation, write:

**`docs/stories/$ARGUMENTS/validation.md`**

```markdown
# $ARGUMENTS — Validation

## Acceptance Criteria

| # | Criterion | Result | Notes |
|---|---|---|---|
| 1 | … | PASS / FAIL / PARTIAL | … |

## Regressions
<list any regressions found, or "None detected">

## Verdict
DONE — all criteria pass
BLOCKED — list of failing criteria
```

---

If any criterion fails, list the specific failures with enough detail to open a fix task.
Do not fix issues inline — keep validation and implementation separate.

Perform a project retrospective.

Review:

* recent work
* errors encountered
* user corrections
* failed assumptions
* architectural deviations

Update:

* MEMORY.md
* docs/decisions.md
* docs/lessons-learned.md

If needed:

* propose new project rules
* propose CLAUDE.md improvements

Output:

1. Findings
2. Updates performed
3. New recommendations

---

## Story artifact (only when $ARGUMENTS is provided)

If a story ID was given ($ARGUMENTS), also write:

**`docs/stories/$ARGUMENTS/retrospective.md`**

```markdown
# $ARGUMENTS — Retrospective

## Lecciones aprendidas
<what we would do differently next time>

## Problemas encontrados
<issues that slowed down or blocked the story>

## Actualizaciones de memoria
<list of memory files updated and what changed>
```

Orchestrate the complete story workflow for: $ARGUMENTS

When reading and executing subcommand files below, treat every occurrence of
`$ARGUMENTS` in those files as: $ARGUMENTS

Stop at each GATE and wait for explicit user approval before continuing.

---

## Phase 1 — Analysis

Read `.claude/commands/analyze-story.md` and execute its instructions for story **$ARGUMENTS**.

Produce and save:
- `docs/stories/$ARGUMENTS/analysis.md`
- `docs/stories/$ARGUMENTS/design.md`

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 2 — Design Review

Read `.claude/commands/review-design.md` and execute its instructions for story **$ARGUMENTS**.

Produce and save:
- `docs/stories/$ARGUMENTS/design-review.md`

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 3 — Implementation

Read `.claude/commands/implement-story.md` and execute its instructions for story **$ARGUMENTS**.

Produce and save:
- `docs/stories/$ARGUMENTS/implementation.md`

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 4 — Validation

Read `.claude/commands/validate-story.md` and execute its instructions for story **$ARGUMENTS**.

Produce and save:
- `docs/stories/$ARGUMENTS/validation.md`

**GATE — Wait for explicit user approval before continuing.**

---

## Phase 5 — Retrospective

Read `.claude/commands/retrospective.md` and execute its instructions for story **$ARGUMENTS**.

Produce and save:
- `docs/stories/$ARGUMENTS/retrospective.md`