Skip to content

Instantly share code, notes, and snippets.

@wtsnz

wtsnz/install-credo.md

Created April 7, 2026 19:19
Show Gist options

  • Select an option

    Learn more about clone URLs
  • Save wtsnz/8000587d0690cc224a91cd0eea33fb29 to your computer and use it in GitHub Desktop.

Select an option

Learn more about clone URLs
Save wtsnz/8000587d0690cc224a91cd0eea33fb29 to your computer and use it in GitHub Desktop.
Download ZIP
LLM Credo Installation Guide
Raw
install-credo.md

Credo Installation Guide

Practical baseline for installing Credo in Elixir apps and umbrella apps.

Goals:

  • explicit lint policy
  • predictable upgrades
  • low-noise default setup
  • optional stricter checks later

Package Choice

Recommended baseline:

  • credo: core static analysis and style checks

Optional add-on:

  • ex_slop: extra opinionated checks for common LLM/code-slop patterns

Suggested posture:

  • start with Credo
  • add ExSlop only if the team wants the extra opinions
  • keep strict mode as an audit pass first, not the initial gate

1. Add Dependencies

Baseline:

defp deps do
  [
    {:credo, "~> 1.7", only: [:dev, :test], runtime: false}
  ]
end

Optional ExSlop:

defp deps do
  [
    {:credo, "~> 1.7", only: [:dev, :test], runtime: false},
    {:ex_slop, "~> 0.2", only: [:dev, :test], runtime: false}
  ]
end

Fetch deps:

mix deps.get

2. Generate A Starting Config

mix credo gen.config

That creates a root .credo.exs. Keep one named config, usually default.

3. Use An Explicit Config Shape

Recommended structure:

%{
  configs: [
    %{
      name: "default",
      files: %{
        included: [
          "lib/",
          "src/",
          "test/",
          "web/",
          "apps/*/lib/",
          "apps/*/src/",
          "apps/*/test/",
          "apps/*/web/"
        ],
        excluded: [
          ~r"/_build/",
          ~r"/deps/",
          ~r"/node_modules/"
        ]
      },
      plugins: [],
      requires: [],
      strict: false,
      parse_timeout: 5000,
      color: true,
      checks: %{
        enabled: [
          # explicit list
        ],
        disabled: [
          # explicit opt-in list
        ]
      }
    }
  ]
}

Why explicit lists:

  • upgrades stay predictable
  • new checks do not silently start failing CI
  • lint-policy changes are easy to review

Tradeoff:

  • when upgrading Credo, someone must review release notes and decide whether to adopt new checks

4. Recommended Built-in Credo Baseline

This is a practical, low-drama baseline for most Elixir apps.

Consistency

  • ExceptionNames
  • LineEndings
  • ParameterPatternMatching
  • SpaceAroundOperators
  • SpaceInParentheses
  • TabsOrSpaces

Design

  • AliasUsage
  • TagFIXME

Readability

  • AliasOrder
  • FunctionNames
  • LargeNumbers
  • MaxLineLength
  • ModuleAttributeNames
  • ModuleNames
  • ParenthesesInCondition
  • ParenthesesOnZeroArityDefs
  • PipeIntoAnonymousFunctions
  • PredicateFunctionNames
  • PreferImplicitTry
  • RedundantBlankLines
  • Semicolons
  • SpaceAfterCommas
  • StringSigils
  • TrailingBlankLine
  • TrailingWhiteSpace
  • UnnecessaryAliasExpansion
  • VariableNames
  • WithSingleClause

Refactor

  • Apply
  • CondStatements
  • CyclomaticComplexity
  • FilterCount
  • FilterFilter
  • FunctionArity
  • LongQuoteBlocks
  • MapJoin
  • MatchInCondition
  • NegatedConditionsInUnless
  • NegatedConditionsWithElse
  • Nesting
  • RedundantWithClauseResult
  • RejectReject
  • UnlessWithElse
  • WithClauses

