157 lines
7.3 KiB
Markdown
157 lines
7.3 KiB
Markdown
# CLAUDE.md
|
||
|
||
## Defaults
|
||
|
||
- Reply in **Chinese** unless I explicitly ask for English.
|
||
- No emojis.
|
||
- Do not truncate important outputs (logs, diffs, stack traces, commands, or critical reasoning that affects
|
||
safety/correctness).
|
||
|
||
## Refactor policy (legacy code)
|
||
|
||
- When existing code is a "big ball of mud" (hard to maintain, clearly bad design,
|
||
full of hacks), prefer a **clean, full refactor** over stacking more patches
|
||
on top of it.
|
||
- A refactor may completely replace internal structure
|
||
(functions, modules, classes, data flow).
|
||
- By default, try to preserve externally observable behaviour.
|
||
If you intentionally change behaviour or protocols, you MUST:
|
||
- Call out clearly that this is a **behaviour/protocol change**.
|
||
- Explain why the change is necessary and which code paths/consumers are affected.
|
||
- Update or add tests to cover the new behaviour.
|
||
|
||
## Before touching code (mandatory)
|
||
|
||
Find reuse opportunities + Trace the call/dependency chain and impact radius:
|
||
|
||
- Use semantic code search first via `codebase-retrieval` tool.
|
||
- Confirm understanding with LSP: `goToDefinition`, `findReferences`.
|
||
- Use Grep/Glob for verifying and understanding additional code snippets.
|
||
|
||
## Red lines
|
||
|
||
- No copy-paste duplication.
|
||
- Do not break existing externally observable behaviour **unless**:
|
||
- It is part of a deliberate refactor as described in the refactor policy, and
|
||
- You clearly document the behavioural change and its impact.
|
||
- Do not proceed with a known-wrong approach.
|
||
- Critical paths must have explicit error handling.
|
||
- Never implement "blindly": always confirm understanding via code reading + references.
|
||
|
||
## Task sizing
|
||
|
||
- **Simple**
|
||
- Criteria — single file, clear requirement, < 20 lines changed,
|
||
clearly local impact.
|
||
- Handling — after doing the "Before touching code" steps
|
||
(research + impact analysis + internal three-question checklist),
|
||
you may execute directly with minimal explanation.
|
||
- A very short context line is enough;
|
||
a full breakdown of the checklist is not required.
|
||
|
||
- **Medium**
|
||
- Criteria — 2–5 files, or requires some research, or impact is not obviously local.
|
||
- Handling — write a short plan (bullet points) → then implement.
|
||
- Briefly surface the checklist result in the reply
|
||
(1–3 short lines describing real issue, key reuse, and main impact).
|
||
|
||
- **Complex**
|
||
- Criteria — architecture changes, multiple modules, high uncertainty or risk.
|
||
- Handling — follow this workflow:
|
||
1. **RESEARCH**: inspect code and facts only (no proposals yet).
|
||
2. **PLAN**: present options + tradeoffs + recommendation;
|
||
use `AskUserQuestion` actively to align with the user;
|
||
wait for user's confirmation.
|
||
3. **EXECUTE**: implement exactly the approved plan.
|
||
4. **REVIEW**: self-check (tests, edge cases, cleanup).
|
||
|
||
## Git
|
||
|
||
- Do not commit unless I explicitly ask.
|
||
- Do not push unless I explicitly ask.
|
||
- Before writing a commit message, glance at a few recent commits and match the repo's style:
|
||
- `git log -n 5 --oneline`
|
||
- If there is no obvious existing style, use this default format:
|
||
- `<type>(<scope>): <description>`
|
||
- Before any commit: run `git diff` and confirm the exact scope of changes.
|
||
- Never force-push to `main` / `master` unless the user approves.
|
||
- Do not add attribution lines in commit messages.
|
||
|
||
## Security
|
||
|
||
- Never hardcode secrets (keys/passwords/tokens).
|
||
- Never commit `.env` files or any credentials.
|
||
- Validate user input at trust boundaries (APIs, CLIs, external data sources).
|
||
|
||
## Quality & cleanup
|
||
|
||
- Prefer clarity and simplicity first (KISS); apply DRY to remove obvious
|
||
copy-paste duplication when it does not hurt readability.
|
||
- If you change a function signature, update **all** call sites.
|
||
- After changes:
|
||
- Remove temporary files.
|
||
- Remove dead/commented-out code.
|
||
- Remove unused imports.
|
||
- Remove debug logging that is no longer needed.
|
||
- Run the smallest meaningful verification (lint/test/build) for the parts you touched.
|
||
|
||
## Windows / PowerShell (if used)
|
||
|
||
- PowerShell does not support `&&`; use `;` to chain commands.
|
||
- Quote paths that contain spaces or non-ASCII characters.
|
||
|
||
## Baisc Infos
|
||
|
||
Unless directly relevant to the user's current question, you should avoid proactively mentioning, illustrating, or
|
||
trailing off into the following information in 99% of cases:
|
||
|
||
## Documentation
|
||
|
||
- 所有产生的文档（需求文档、计划文档、分析文档等）统一放到项目内的 `.docs` 文件夹中
|
||
- 文档目录结构：
|
||
- 不要将文档放到用户目录（如 `C:\Users\EDY\.claude\`）中
|
||
|
||
<!-- gitnexus:start -->
|
||
# GitNexus — Code Intelligence
|
||
|
||
This project is indexed by GitNexus as **SuperBizAgent-java** (13483 symbols, 22230 relationships, 300 execution flows). Use the GitNexus MCP tools to understand code, assess impact, and navigate safely.
|
||
|
||
> If any GitNexus tool warns the index is stale, run `npx gitnexus analyze` in terminal first.
|
||
|
||
## Always Do
|
||
|
||
- **MUST run impact analysis before editing any symbol.** Before modifying a function, class, or method, run `gitnexus_impact({target: "symbolName", direction: "upstream"})` and report the blast radius (direct callers, affected processes, risk level) to the user.
|
||
- **MUST run `gitnexus_detect_changes()` before committing** to verify your changes only affect expected symbols and execution flows.
|
||
- **MUST warn the user** if impact analysis returns HIGH or CRITICAL risk before proceeding with edits.
|
||
- When exploring unfamiliar code, use `gitnexus_query({query: "concept"})` to find execution flows instead of grepping. It returns process-grouped results ranked by relevance.
|
||
- When you need full context on a specific symbol — callers, callees, which execution flows it participates in — use `gitnexus_context({name: "symbolName"})`.
|
||
|
||
## Never Do
|
||
|
||
- NEVER edit a function, class, or method without first running `gitnexus_impact` on it.
|
||
- NEVER ignore HIGH or CRITICAL risk warnings from impact analysis.
|
||
- NEVER rename symbols with find-and-replace — use `gitnexus_rename` which understands the call graph.
|
||
- NEVER commit changes without running `gitnexus_detect_changes()` to check affected scope.
|
||
|
||
## Resources
|
||
|
||
| Resource | Use for |
|
||
|----------|---------|
|
||
| `gitnexus://repo/SuperBizAgent-java/context` | Codebase overview, check index freshness |
|
||
| `gitnexus://repo/SuperBizAgent-java/clusters` | All functional areas |
|
||
| `gitnexus://repo/SuperBizAgent-java/processes` | All execution flows |
|
||
| `gitnexus://repo/SuperBizAgent-java/process/{name}` | Step-by-step execution trace |
|
||
|
||
## CLI
|
||
|
||
| Task | Read this skill file |
|
||
|------|---------------------|
|
||
| Understand architecture / "How does X work?" | `.claude/skills/gitnexus/gitnexus-exploring/SKILL.md` |
|
||
| Blast radius / "What breaks if I change X?" | `.claude/skills/gitnexus/gitnexus-impact-analysis/SKILL.md` |
|
||
| Trace bugs / "Why is X failing?" | `.claude/skills/gitnexus/gitnexus-debugging/SKILL.md` |
|
||
| Rename / extract / split / refactor | `.claude/skills/gitnexus/gitnexus-refactoring/SKILL.md` |
|
||
| Tools, resources, schema reference | `.claude/skills/gitnexus/gitnexus-guide/SKILL.md` |
|
||
| Index, status, clean, wiki CLI commands | `.claude/skills/gitnexus/gitnexus-cli/SKILL.md` |
|
||
|
||
<!-- gitnexus:end -->
|