diff --git a/.github/workflows/check-claude-settings.yml b/.github/workflows/check-claude-settings.yml new file mode 100644 index 00000000000..b3141a6b8ab --- /dev/null +++ b/.github/workflows/check-claude-settings.yml @@ -0,0 +1,45 @@ +name: Check Claude Configuration + +on: + pull_request: + paths: + - '.claude/**' + - 'CLAUDE.md' + +jobs: + check-claude-config: + runs-on: ubuntu-latest + steps: + - name: Check for Claude configuration changes + uses: actions/github-script@v7 + with: + script: | + const comment = `⚠️ **Claude Configuration Warning** + + You've modified Claude Code configuration files. These files contain the shared configuration for all contributors. Please revert this change if unintended. **ONLY modify these files if you need to change shared configurations that apply to everyone and have discussed this change with the TW team.** + + To override the Claude settings locally, use \`.claude/settings.local.json\` instead. + + **For example, if you're changing AWS_PROFILE:** + The default profile name is \`my-sandbox\`. If your AWS profile has a different name, override it locally instead of changing the shared file. + + Create or edit \`.claude/settings.local.json\` in the repo root and include the following lines: + + \`\`\`json + { + "env": { + "AWS_PROFILE": "your-sandbox-name" + } + } + \`\`\` + + This local file is gitignored and overrides the repo default.`; + + github.rest.issues.createComment({ + issue_number: context.issue.number, + owner: context.repo.owner, + repo: context.repo.repo, + body: comment + }); + + core.setFailed('Claude configuration was modified - see comment for guidance'); diff --git a/CLAUDE.md b/CLAUDE.md index 0324ddc85ad..380a57902bc 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -200,3 +200,7 @@ If you are unsure whether a command is safe to run, **do not run it**. Instead, - Run tests after making changes: see project-specific test commands - Do not add dependencies without asking - Do not refactor code beyond what was requested + +### Claude Code Settings Management + +For personal configuration changes (AWS_PROFILE, etc.), always suggest `.claude/settings.local.json` instead of modifying `.claude/settings.json`. The local file is gitignored and overrides shared settings. \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4329ba491a5..33fee0d4c52 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,4 +1,5 @@ -For guidelines on contributing to the Mendix documentation, please see these two documents: +For guidelines on contributing to the Mendix documentation, see these documents: * [How to Contribute to Mendix Docs](https://docs.mendix.com/community-tools/contribute-to-mendix-docs/) * [Documentation Writing Guidelines](https://docs.mendix.com/community-tools/documentation-guidelines/) +* [Using AI Tools for Documentation](https://docs.mendix.com/community-tools/contribute-to-mendix-docs/using-ai-tools/) diff --git a/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md new file mode 100644 index 00000000000..e5957de33d5 --- /dev/null +++ b/content/en/docs/community-tools/contribute-to-mendix-docs/using-ai-tools.md @@ -0,0 +1,64 @@ +--- +title: "Using AI Tools for Documentation" +url: /community-tools/contribute-to-mendix-docs/using-ai-tools/ +weight: 30 +description: "Guidelines for using AI tools when contributing to Mendix documentation." +--- + +## Introduction + +Contributors may use AI tools such as large language models and writing assistants to draft or improve documentation. However, these tools must be treated as writing aids, like spell-checkers or linters, and not as authoritative sources. + +## Contributor Responsibility + +If you use AI tools, before contributing, you must: + +* Review and verify the accuracy of all AI-assisted content. +* Ensure the content does not infringe on third-party copyrights. +* Remove hallucinated content or unsupported claims. +* Confirm that the AI tool's terms do not impose restrictions inconsistent with Mendix's contributors license agreement. + +AI output must be treated as unverified draft material. + +## Maintainer Discretion + +Maintainers may request clarification, edits, or removal of AI-assisted content if concerns arise regarding accuracy, licensing, or quality. + +## Using AI Assistants + +This repository is configured for use with [Claude Code](https://code.claude.com/docs/en/vs-code), an AI-powered coding assistant. There is also GitHub Copilot customization for contributors who use it. + +### Claude Code Configuration + +The default AWS profile name is `my-sandbox`. If your AWS sandbox profile has a different name, create `.claude/settings.local.json` in the repo root and include the following lines: + +```json +{ + "env": { + "AWS_PROFILE": "your-sandbox-name" + } +} +``` + +This file is gitignored and will override the shared settings. + +{{% alert color="warning" %}} +Do not modify `.claude/settings.json` or other files in the `.claude/` directory for personal configuration. These files contain shared configuration for all contributors. +{{% /alert %}} + +### Custom Skills + +This repository includes custom Claude Code skills optimized for documentation work: + +* `/proofread` - Checks spelling, grammar, punctuation, and basic Markdown formatting +* `/polish` - Improves clarity, readability, and word choice without changing meaning +* `/enhance` - Performs comprehensive editing including reorganization, restructuring, and stronger phrasing +* `/review` - Analyzes documentation and generates suggestions for improvements +* `/add` - Adds new content to an existing page while preserving original structure + +These skills are available to all contributors using Claude Code with this repository. + +## Read More + +* [Contributing to Mendix Docs](/community-tools/contribute-to-mendix-docs/) +* [Documentation Writing Guidelines](/community-tools/documentation-guidelines/)