Warning

  • ApplicationConfigInModuleAttribute
  • BoolOperationOnSameValues
  • Dbg
  • ExpensiveEmptyEnumCheck
  • IExPry
  • IoInspect
  • MissedMetadataKeyInLoggerConfig
  • OperationOnSameValues
  • OperationWithConstantResult
  • RaiseInsideRescue
  • SpecWithStruct
  • StructFieldAmount
  • UnsafeExec
  • UnusedEnumOperation
  • UnusedFileOperation
  • UnusedKeywordOperation
  • UnusedListOperation
  • UnusedMapOperation
  • UnusedPathOperation
  • UnusedRegexOperation
  • UnusedStringOperation
  • UnusedTupleOperation
  • WrongTestFilename

5. Suggested Built-in Customizations

These keep the baseline useful without making it noisy.

Enable with params:

  • Credo.Check.Design.AliasUsage
    • priority: :low
    • if_nested_deeper_than: 2
    • if_called_more_often_than: 0
  • Credo.Check.Readability.MaxLineLength
    • priority: :low
    • max_length: 120

Often disabled in the first pass:

  • Credo.Check.Design.TagTODO
  • Credo.Check.Readability.ModuleDoc

Reasonable defaults:

  • TODOs are often issue-tracking artifacts, not lint failures
  • mandatory module docs can add churn before a codebase has settled

6. Optional ExSlop Checks

No plugin registration is needed. Add the checks directly to checks.enabled.

Refactor

  • CaseTrueFalse
  • FilterNil
  • IdentityMap
  • IdentityPassthrough
  • MapIntoLiteral
  • ReduceAsMap
  • RejectNil
  • SortThenReverse
  • StringConcatInReduce
  • TryRescueWithSafeAlternative
  • WithIdentityDo
  • WithIdentityElse

Warning

  • BlanketRescue
  • QueryInEnumMap
  • RepoAllThenFilter
  • RescueWithoutReraise

Good fit:

  • teams cleaning up generated or AI-assisted code
  • teams that want stronger pressure toward idiomatic Elixir

Less ideal as a day-one default:

  • legacy codebases with lots of existing style debt
  • teams that have not yet agreed on stricter refactor rules

7. Suggested Opt-in Checks To Leave Disabled At First

These are useful, but commonly better as a second-pass rollout:

  • Refactor.UtcNowTruncate
  • Design.DuplicatedCode
  • Design.SkipTestWithoutComment
  • Readability.Specs
  • Readability.StrictModuleLayout
  • Refactor.ABCSize
  • Refactor.VariableRebinding
  • Warning.MixEnv
  • Warning.UnsafeToAtom

General rule:

  • if a check creates recurring team debate, leave it opt-in until the team agrees to enforce it

8. First Run Strategy

Start with normal-priority issues:

mix credo --all

Useful commands:

mix credo
mix credo lib/my_app/foo.ex:123
mix credo --only readability
mix credo --only warning
mix credo --strict

Recommended rollout order:

  1. install Credo and get mix credo --all green
  2. tune noisy checks in .credo.exs
  3. add ExSlop if desired
  4. run mix credo --strict as an audit pass
  5. only then decide whether strict mode belongs in CI

9. Wire It Into Automation

Minimum enforcement:

  • add credo to mix precommit
  • run mix credo in CI

Suggested alias:

defp aliases do
  [
    precommit: [
      "compile --warnings-as-errors",
      "deps.unlock --unused",
      "format",
      "credo",
      "test"
    ]
  ]
end

Only switch to this if the repo is already clean enough:

"credo --strict"

Suggested CI gate:

mix format --check-formatted
mix credo
mix test

10. Maintenance Notes

  • keep excludes narrow and intentional
  • prefer fixing issues over piling up ignores
  • review new Credo releases before upgrading
  • when investigating a warning, use mix credo path/to/file.ex:line
  • if a repo has generated code or teaching/example code, exclude only those paths, not entire top-level trees

References

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment