chore: Update claude.md, feat spec skill (#636)

* docs: Update CLAUDE.md and SKILL.md with guidelines on scope discipline and public/internal repo separation

* docs: Add feature_spec.yml template for internal feature specifications

* docs: Update CLAUDE.md and SKILL.md with scope discipline guidelines; modify feature_spec.yml title and placeholder

* docs: Add guidelines for handling refactoring in CLAUDE.md and SKILL.md

Author: jirispilka

.claude/skills/feature-spec/SKILL.md

@@ -58,6 +58,8 @@ You might have access to these resources during planning (paths marked "if avail
 Follow these when designing:
 
 - **Simple > complex, ruthlessly minimal** — only what's explicitly in scope
+- **Reuse before creating.** Search for existing helpers, patterns, and utilities that already handle similar cases. Extend what exists rather than adding new abstractions.
+- **Smallest possible feature.** Design the minimal version that solves the problem. If you're adding new parameters, methods, or abstractions, ask: is there a simpler way using what's already there?
 - **Zod** for input validation, **HelperTools enum** for tool names
 - Integration tests go in `tests/integration/suite.ts`
 - Changes may affect `apify-mcp-server-internal` — always assess impact
@@ -75,65 +77,56 @@ During planning, explore:
 5. **MCP Apps spec/SDK** if the feature involves widgets or interactive UIs — check both the spec and `node_modules/@modelcontextprotocol/ext-apps`
 6. Use `mcp__apify-dev__*` and `mcp__apify-dev-ui__*` tools to test current behavior if the dev servers are running
 
-Ask clarifying questions if the feature description is ambiguous. Prefer narrowing scope over guessing intent.
-
-## Step 5: Produce the GitHub issue
-
-When planning is complete, exit planning mode with `ExitPlanMode`, then create a GitHub issue using `gh issue create` with this structure:
+**Public/internal repo separation**: See `CLAUDE.md § Public/internal repo separation`.
 
-```markdown
-## Context and motivation
-[Why this feature is needed]
-
-## Scope
+Ask clarifying questions if the feature description is ambiguous. Prefer narrowing scope over guessing intent.
 
-### In scope
-- [bullet list]
+## Step 5: Check existing issues
 
-### Out of scope
-- [bullet list]
+Before creating anything, search for duplicates and related issues across all three repos:
 
-## Technical design
+```
+gh issue list -R apify/apify-mcp-server --search "<feature keywords>" --json number,title,state
+gh issue list -R apify/ai-team --search "<feature keywords>" --json number,title,state
+gh issue list -R apify/apify-mcp-server-internal --search "<feature keywords>" --json number,title,state
+```
 
-### Overview
-[High-level approach]
+If a matching issue exists, update it with `gh issue edit` instead of creating a new one. Reference related issues from other repos in the description.
 
-### Detailed design
-[Implementation details, referencing existing code by file path]
+## Step 6: Produce GitHub issues
 
-### Files to modify
-| File | Change |
-|------|--------|
-| `src/...` | Description |
+When planning is complete, exit planning mode with `ExitPlanMode`, then create issues.
 
-### New files (if any)
-| File | Purpose |
-|------|---------|
-| `src/...` | Description |
+**One issue per implementation phase.** A phase ≈ one PR-sized unit of work (roughly 50–200 lines changed). Example: phase 1 = add the new Zod schema + types, phase 2 = wire up the tool handler + tests. If the feature has multiple phases, create a separate issue for each. Each issue should be independently implementable.
 
-## Internal repo impact
-[Does apify-mcp-server-internal need changes? Check imports/usage.]
+Use the repo's `feature_spec.yml` template (not `feature_request.yml` — that one is for external users). Write **concrete, concise, no empty sections** issues. Only include sections that have real content for this specific issue.
 
-## Testing strategy
+```markdown
+## Problem
+[Be concrete — numbers, error messages, user reports, Slack/issue links. "Users are confused" is weak; "3 users reported X in #channel" is strong.]
 
-### Unit tests
-- [Key test cases, target files]
+## Proposed solution
+[Short explanation of the approach. Reference existing code paths. If files need changing, list them here inline — don't make a separate table unless there are 5+ files.]
 
-### Integration tests
-- [Cases to add to tests/integration/suite.ts]
+## Plan
+- [ ] Step 1 (with PR links or assignees if known)
+- [ ] Step 2
+- [ ] ...
 
-### Manual testing
-- [Steps using local dev servers, MCPJam, or ChatGPT]
+## Alternatives considered
+[Only if you actually evaluated other approaches. Skip if there's one obvious solution.]
+```
 
-## Verification checklist
-- [ ] `npm run type-check` passes
-- [ ] `npm run lint` passes
-- [ ] `npm run test:unit` passes
-- [ ] Internal repo impact assessed
-- [ ] No breaking changes (or coordinated)
+**Style rules:**
+- Skip any section that would be empty or generic
+- Lead with real evidence (data, links, screenshots), not abstract motivation
+- Keep it short — the best issues are 10-30 lines, not 100
+- A checklist plan with concrete steps beats a wall of prose
 
-## Open questions
-- [Anything needing human decision]
-```
+**Before presenting the issues**, self-review the design:
+- Is this the minimal design? Could the scope be smaller?
+- Am I reusing existing patterns or reinventing?
+- Could this be done by adjusting existing code rather than adding new code?
+- Does the feature require refactoring first? If so, split into a separate refactoring PR that must merge before the feature work begins. Never mix refactoring with feature changes — the combined diff is hard to review and easy to break.
 
-Present the issue content to the user for review before creating it. Use `gh issue create` with appropriate title and labels.
+Present the issue content to the user for review before creating. Use `gh issue create` with appropriate title and `t-ai` labels.

.github/ISSUE_TEMPLATE/feature_spec.yml

@@ -0,0 +1,46 @@
+name: Feature spec
+description: Internal feature specification with technical design and implementation plan
+title: "[spec] "
+labels: ["t-ai"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: >-
+        Be concrete — include numbers, error messages, user reports, or
+        Slack/issue links. "Users are confused" is weak; "3 users reported X in
+        #channel" is strong.
+    validations:
+      required: true
+
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed solution
+      description: >-
+        Short explanation of the approach. Reference existing code paths and
+        patterns. If files need changing, list them inline.
+    validations:
+      required: true
+
+  - type: textarea
+    id: plan
+    attributes:
+      label: Plan
+      description: >-
+        Concrete steps as checkboxes. Include assignees and PR links if known.
+        Skip for trivial changes.
+      placeholder: |
+        - [ ] Step 1
+        - [ ] Step 2
+    validations:
+      required: false
+
+  - type: textarea
+    id: alternatives
+    attributes:
+      label: Alternatives considered
+      description: Other approaches evaluated and why they were rejected. Skip if there's one obvious solution.
+    validations:
+      required: false

CLAUDE.md

@@ -18,6 +18,15 @@ The server can run in multiple modes:
 - **No over-engineering**: Solve the current problem, not hypothetical future ones
 - **No unsolicited features**: Don't add anything not explicitly requested by the human operator
 
+## Scope discipline
+
+- **Bug fix = bug fix.** When fixing a bug, fix only the bug. Don't refactor surrounding code, don't improve naming, don't add comments, don't "clean up while you're here."
+- **One thing per change.** Each change should do exactly one thing: fix a bug, add a feature, or refactor. Never combine. If you spot something unrelated that needs fixing, mention it — don't fix it.
+- **Test first.** For bug fixes, write a failing test that reproduces the bug before touching source code. Run it to confirm it fails. Then fix.
+- **Fix by adjusting, not adding.** Prefer a 1-line fix over a 10-line fix. Prefer adjusting existing code over adding new branches. Search for existing helpers and patterns that already handle similar cases. Ask: "Am I adding code, or fixing the code that's already there?"
+- **Self-review your diff.** Before declaring done, review: Is this the minimal fix? Am I reusing existing patterns? Did I leave any debug artifacts?
+- **Refactoring is a separate PR.** If a feature requires refactoring, do the refactoring first in its own PR, get it merged, then implement the feature. Never mix refactoring with feature work — the combined diff is hard to review and easy to break.
+
 ## ⚠️ MANDATORY: Verification after every implementation
 
 **THIS IS NON-NEGOTIABLE. DO NOT SKIP.**
@@ -100,6 +109,14 @@ it('should do something awesome', async () => {
 
 **IMPORTANT**: This package (`@apify/actors-mcp-server`) is used in the private `apify-mcp-server-internal` repository for the hosted server. Changes here may affect that server. Breaking changes must be coordinated; check whether updates are needed in `apify-mcp-server-internal` before submitting a PR. See README.md for canary (`beta`) releases via `pkg.pr.new`.
 
+### Public/internal repo separation (see [internal#419](https://github.com/apify/apify-mcp-server-internal/issues/419))
+
+- **Public repo** = core MCP server logic, interfaces, types (with generic/plain data types only)
+- **Internal repo** = backend/DB/proprietary logic (Redis, MongoDB, IAM auth, multi-node)
+- **Never** import private Apify libraries or internal DB schemas into the public repo — external users can't install them
+- **Expose methods on `ActorsMcpServer`**, not raw data exports via `./internals` — minimize the coupling surface
+- When designing a new feature, ask: can this land in one repo? Prefer exposing a method or interface over exporting internals that the other repo re-implements
+
 ## Further reading
 
 - **[CONTRIBUTING.md](./CONTRIBUTING.md)** — coding standards, patterns, anti-patterns, commit format, PR guidelines, design system rules