Skip to content

docs: record Symfony tooling conventions in CLAUDE.md (#81)#82

Merged
martinyde merged 2 commits into
chore/test-method-commentsfrom
feature/issue-81-claude-md-symfony-practices
Jun 22, 2026
Merged

docs: record Symfony tooling conventions in CLAUDE.md (#81)#82
martinyde merged 2 commits into
chore/test-method-commentsfrom
feature/issue-81-claude-md-symfony-practices

Conversation

@martinydeAI

@martinydeAI martinydeAI commented Jun 18, 2026

Copy link
Copy Markdown
Collaborator

Links to issues

Fixes #81.

Description

Extends the Coding practices section (introduced by PR #74) with
three subsections that name the Symfony-native tooling the project
expects agents to reach for first. Each entry is short and
prescriptive — name the tool, when to reach for it, what failure
mode it prevents.

Added subsections, inserted between Defer to symfony.com/doc when implementing Symfony features and Controllers stay thin:

  1. Use Symfony Flex for new dependencies. Install via
    task composer -- require <package> so the recipe wires
    config/bundles.php, config/packages/, and .env placeholders.
    Hand-editing composer.json or running composer with
    --no-scripts is the failure mode this rule prevents.
  2. Twig components: reuse before creating, prefer
    symfony/ux-twig-component.
    New reusable markup lives at
    templates/components/<Family>/<Name>.html.twig and is invoked via
    <twig:Family:Name … />, not {% include %} or hand-rolled
    partials. Scan the existing families first — extending a component
    with a new prop almost always beats a near-duplicate that drifts in
    styling.
  3. Use Maker Bundle when a recipe exists. Scaffolding work
    (entity, controller, command, form, fixture, voter, event
    subscriber, registration form, etc.) goes through
    task console -- make:<thing>. Hand-rolling boilerplate is the
    failure mode this rule prevents.

Verified locally:

  • symfony/flex, symfony/ux-twig-component, and symfony/maker-bundle
    are all already in composer.json, so each rule names tooling the
    project actually has.
  • task coding-standards-markdown-check — green.

Screenshot of the result

n/a — docs-only.

Checklist

  • My code is covered by test cases. (n/a — docs-only.)
  • My code passes our test (all our tests). (n/a — docs-only.)
  • My code passes our static analysis suite. (markdown lint passes.)
  • My code passes our continuous integration process.

Additional comments or questions

do-not-merge rationale: this PR is stacked on top of #74. Base
is chore/test-method-comments (the head of #74) rather than
develop. Merge order is #74 first, then this PR, after a
quick rebase onto develop. Remove the do-not-merge label once #74
has landed.


Details - AI specificities

  • Section ordering matters: the three new subsections sit between
    Defer to symfony.com/doc and Controllers stay thin so the
    "where to find guidance → what tooling to reach for → how to shape
    the code" flow reads top-to-bottom.
  • The Maker Bundle subsection deliberately references the
    symfony.com/doc rule above ("matches what symfony.com/doc rule
    above points at"), so the two stay aligned conceptually.
  • Each rule names a package that's already installed
    (symfony/flex, symfony/ux-twig-component, symfony/maker-bundle)
    — none of them imply a new dependency.

…nent, Maker Bundle)

Adds three subsections to the `Coding practices` section of CLAUDE.md:

- Install new dependencies via Symfony Flex (`task composer -- require`)
  so the recipe wires the bundle, config, and `.env` placeholders.
- Prefer `symfony/ux-twig-component` for new template markup. Scan
  `templates/components/` for an existing component before adding a
  new one — extending props beats near-duplicates that drift in
  styling.
- Use Maker Bundle (`task console -- make:<thing>`) for scaffolding
  work when a recipe exists, so generated code stays in step with the
  attribute-driven idioms already in the codebase.

Builds on PR #74 (#74 introduces the `Coding practices` section);
this PR sits on top of that branch and should be rebased onto
develop once #74 lands.

Fixes #81.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@martinydeAI martinydeAI added documentation Improvements or additions to documentation do-not-merge Block merging until external dependency lands labels Jun 18, 2026
@martinyde martinyde requested a review from tuj June 18, 2026 11:23
@martinyde martinyde removed the do-not-merge Block merging until external dependency lands label Jun 19, 2026
@martinyde martinyde merged commit 97570a9 into chore/test-method-comments Jun 22, 2026
4 checks passed
@martinyde martinyde deleted the feature/issue-81-claude-md-symfony-practices branch June 22, 2026 08:36
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants