The weak version of this article would say oop-architect keeps UML diagrams current. That is a feature description, not a reason to read.

The better story is that oop-architect turns CLAUDE.md into a design contract for long-running Claude Code work. It puts class diagrams, workflow diagrams, implementation status, directory structure, design decisions, constraints, roadmap items, and maintenance rules in the one file Claude Code already reads before every task.

That matters because agent projects fail in a familiar way: the code changes, the plan stays old, and the next session starts from a stale mental model. oop-architect is useful only if it makes that drift visible without letting diagrams become fake authority.

The contract is the product

The README describes a skill that generates Mermaid UML in CLAUDE.md. The design decision behind it is more important: the maintenance rules live inside the generated CLAUDE.md, not only inside the skill. Routine updates do not require the skill to be active, because Claude Code already loads CLAUDE.md at the start of work.

That makes the file a contract. It says which public interfaces exist, which classes are partial, which files are planned but not created, which constraints came from the user, and which updates count as architecture changes.

Do the OOP check first

The skill has a good first guardrail: do not force OOP where it does not fit. It tells the user to skip the class hierarchy for single-file scripts, one-off data transforms, purely functional pipelines, or projects with no shared state.

That boundary should stay in the article. A diagram skill that always produces diagrams is dangerous. A design-contract skill that can say 'use a simpler approach' is useful.

Pick the phase before touching docs

The four modes are the reason the tool is worth covering:

No code, no CLAUDE.md: design from scratch.
Code exists, no CLAUDE.md: scan code and document what exists.
CLAUDE.md exists, new feature: extend the design before coding.
CLAUDE.md drifted from code: resync from current source.

Those modes prevent a common agent error. The agent should not redesign an existing codebase when the task is to document it. It should not silently rewrite design decisions when the task is to resync. It should not mutate existing public interfaces for a new feature without discussing the change.

Install it per project first

The marketplace install is convenient, but a serious trial should start per project so the team can review the skill as repo policy:

git clone https://github.com/ZhongliangGuo/oop-architect .claude/skills/oop-architect
ls .claude/skills/oop-architect
sed -n '1,180p' .claude/skills/oop-architect/SKILL.md

Then trigger it on a low-risk branch:

/oop-architect
Generate CLAUDE.md for this existing codebase.

The output should be reviewed like code. If the generated CLAUDE.md misstates a public interface or invents design intent, fix the document before letting later sessions rely on it.

A 15-minute setup run

A useful first run should end with one reviewed diff.

# 0-2 minutes: create a branch
git checkout -b docs/architecture-ledger

# 2-5 minutes: install per project
git clone https://github.com/ZhongliangGuo/oop-architect .claude/skills/oop-architect

# 5-10 minutes: ask Claude Code for the right mode
# If code exists and CLAUDE.md does not:
# /oop-architect
# Generate CLAUDE.md for this existing codebase.

# 10-15 minutes: inspect the result
git diff -- CLAUDE.md
rg -n "Architecture Maintenance Rules|Implementation Progress|Design Decisions|Constraints" CLAUDE.md

If the grep command does not find those sections, the output is not ready. If the diff contains planned files that are not marked [not created], fix it. If design decisions are not traceable to code or user intent, mark them as inferred or remove them.

A resync runbook

Use resync only when the file drifted from code, not for every edit.

/oop-architect
Resync the architecture from the current code. Preserve existing Design Decisions and Constraints. If code contradicts a design decision, report the conflict before changing CLAUDE.md.

Then inspect the diff in three groups:

git diff -- CLAUDE.md | rg "Class Diagram|Implementation Progress|Directory Structure|Design Decisions|Constraints"

Accept diagram and progress updates when they match code. Stop on design decision changes unless a human approved the change. That is the rule that keeps resync from erasing intent.

Language references keep UML honest

The skill does not use one generic UML dialect for every stack. It loads a language reference first. TypeScript diagrams use TS types and Promise~T~ return syntax. Python diagrams use type hints, ABC notes, abstract markers, and dataclass stereotypes. Stub detection also changes by language: throw new Error('not implemented') in TypeScript, pass or NotImplementedError in Python.

This matters because implementation status is only useful if the parser knows what unfinished code looks like in that language. A partial class in Python and a partial class in TypeScript leave different traces.

Make public interface change the trigger

The CLAUDE.md template has the most important rule: update this file only when public interfaces change. Skip internal refactors, private helper methods, and utility functions.

A good local rule is:

Update architecture docs only when a public class, interface, method signature, relationship, state transition, data entity, module boundary, constraint, or roadmap item changes. Do not update UML for internal refactors unless they change the public contract.

That keeps the diagram from becoming noise. It also gives Claude Code a crisp decision point during ordinary edits.

Resync must protect human intent

The resync phase is the strongest part of the design. It scans code, compares it to existing UML, updates diagrams, progress, and directory structure, but preserves special notes, design decisions, constraints, and roadmap items.

If code contradicts a design decision, the skill should not overwrite the decision. It should report the conflict and ask which side is correct: update documentation, or flag the code as debt. That distinction is the difference between documentation maintenance and design erasure.

Use status as resume state

Status tracking is not decoration. The generated contract tracks complete, partial, and not-started classes, methods, relationships, workflows, files, and sometimes data or state transitions. That gives the next Claude Code session a resume map.

A useful review asks three questions:

- What is complete enough to rely on?
- What is partial and should not be treated as done?
- What is planned but not created?

If CLAUDE.md cannot answer those questions, the diagrams are not doing their job.

Split large diagrams early

The skill says diagrams with more than 15 to 20 classes should split by module, with cross-module relationships moved into a component diagram. That is not cosmetic. Large Mermaid class diagrams become unreadable quickly, and unreadable diagrams stop being contracts.

For a multi-layer app, keep separate class diagrams for backend, frontend, worker, and shared contracts. Use component diagrams for REST APIs, queues, SDK boundaries, or persistence layers. Do not draw a cross-language inheritance relationship just because two names look related.

A rollout checklist

A team can adopt oop-architect in one branch:

git checkout -b docs/oop-architect-contract
git clone https://github.com/ZhongliangGuo/oop-architect .claude/skills/oop-architect
# In Claude Code:
# /oop-architect
# Generate CLAUDE.md for this existing codebase.

Then review the diff:

git diff -- CLAUDE.md
git diff -- .claude/skills/oop-architect

Accept it only if public signatures match code, design decisions are clearly labeled as human intent or inferred intent, planned files are marked as not created, and the maintenance rules fit the repo.

Review the generated file like code

The review should be mechanical. Use a checklist in the PR:

- [ ] Every public class/interface in the diagram exists in source or is marked planned.
- [ ] Every public method signature matches source.
- [ ] Partial items map to real stubs, TODOs, or missing overrides.
- [ ] Planned files are marked [not created].
- [ ] Design Decisions separate inferred intent from human-confirmed intent.
- [ ] Constraints came from the user, code, or README, not guesswork.
- [ ] Maintenance Rules say updates happen only on public contract changes.

If any box fails, fix CLAUDE.md before merging. The goal is not to make the diagram pretty. The goal is to make the next Claude Code session less likely to act on stale architecture.

Know the failure modes

There are three common failures.

First, over-documentation. If every helper method appears in UML, Claude Code will spend attention on noise. Keep only public architecture.

Second, invented intent. Reverse generation can infer a pattern from code, but it should label inference. Human constraints belong in Constraints & Rules; guesses belong in notes or should be omitted.

Third, silent drift. If a later agent edits public interfaces and does not update CLAUDE.md, the contract is broken. Add a PR check: any diff touching exported classes, public methods, state transitions, database entities, or module boundaries must mention whether CLAUDE.md changed.

What to add to AGENTS.md

The repo should decide when the design contract applies:

Use oop-architect only for multi-file projects where object relationships matter. Treat CLAUDE.md architecture sections as a contract, not decoration. Update UML only when public interfaces, relationships, state transitions, data entities, module boundaries, constraints, or roadmap items change. During resync, preserve human design decisions and ask before changing them when code disagrees. Do not include test fixtures or mocks unless they ship as production library pieces.

This turns the skill from a one-off diagram generator into a working rule.

When not to use it

Skip oop-architect for small scripts, short prototypes, pure data pipelines, or projects where a few plain notes are enough. Skip it when the team will not maintain the generated file. Stale diagrams are worse than no diagrams because they give the agent confidence in a false map.

Use it when the cost of losing architecture state across sessions is higher than the cost of keeping the contract current.

Save the oop-architect article as a guide to CLAUDE.md architecture contracts. It is valuable when readers learn the phase model, public-interface trigger, resync conflict rule, and adoption boundary; it is weak if reduced to live UML.

Practical takeaway

Install oop-architect per project first, run it on a branch, and review the generated CLAUDE.md before relying on it. Keep the OOP appropriateness check, choose the correct phase, update docs only on public interface changes, and preserve human design decisions during resync. If the team will not maintain the contract, do not use the skill.