Claude Architect · Oppitunti

Projektin ja käyttäjän laajuus

.mcp.json jaettuna VCS:ssä vs. henkilökohtainen ~/.claude.json.

Oppitunti 2/413 vaihetta

Projektin ja käyttäjän laajuus on ilmainen Claude Architect-oppitunti CoddyKitissä. Tämä on oppitunti 2/4. Voit lukea tästä oppimispolusta kokonaan mitkä tahansa 3 oppituntia ilmaiseksi — sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä käytännön harjoittelun sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Oppitunti kuuluu Claude Architect-oppimispolkuun, ja edistymisesi synkronoituu verkon ja CoddyKit-sovelluksen välillä. Claude Architect-kurssilla on yhteensä 4 oppituntia.

MCP-määrityksen kaksi sijaintia

Kun liität MCP-palvelimen Claude Codeen, palvelimen määrityksen on sijaittava jossakin. Käytettävissä on kaksi tasoa, ja väärän valitseminen on tyypillinen arkkitehtuurivirhe.

Projektitaso — repositorion juuressa oleva .mcp.json, joka viedään versionhallintaan. Jaettu koko tiimille.
Käyttäjätaso — kotihakemistossasi oleva ~/.claude.json. Henkilökohtainen, eikä sitä koskaan jaeta versionhallinnan kautta.

Päätössääntö on yksinkertainen: tarvitsevatko kaikki tätä repositoriota työstävät tätä palvelinta? Jos kyllä, se kuuluu projektitasolle.

Mitä MCP-palvelin tarjoaa

Muista ennen tason valitsemista, mitä oikeastaan jaat. MCP-palvelin tarjoaa kolmenlaisia perusominaisuuksia:

Tools — toimintoja, joita malli voi kutsua (esimerkiksi tietokannan kysely tai tiketin avaaminen).
Resources — vain luku -muotoista dataa ja kontekstia, kuten skeemoja tai luetteloita.
Prompts — uudelleenkäytettäviä mallipohjia.

Kun viet palvelimen .mcp.json-tiedostoon, jokainen tiimikaveri saa heti samat Tools-, Resources- ja Prompts-ominaisuudet — yhteisen ja toistettavan toimintopinnan.

Projektitaso: .mcp.json versionhallinnassa

Projektitaso on oikea paikka palvelimille, joihin koko tiimi luottaa: yrityksen GitHub-palvelimelle, sisäiselle tietokantayhdyskäytävälle tai jaetulle suunnittelujärjestelmän resurssipalvelimelle.

Koska .mcp.json viedään versionhallintaan, uusi tiimikaveri kloonaa repositorion ja työkalut ovat jo valmiina — manuaalista määritystä ei tarvita, eikä synny "toimii minun koneellani" -eroja.

{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"],
      "env": {
        "GITHUB_TOKEN": "${GITHUB_TOKEN}"
      }
    }
  }
}

Salaisuuksia ei koskaan viedä versionhallintaan

Palvelimen määrityksen jakaminen on sopivaa. Tokenin jakaminen on tietoturvaloukkaus. Sääntö on tämä: viittaa salaisuuksiin ympäristömuuttujilla — älä koskaan vie raakaa arvoa versionhallintaan.

Kirjoita .mcp.json-tiedostoon ${GITHUB_TOKEN}, joka laajennetaan kunkin kehittäjän omasta ympäristöstä suorituksen aikana. Jaettu tiedosto kuvaa miten yhteys muodostetaan; kukin kone toimittaa omat tunnistetietonsa.

# Each developer exports their own token locally
export GITHUB_TOKEN="ghp_yourPersonalTokenHere"

# .mcp.json references it as ${GITHUB_TOKEN} — the
# literal token value is NEVER written into the repo

Käyttäjätaso: ~/.claude.json

Käyttäjätaso sijaitsee tiedostossa ~/.claude.json ja on henkilökohtainen. Se on oikea paikka palvelimille, jotka ovat omia ja haittaisivat tiimikaveria, jos ne jaettaisiin:

Henkilökohtaisten muistiinpanojen tai toisen aivon palvelin.
Kokeellinen palvelin, jota arvioit.
Työnkulun työkalu, joka on sidottu omiin käyttäjätileihisi.

On tärkeää huomata, että käyttäjätasoa ei jaeta versionhallinnan kautta — uudet tiimikaverit eivät saa sitä käyttöönsä.

{
  "mcpServers": {
    "my-notes": {
      "command": "node",
      "args": ["/Users/me/tools/notes-mcp/server.js"]
    }
  }
}

Ajattelumalli: CLAUDE.md:n peilikuva

Tämä tasojen jako vastaa täsmälleen CLAUDE.md-hierarkiaa — sama periaate, eri tiedosto:

Projektitaso (./CLAUDE.md, .mcp.json) — jaetaan versionhallinnan kautta, joten kaikki saavat sen.
Käyttäjätaso (~/.claude/CLAUDE.md, ~/.claude.json) — henkilökohtainen, EI jaeta, joten uudet tiimikaverit eivät saa sitä.

Sama logiikka koskee hakemistoja .claude/skills/ ja .claude/commands/: projektitaso jaetaan versionhallinnan kautta, kun taas hakemiston ~/.claude/ kopiot ovat henkilökohtaisia.

Käyttöönottotesti

Paras tapa päättää taso on kysyä: "Pitäisikö tämän toimia heti, kun uusi tiimikaveri kloonaa repositorion?"

Kyllä → projektitaso (.mcp.json). Hän kloonaa repositorion, palvelin on määritetty ja työ voi alkaa heti ensimmäisenä päivänä.
Ei, tämä on minun → käyttäjätaso (~/.claude.json).

Jos sijoitat tiimille kriittisen palvelimen käyttäjätasolle, luot näkymättömän riippuvuuden: se toimii sinulla, epäonnistuu hiljaisesti kaikilla muilla, eikä kukaan tiedä miksi.

Suosi yhteisön palvelimia räätälöityjen sijaan

Vakiomuotoisissa integraatioissa — GitHub, Slack, Postgres ja tiedostojärjestelmä — suosi yhteisön MCP-palvelinta oman rakentamisen sijaan. Ylläpidettävää koodia on vähemmän, toiminta on hyvin testattua ja palvelin sopii suoraan projektitasolle.

Räätälöidyt palvelimet kannattaa varata aidosti omisteisille järjestelmille, joihin ei ole saatavilla yhteisön vaihtoehtoa. Valinnastasi riippumatta tasopäätös on sama: koko tiimille → .mcp.json; henkilökohtaiseen käyttöön → ~/.claude.json.

Resurssit ovat parhaimmillaan projektitasolla

MCP:n Resource tarjoaa vain luku -muotoista kontekstia — esimerkiksi tietokannan skeeman, API-luettelon tai koodausstandardien dokumentin. Juuri tällaisten asioiden tiimi haluaa olevan identtisiä jokaisella kehittäjällä.

Kun toimitat skeeman tarjoavan palvelimen tiedostossa .mcp.json, jokaisen tiimikaverin Claude näkee saman auktoritatiivisen skeeman. Kukaan ei tee kyselyitä vanhentuneen mielikuvan perusteella, ja vastaukset pysyvät yhdenmukaisina koko tiimissä.

{
  "mcpServers": {
    "db-schema": {
      "command": "npx",
      "args": ["-y", "@acme/mcp-schema-server"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

Jäsennellyt virheet toimivat kummallakin tasolla

Taso määrittää missä palvelin on määritetty, ei sitä, kuinka vankka se on. Hyvin rakennettu MCP-palvelin palauttaa jäsenneltyjä virheitä tasosta riippumatta: isError-lipun sekä errorCategory-luokan (transient / validation / business / permission), isRetryable-arvon, viestin, yritetyn kyselyn ja mahdolliset osittaiset tulokset.

Yleiset virheet, kuten "Operation failed", estävät älykkään palautumisen; jäsennellyt virheet antavat agentille mahdollisuuden reitittää, yrittää uudelleen tai eskaloida ongelman. Suunnittele tämä osaksi palvelinta — siitä on hyötyä riippumatta siitä, jaetaanko palvelin vai käytätkö sitä henkilökohtaisesti.

{
  "isError": true,
  "errorCategory": "transient",
  "isRetryable": true,
  "message": "Upstream timeout contacting issues API",
  "attempted_query": "list_issues(repo='acme/web')",
  "partial_results": []
}

Käytännön jako

Realistisessa määrityksessä molemmat tasot toimivat siististi yhdessä:

Projekti (.mcp.json, viety versionhallintaan): GitHub-palvelin, sisäinen tietokantayhdyskäytävä ja skeemaresurssipalvelin — kaikki, mitä tiimi tarvitsee tämän tuotteen rakentamiseen.
Käyttäjä (~/.claude.json, yksityinen): henkilökohtaisten muistiinpanojesi palvelin ja kokeellinen työkalu, jota testaat.

Kaksi tasoa täydentävät toisiaan: Claude Code lataa molemmat, joten saat jaetun tiimin toimintopinnan ja omat lisätyökalusi ilman, että repositorio täyttyy ylimääräisestä tai henkilökohtaiset työkalusi vuotavat tiimikavereille.

Pikatarkistus: tason valinta

Sovella päätössääntöä todelliseen tilanteeseen.

Vastaa interaktiivisessa oppitunnissa

Kertaus: projekti- ja käyttäjätaso

Tärkeimmät asiat:

Projektitaso = .mcp.json, viety versionhallintaan ja jaettu koko tiimille. Käytä sitä, kun kaikkien pitää saada palvelin käyttöön repositorion kloonauksen yhteydessä.
Käyttäjätaso = ~/.claude.json, henkilökohtainen, eikä sitä jaeta versionhallinnan kautta. Käytä sitä yksityisiin tai kokeellisiin palvelimiisi.
Rakenne peilaa CLAUDE.md-hierarkiaa: projektitaso jaetaan, käyttäjätaso on henkilökohtainen eivätkä uudet tiimikaverit saa sitä.
Älä koskaan vie salaisuuksia versionhallintaan — viittaa niihin ympäristömuuttujilla, kuten ${GITHUB_TOKEN}.
Suosi yhteisön palvelimia vakiomuotoisissa integraatioissa ja suunnittele jäsennellyt virheet tasosta riippumatta.

Muista tämä päätössääntö: pitäisikö uuden tiimikaverin saada tämä heti repositorion kloonauksen yhteydessä? Kyllä → projekti. Oma → käyttäjä.

Aloita maksutta

Opi Python tekoälytuutorin avulla — ilmaiseksi

Kirjoita ja suorita oikeaa koodia selaimessa, saa välitöntä apua tekoälytuutorilta ympäri vuorokauden ja jatka siitä, mihin jäit, verkossa tai sovelluksessa.

Kurssit: 26
Oppitunnit: 104

Aloita opiskelu maksutta Näytä koko kurssi

Usein kysytyt kysymykset

Onko oppitunti ”Projektin ja käyttäjän laajuus” ilmainen?

Kyllä — voit lukea täällä verkossa kokonaan ilmaiseksi mitkä tahansa Claude Architect-oppimispolun 3 oppituntia, myös oppitunnin “Projektin ja käyttäjän laajuus”. Sen jälkeen CoddyKit PRO avaa kaikki oppitunnit sekä interaktiiviset harjoitukset sisäänrakennetulla koodieditorilla ja ympäri vuorokauden toimivalla tekoälytuutorilla. Claude Architect-kurssilla on yhteensä 4 oppituntia.

Mitä opin oppitunnilla ”Projektin ja käyttäjän laajuus”?

.mcp.json jaettuna VCS:ssä vs. henkilökohtainen ~/.claude.json. Harjoittelet Claude Architect-aihetta koodilla, jonka suoritat suoraan selaimessa. Ympäri vuorokauden käytettävissä oleva tekoälytuutori vastaa kysymyksiisi oppitunnin aikana.

Tarvitsenko kokemusta aloittaakseni Claude Architect-opiskelun?

Aiempi kokemus ei ole tarpeen. CoddyKitin Claude Architect-oppimispolku sopii vasta-alkajista edistyneisiin, joten voit aloittaa tästä tai alusta ja edetä omaan tahtiisi. Tämä on oppitunti 2/4.

Kuinka kauan ”Projektin ja käyttäjän laajuus”-oppitunnin suorittaminen kestää?

Useimmat CoddyKitin oppitunnit kestävät noin 5–10 minuuttia. Jokainen oppitunti on lyhyt ja interaktiivinen, joten edistyt tasaisesti ja voit jatkaa siitä, mihin jäit – sekä verkossa että sovelluksessa.

Voinko kirjoittaa ja suorittaa koodia tällä Claude Architect-oppitunnilla?

Kyllä. Jokainen Claude Architect-oppitunti sisältää sisäänrakennetun koodieditorin, joten voit kirjoittaa ja suorittaa oikeaa koodia suoraan selaimessa ja saada välitöntä palautetta tekoälyltä – paikallista asennusta ei tarvita.

Kaikki tämän kurssin oppitunnit

Työkalut, resurssit ja kehotteet
Projektin ja käyttäjän laajuus
Salaisuudet ympäristömuuttujilla
Yhteisöpalvelimet ja mukautetut palvelimet

← Takaisin: Claude Architect