Claude Code ਲਈ ਦਸਤਾਵੇਜ਼ ਡਰਿਫਟ: README, API ਅਤੇ ਰਨਬੁੱਕ ਨੂੰ ਕੋਡ ਨਾਲ ਮਿਲਾਓ

ਦਸਤਾਵੇਜ਼ ਡਰਿਫਟ ਕੀ ਹੈ (ਅਤੇ ਇਹ ਮੁੜ-ਮੁੜ ਕਿਉਂ ਹੁੰਦੀ ਰਹਿੰਦੀ ਹੈ)

ਦਸਤਾਵੇਜ਼ ਡਰਿਫਟ ਉਹ ਹੌਲੀ ਜਿਹੀ ਵੱਖਰਾ ਹੋਣਾ ਹੈ ਜਿੱਥੇ ਤੁਹਾਡੇ docs ਜੋ ਕਹਿੰਦੇ ਹਨ ਅਤੇ ਜੋ ਤੁਹਾਡਾ ਕੋਡ ਅਸਲ ਵਿੱਚ ਕਰਦਾ ਹੈ, ਉਹ ਇੱਕ-ਦੂਜੇ ਤੋਂ ਹਟ ਜਾਂਦੇ ਹਨ। ਇਹ ਛੋਟੇ-ਛੋਟੇ ਅੰਤਰਾਂ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ, ਫਿਰ ਉਹ "ਅਸੀਂ ਕਹਿੰਦੇ ਸੀ ਇਹ ਪਿਛਲੇ ਮਹੀਨੇ ਚੱਲਦਾ ਸੀ" ਵਾਲੀ ਗੁੰਝਲਦਾਰ ਸਥਿਤੀ ਬਣ ਜਾਂਦੀ ਹੈ।

ਅਸਲ ਟੀਮ ਵਿੱਚ, ਡਰਿਫਟ ਐਸਾ ਦਿਖਦਾ ਹੈ: README ਦੱਸਦਾ ਹੈ ਕਿ ਇੱਕ ਕਮਾਂਡ ਨਾਲ ਸੇਵਾ ਚਲਾਉਣੀ ਹੈ, ਪਰ ਹੁਣ ਇੱਕ ਨਵਾਂ environment variable ਲਾਜ਼ਮੀ ਹੋ ਗਿਆ ਹੈ। API docs ਇੱਕ ਐਂਡਪਾਇੰਟ ਵਿੱਚ ਇੱਕ ਫੀਲਡ ਦਿਖਾਉਂਦੇ ਹਨ ਜਿਸ ਦਾ ਨਾਂ ਬਦਲ ਚੁੱਕਾ ਹੈ। ਇੱਕ runbook on-call ਨੂੰ "worker-a" ਨੂੰ restart ਕਰਨ ਲਈ ਕਹਿੰਦਾ ਹੈ, ਪਰ ਹੁਣ ਉਹ ਪ੍ਰੋਸੈਸ ਦੋ ਸਰਵਿਸਾਂ ਵਿੱਚ ਵੰਡਿਆ ਗਿਆ ਹੈ।

ਡਰਿਫਟ ਵਧਦਾ ਹੈ ਭਾਵੇਂ ਇਰਾਦੇ ਚੰਗੇ ਹੋਣ, ਕਿਉਂਕਿ ਸਾਫਟਵੇਅਰ ਦਸਤਾਵੇਜ਼ੀ ਆਦਤਾਂ ਤੋਂ ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਦਾ ਹੈ। ਲੋਕ ਦਬਾਅ ਹੇਠਾਂ ਫਿਕਸ ਸ਼ਿਪ ਕਰਦੇ ਹਨ, ਪੁਰਾਣੇ ਉਦਾਹਰਣਾਂ ਨੂੰ ਕਾਪੀ ਕਰ ਲੈਂਦੇ ਹਨ, ਜਾਂ ਸੋਚਦੇ ਹਨ ਕਿ ਕੋਈ ਹੋਰ ਬਾਅਦ ਵਿੱਚ docs ਅਪਡੇਟ ਕਰੇਗਾ। ਇਹ ਉਸ ਵੇਲੇ ਵੀ ਵਧਦਾ ਹੈ ਜਦੋਂ ਤੁਹਾਡੇ ਕੋਲ ਬਹੁਤ ਸਾਰੇ "source of truth" ਜਗ੍ਹਾਂ ਹੁੰਦੀਆਂ ਹਨ: README ਫਾਇਲਾਂ, API references, ਅੰਦਰੂਨੀ wiki ਪੇਜ, ਟਿਕਟ, ਅਤੇ tribal knowledge.

ਲਾਗਤਾਂ ਸਾਫ਼-ਸੁਥਰੀਆਂ ਹਨ:

• Onboarding ਟੁੱਟਦਾ ਹੈ (ਨਵੇਂ ਹਾਇਰ ਸੈਟਅਪ ਸਮੱਸਿਆਵਾਂ ਕਾਰਨ ਦਿਨ ਗਵਾ ਬੈਠਦੇ ਹਨ)।
• Deploy ਫੇਲ ਹੁੰਦੇ ਹਨ (ਕਦਮ ਮੌਜੂਦਾ config ਨਾਲ ਮੇਲ ਨਹੀਂ ਖਾਂਦੇ)।
• Support ਦੀ ਭਾਰ ਘਟਦੀ ਨਹੀਂ (ਯੂਜ਼ਰ outdated ਨਿਰਦੇਸ਼ਾਂ ਦੀ ਪਾਲਣਾ ਕਰਦੇ ਹਨ)।
• Incident ਲੰਬੇ ਚੱਲਦੇ ਹਨ (runbooks responders ਨੂੰ ਗਲਤ ਰਸਤੇ 'ਤੇ ਭੇਜਦੇ ਹਨ)।

ਸਿਰਫ਼ ਲਿਖਤ ਸੁਧਾਰ ਕਰਕੇ ਡਰਿਫਟ ਸੁਧਰਦਾ ਨਹੀਂ ਜੇ ਤੱਥ ਗਲਤ ਹਨ। ਮਦਦ ਇਹ ਹੁੰਦੀ ਹੈ ਕਿ docs ਨੂੰ ਇਸ ਤਰ੍ਹਾਂ ਵਰਤੋਂ ਜੋ ਤੁਸੀਂ ਵੈਰੀਫਾਈ ਕਰ ਸਕੋ: ਉਨ੍ਹਾਂ ਨੂੰ ਮੌਜੂਦਾ ਕੋਡ, configs, ਅਤੇ ਅਸਲੀ ਆਉਟਪੁੱਟ ਨਾਲ ਤੁਲਨਾ ਕਰੋ, ਫਿਰ ਜਿੱਥੇ ਦਸਤਾਵੇਜ਼ ਉਹ ਵਰਤਿਆ ਰਵੱਈਆ ਵਾਅਦਾ ਕਰਦਾ ਹੈ ਜੋ ਕੋਡ ਹੁਣ ਨਹੀਂ ਕਰਦਾ, ਉਥੇ ਵਿਰੋਧ ਦਿਖਾਓ।

ਡਰਿਫਟ ਕਿੱਥੇ ਦਿਖਾਈ ਦਿੰਦਾ ਹੈ: README, API docs, ਅਤੇ runbooks

ਡਰਿਫਟ ਆਮ ਤੌਰ 'ਤੇ ਉਹਨਾਂ ਦਸਤਾਵੇਜ਼ਾਂ ਵਿੱਚ ਹੁੰਦੀ ਹੈ ਜੋ ਲੋਕ "Quick reference" ਵਾਂਗ ਸੌਂਝਦੇ ਹਨ। ਇਹ ਇਕ ਵਾਰੀ ਅਪਡੇਟ ਹੋ ਜਾਂਦੇ ਹਨ, ਫਿਰ ਕੋਡ ਅੱਗੇ ਵੱਧਦਾ ਰਹਿੰਦਾ ਹੈ। ਇਨ੍ਹਾਂ ਤਿੰਨ ਤੋਂ ਸ਼ੁਰੂ ਕਰੋ ਕਿਉਂਕਿ ਇਹਨਾਂ ਵਿੱਚ ਠੋਸ ਦਾਅਵੇ ਹੁੰਦੇ ਹਨ ਜੋ ਤੁਸੀਂ ਚੈੱਕ ਕਰ ਸਕਦੇ ਹੋ।

README: ਉਹ ਪਹਿਲੀ ਜਗ੍ਹਾ ਜਿੱਥੇ ਯੂਜ਼ਰ ਦਰਦ ਮਹਿਸੂਸ ਕਰਦੇ ਹਨ

READMEs ਉਦਾਹਰਣ ਦੌਰਾਨ ਬਦਲਣ ਵਾਲੀਆਂ ਕਮਾਂਡਾਂ ਦੇ ਨਾਲ ਡਰਿਫਟ ਕਰਦੇ ਹਨ। ਇੱਕ ਨਵਾਂ flag ਐਡ ਹੋ ਜਾਂਦਾ ਹੈ, ਇੱਕ ਪੁਰਾਣਾ ਹਟਿਆ ਜਾਂਦਾ ਹੈ, ਜਾਂ ਕੋਈ environment variable renaм ਹੋ ਜਾਂਦਾ ਹੈ, ਪਰ setup ਸੈਕਸ਼ਨ ਹਾਲੇ ਵੀ ਪੁਰਾਣੇ ਹਾਲਤ ਨੂੰ ਦਿਖਾਂਦਾ ਹੈ। ਨਵੇਂ ਸਾਥੀ README ਤੋਂ ਕਾਪੀ-ਪੇਸਟ ਕਰਦੇ ਹਨ, errors ਆਉਂਦੇ ਹਨ, ਅਤੇ ਸਮਝਦੇ ਹਨ ਕਿ ਪ੍ਰੋਜੈਕਟ ਬਿਗੜਿਆ ਹੋਇਆ ਹੈ।

ਸਭ ਤੋਂ ਬੁਰੀ ਸਥਿਤੀ "ਲਗਭਗ ਸਹੀ" ਹੈ। ਇੱਕ ਘੱਟ-ਰਹਿਆ environment variable ਇੱਕ ਪੂਰੀ ਤਰ੍ਹਾਂ outdated README ਨਾਲੋਂ ਜ਼ਿਆਦਾ ਸਮਾਂ ਬਰਬਾਦ ਕਰ ਸਕਦਾ ਹੈ, ਕਿਉਂਕਿ ਲੋਕ ਛੋਟੇ ਛੋਟੇ variations ਨੂੰ ਦੁਹਰਾ ਕੇ ਹੱਲ ਲੱਭਦੇ ਰਹਿੰਦੇ ਹਨ ਅਤੇ ਡਾਕ ਨੂੰ ਚੈਲੰਜ ਨਹੀਂ ਕਰਦੇ।

API docs: mismatch ਕੀਤੇ ਗਏ ਆਕਾਰ ਅਤੇ ਗੁਮਰਾਹ ਕਰਨ ਵਾਲੇ ਉਦਾਹਰਣ

API docs ਉਨ੍ਹਾਂ ਸਥਿਤੀਆਂ ਵਿੱਚ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ request ਜਾਂ response ਫੀਲਡ ਬਦਲ ਜਾਂਦੇ ਹਨ। ਛੋਟੀ-ਛੋਟੀ ਤਬਦੀਲੀਆਂ (ਨਵੇਂ ਨਾਂ, defaults ਵਿੱਚ ਫਰਕ, ਨਵੀਂ ਲੋੜੀਂਦੀ headers) ਵੀ clients ਨੂੰ ਤੋੜ ਸਕਦੀਆਂ ਹਨ। ਅਕਸਰ endpoint ਸੂਚੀ ਸਹੀ ਹੁੰਦੀ ਹੈ ਪਰ ਉਦਾਹਰਣ ਗਲਤ ਹੁੰਦੇ ਹਨ, ਜੋ ਯੂਜ਼ਰ ਕਾਪੀ ਕਰਦੇ ਹਨ।

ਆਮ ਸਿਗਨਲ:

• Example payloads ਵਿੱਚ ਉਹ ਫੀਲਡ ਹਨ ਜੋ ਸਰਵਰ ਹੁਣ ਨਹੀਂ ਮੰਨਦਾ।
• Response samples ਪੁਰਾਣੇ error ਫਾਰਮੈਟ ਜਾਂ status codes ਦਿਖਾਉਂਦੇ ਹਨ।
• Parameter tables ਉਹ ਫੀਲਡ Optional ਦਿਖਾਉਂਦੇ ਹਨ ਜੋ ਹੁਣ Required ਹਨ।
• Auth ਨੋਟਸ ਉਹ headers ਜਾਂ scopes ਦੱਸਦੇ ਹਨ ਜੋ ਹੁਣ ਕੰਮ ਨਹੀਂ ਕਰਦੇ।
• Pagination, sorting, ਜਾਂ filtering ਨਿਯਮ ਹਕੀਕਤ ਨਾਲ ਮੇਲ ਨਹੀਂ ਖਾਂਦੇ।

Runbooks: ਚੁੱਪਚਾਪ ਡਰਿਫਟ ਜੋ ਸ਼ੋਰ ਵਾਲੇ incidents ਪੈਦਾ ਕਰਦਾ ਹੈ

Runbooks ਉਦਾਹਰਣ ਦੇ ਰੂਪ ਵਿੱਚ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ deployment, rollback, ਜਾਂ operational ਕਦਮ ਬਦਲ ਜਾਂਦੇ ਹਨ। ਇੱਕ outdated ਕਮਾਂਡ, ਗਲਤ ਸਰਵਿਸ ਨਾਂ, ਜਾਂ ਘੱਟ-ਪੂਰਕ prerequisite ਇੱਕ routine fix ਨੂੰ downtime ਵਿੱਚ ਬਦਲ ਸਕਦਾ ਹੈ।

ਉਹ "ਸਹੀ ਪਰ ਅਧੂਰੇ" ਵੀ ਹੋ ਸਕਦੇ ਹਨ: ਕਦਮ ਅਜੇ ਵੀ ਕੰਮ ਕਰਦੇ ਹਨ, ਪਰ ਉਹ ਇੱਕ ਨਵੀਂ migration, cache clear, ਜਾਂ feature flag toggle ਨੂੰ ਛੱਡ ਦਿੰਦੇ ਹਨ। ਇਸ ਵੇਲੇ responders runbook ਨੂੰ ਬੇਹੱਦ ਸਹੀ ਤਰੀਕੇ ਨਾਲ ਫੋਲੋ ਕਰਦੇ ਹਨ ਅਤੇ ਫਿਰ ਵੀ ਹੈਰਾਨ ਰਹਿ ਜਾਂਦੇ ਹਨ।

Claude Code ਨੂੰ ਕਿਵੇਂ ਵਰਤਣਾ ਹੈ: diffs ਅਤੇ contradictions callouts

Claude Code documentation drift ਲਈ ਸਭ ਤੋਂ ਵਧੀਆ ਤਰ੍ਹਾਂ ਕੰਮ ਕਰਦਾ ਹੈ ਜਦ ਤੁਸੀਂ docs ਨੂੰ ਕੋਡ ਵਾਂਗTreat ਕਰੋ: ਇੱਕ ਛੋਟਾ, ਰਿਵਿਊਯੋਗ ਪੈਚ ਪ੍ਰਸਤਾਵ ਕਰੋ ਅਤੇ ਵਜਹ ਸਮਝਾਓ। "README ਅਪਡੇਟ ਕਰੋ" ਪੁੱਛਣ ਦੀ ਥਾਂ, ਇਸਨੂੰ ਖਾਸ ਫਾਇਲਾਂ ਦੇ ਖਿਲਾਫ਼ diff ਜਨਰੇਟ ਕਰਨ ਲਈ ਕਹੋ। ਰਿਵਿਊਅਰਜ਼ ਨੂੰ ਸਾਫ਼ before/after ਦਿੱਸਦਾ ਹੈ ਅਤੇ ਉਹ ਅਣਹੋਣੀ ਸੋਧਾਂ ਨੂੰ ਤੇਜ਼ੀ ਨਾਲ ਪਛਾਣ ਸਕਦੇ ਹਨ।

ਇੱਕ ਵਧੀਆ drift ਚੈਕ ਦੋ ਚੀਜ਼ਾਂ ਉਤਪਾਦ ਕਰਦਾ ਹੈ:

1. ਇੱਕ ਮਿਨੀਮਲ diff
2. ਇੱਕ contradiction ਰਿਪੋਰਟ ਜੋ ਸਿੱਧਾ ਅਤੇ ਵਿਸਥਾਰ ਨਾਲ ਕਹੇ: "Doc ਕਹਿੰਦਾ X, repo ਦਿਖਾਉਂਦਾ Y."

ਸਬੂਤ ਮੰਗੋ, ਰائے ਨਹੀਂ

ਜਦ ਤੁਸੀਂ ਪ੍ਰੋਮਪਟ ਦਿੰਦੇ ਹੋ, ਰੇਪੋ ਤੋਂ ਪ੍ਰਮਾਣ ਮੰਗੋ: ਫਾਇਲ ਪਾਥ ਅਤੇ ਉਹ ਵੇਰਵੇ ਜਿਵੇਂ ਰੂਟਸ, config ਮੁੱਲ, ਜਾਂ ਇੰਟੀਗਰੇਸ਼ਨ ਟੈਸਟ ਜੋ ਮੌਜੂਦਾ ਬਿਹੇਵਿਅਰ ਦਾ ਪ੍ਰਮਾਣ ਦਿੰਦੇ ਹੋਣ।

ਇੱਥੇ ਇੱਕ ਪ੍ਰੋਮਪਟ ਪੈਟਰਨ ਹੈ ਜੋ ਇਸਨੂੰ ਜ਼ਮੀਨੀ ਰੱਖਦਾ ਹੈ:

Check these docs for drift: README.md, docs/api.md, runbooks/deploy.md.
Compare them to the current repo.
Output:
1) Contradictions list (doc claim -> repo evidence with file path and line range)
2) Unified diffs for the smallest safe edits
Rules: do not rewrite sections that are still accurate.

ਜੇ Claude ਕਹਿੰਦਾ "the API uses /v2", ਤਾਂ ਉਹ ਰਾਊਟਰ, OpenAPI spec, ਜਾਂ ਇੱਕ ਇੰਟੀਗਰੇਸ਼ਨ ਟੈਸਟ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਕੇ ਉਸ ਦਾ ਸਬੂਤ ਦਿੱਤੇ। ਜੇ ਇਹ ਸਬੂਤ ਨਹੀਂ ਲੱਭ ਸਕਦਾ, ਤਾਂ ਉਸ ਨੂੰ ਇਹ ਕਹਿਣਾ ਚਾਹੀਦਾ ਹੈ।

ਸੋਧ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ.Scope ਕਰੋ

ਡਰਿਫਟ ਅਕਸਰ ਇੱਕ ਕੋਡ ਤਬਦੀਲੀ ਨਾਲ ਸ਼ੁਰੂ ਹੁੰਦਾ ਹੈ ਜੋ ਖਾਮੋਸ਼ੀ ਨਾਲ ਕਈ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ ਪ੍ਰਭਾਵਿਤ ਕਰਦੀ ਹੈ। ਪਹਿਲਾਂ Claude ਨੂੰ ਪ੍ਰਭਾਵ ਦਾ ਘੇਰਾ ਦੱਸੋ: ਕੀ ਬਦਲਿਆ, ਕਿੱਥੇ ਬਦਲਿਆ, ਕਿਹੜੇ docs ਟੁੱਟ ਸਕਦੇ ਹਨ, ਅਤੇ ਕਿਹੜੇ ਯੂਜ਼ਰ ਪ੍ਰਭਾਵਿਤ ਹੋਣਗੇ।

ਉਦਾਹਰਨ: ਤੁਸੀਂ ਇੱਕ environment variable ਦਾ ਨਾਂ API_KEY ਤੋਂ SERVICE_TOKEN ਕਰ ਦਿੱਤਾ। ਇੱਕ ਵਧੀਆ ਰਿਪੋਰਟ ਪੁਰਾਣੇ ਨਾਂ ਦੀ ਹਰ ਥਾਂ ਖੋਜੇਗੀ (README setup, API ਉਦਾਹਰਣ, runbook secrets ਸੈਕਸ਼ਨ), ਫਿਰ ਇੱਕ ਟ tight(diff) ਜਨਰੇਟ ਕਰੇਗੀ ਜੋ ਸਿਰਫ਼ ਉਹ ਲਾਈਨਾਂ ਅਪਡੇਟ ਕਰੇ ਜੋ ਹੁਣ ਫੇਲ ਹੋਣਗੀਆਂ।

ਪ੍ਰਾਰੰਭ ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਇੱਕ ਸਧਾਰਨ workflow ਸੈੱਟ ਕਰੋ

ਜੇ ਤੁਸੀਂ ਕਿਸੇ ਮਾਡਲ ਨੂੰ "ਸਾਰੇ docs" ਵੱਲ ਬਿਨਾਂ ਨਿਯਮਾਂ ਦੇ ਪਇੰਟ ਕਰੋਗੇ, ਤਾਂ ਅਕਸਰ ਤੁਹਾਨੂੰ ਦੁਬਾਰਾ ਲਿਖਿਆ prose ਮਿਲੇਗਾ ਜੋ ਅਜੇ ਵੀ ਗਲਤ ਤੱਥ ਰੱਖਦਾ ਹੈ। ਇੱਕ ਸਧਾਰਨ workflow ਸੋਧਾਂ ਨੂੰ ਛੋਟਾ, ਦੋਹਰਾਉਣਯੋਗ, ਅਤੇ ਰਿਵਿਊਯੋਗ ਰੱਖਦਾ ਹੈ।

ਇੱਕ doc ਸੈੱਟ ਨਾਲ ਸ਼ੁਰੂ ਕਰੋ: README, API ਰੈਫਰੈਂਸ, ਜਾਂ ਇੱਕ ਅਜਿਹਾ runbook ਜੋ ਲੋਕ ਅਸਲ ਵਿੱਚ ਵਰਤਦੇ ਹਨ। ਇੱਕ ਖੇਤਰ ਨੂੰ ਅਖੀਰ ਤਕ ਠੀਕ ਕਰਨਾ ਤੁਹਾਨੂੰ ਦੱਸੇਗਾ ਕਿ ਕਿਹੜੇ ਸਿਗਨਲ ਭਰੋਸੇਯੋਗ ਹਨ, ਉਸ ਤੋਂ ਬਾਅਦ ਵਧਾਓ।

ਫੈਸਲਾ ਕਰੋ ਕਿ ਕਿੜਾ ਸਾਰਥਕ ਤੱਥ ਦਾ ਸੋਰਸ ਹੋਵੇਗਾ

ਸਾਦਾ ਸ਼ਬਦਾਂ ਵਿੱਚ ਲਿਖੋ ਕਿ ਉਸ doc ਸੈੱਟ ਲਈ ਤੱਥ ਕਿੱਥੋਂ ਆਉਣਗੇ।

• README ਲਈ: CLI help output ਅਤੇ ਇੱਕ ਕੰਮ ਕਰਦਾ ਉਦਾਹਰਣ ਐਪ।
• API docs ਲਈ: router definitions ਅਤੇ integration tests।
• Runbooks ਲਈ: deployment config ਅਤੇ ਉਹ alerts ਜੋ ਪ੍ਰੋਸੀਜਰ ਨੂੰ trigger ਕਰਦੇ ਹਨ।

ਇਕ ਵਾਰੀ ਤੁਸੀਂ ਉਹ ਸਰੋਤ ਨਾਂਮ ਲਿਖ ਲਏ, ਪ੍ਰੌਮਪਟ ਹੋਰ ਨਿਗਰਾਨ ਹੋ ਜਾਂਦੇ ਹਨ: "README ਨੂੰ ਮੌਜੂਦਾ CLI output ਅਤੇ config defaults ਨਾਲ ਤੁਲਨਾ ਕਰੋ, ਫਿਰ ਇੱਕ patch ਜਨਰੇਟ ਕਰੋ।"

ਇੱਕ ਐਸਾ ਆਉਟਪੁੱਟ ਚੁਣੋ ਜੋ ਰਿਵਿਊਅਰ ਤੁਰੰਤ ਵੇਰੀਫਾਈ ਕਰ ਸਕੇ

ਪਹਿਲੇ ਚੈਕ ਕਰਨ ਤੋਂ ਪਹਿਲੇ ਆਉਟਪੁੱਟ ਫਾਰਮੈਟ 'ਤੇ ਸਹਿਮਤ ਹੋ ਜਾਓ। ਫਾਰਮੈਟ ਮਿਲਾਉਣ ਨਾਲ ਇਹ ਮੁਸ਼ਕਲ ਹੁੰਦਾ ਹੈ ਕਿ ਕੀ ਬਦਲਿਆ ਅਤੇ ਕਿਉਂ।

ਇੱਕ ਸਧਾਰਨ ਨਿਯਮ-ਸੈੱਟ:

• ਹਰ ਦਸਤਾਵੇਜ਼ ਸੋਧ ਲਈ ਇੱਕ diff ਮੰਗੋ, ਨਾਲ ਹੀ ਇੱਕ ਇੱਕ-ਵਾਕ ਦਾ ਕਾਰਨ।
• ਜਦੋਂ ਟੂਲ ਸੁਰੱਖਿਅਤ ਤੌਰ 'ਤੇ ਲਫ਼ਜ਼ ਨਹੀਂ ਬਦਲ ਸਕਦਾ, ਤਾਂ ਇੱਕ ਛੋਟੀ contradiction ਲਿਸਟ ਦੀ ਆਗਿਆ ਦਿਓ।
• ਜੇ ਲਈ ਸਕੇ ਤਾਂ diffs ਨੂੰ ਇੱਕ ਫਾਇਲ ਪ੍ਰਤੀ ਸੋਧ ਤੱਕ ਸੀਮਿਤ ਰੱਖੋ।
• ਫੇਲ ਹੋ ਰਹੇ ਉਦਾਹਰਣ (ਕਮਾਂਡ, ਰਿਕਵੇਸਟ, ਕੋਡ ਸ્નਿਪੈਟ) ਨੂੰ ਆਮ ਲਿਖਤ ਤੋਂ ਉੱਚੀ ਤਰਜੀਹ ਦਿਓ।

ਇਕ ਪ੍ਰਯੋਗਿਕ ਆਦਤ: ਹਰ doc PR ਵਿੱਚ ਇੱਕ ਛੋਟਾ ਨੋਟ ਜੋੜੋ: "Source of truth checked: routes + tests" ਤਾਂ ਕਿ ਰਿਵਿਊਅਰ ਜਾਣ ਸਕਣ ਕਿ ਕੀ ਤੁਲਨਾ ਕੀਤੀ ਗਈ। ਇਹ doc ਅਪਡੇਟਾਂ ਨੂੰ "ਲੱਗਦਾ ਠੀਕ ਹੈ" ਤੋਂ "ਕਿਸੇ ਨਿਸ਼ਚਿਤ ਚੀਜ਼ ਦੇ ਮੁਕਾਬਲੇ ਵੇਰੀਫਾਈਡ" ਵਿੱਚ ਬਦਲ ਦਿੰਦਾ ਹੈ।

ਕਦਮ-ਬਾਈ-ਕਦਮ: ਹਰ ਬਦਲਾਅ 'ਤੇ docs ਨੂੰ ਕੋਡ ਨਾਲ ਸੰਰੇਖਿਤ ਰੱਖੋ

ਹਰ ਕੋਡ ਤਬਦੀਲੀ ਨੂੰ ਇੱਕ ਛੋਟੀ docs ਜਾਂਚ ਸਮਝੋ। ਮਕਸਦ ਇਹ ਹੈ ਕਿ ਵਿਵਾਦਾਂ ਨੂੰ ਜਲਦੀ ਪਕੜਿਆ ਜਾਵੇ ਅਤੇ ਇੱਕ ਛੋਟਾ ਪੈਚ ਤਿਆਰ ਕੀਤਾ ਜਾਵੇ ਜੋ ਰਿਵਿਊਅਰ ਭਰੋਸਾ ਕਰ ਸਕਦੇ ਹਨ।

ਪਹਿਲਾਂ, ਉਹ ਨਿਰਧਾਰਤ ਫਾਇਲਾਂ ਚੁਣੋ ਜਿਨ੍ਹਾਂ ਦੀ ਤੁਸੀਂ ਜਾਂਚ ਕਰਨਾ ਚਾਹੁੰਦੇ ਹੋ ਅਤੇ ਇੱਕ ਸਪਸ਼ਟ drift ਸਵਾਲ। ਉਦਾਹਰਨ: "ਕੀ ਅਸੀ ਕਿਸੇ environment variable, CLI flag, HTTP route, ਜਾਂ error code ਨੂੰ ਬਦਲਿਆ ਹੈ ਜੋ ਦਸਤਾਵੇਜ਼ ਅਜੇ ਵੀ ਉੱਲੇਖ ਕਰ ਰਹੇ ਹਨ?" ਵਿਸ਼ੇਸ਼ ਬਣਨਾ ਮਾਡਲ ਨੂੰ ਪੂਰੇ ਸੈਕਸ਼ਨ ਰੀ-ਰਾਈਟ ਕਰਨ ਤੋਂ ਰੋਕਦਾ ਹੈ।

ਅਗਲੇ ਕਦਮ ਵਿੱਚ, Claude Code ਨੂੰ ਪਹਿਲਾਂ ਕੋਡ ਤੋਂ ਕਠੋਰ ਤੱਥ ਨਿਕਾਲਣ ਲਈ ਕਹੋ। ਇਸਨੂੰ ਸਿਰਫ਼ ਕংਕਰੀਟ ਆਈਟਮ ਲਿਸਟ ਕਰਨ ਲਈ ਕਹੋ: ਯੂਜ਼ਰ ਜੋ ਕਮਾਂਡ ਚਲਾਉਂਦੇ ਹਨ, endpoints ਅਤੇ methods, request ਅਤੇ response ਫੀਲਡ, config keys, ਲੋੜੀਂਦੇ environment variables, ਅਤੇ ਸਕ੍ਰਿਪਟ ਜਾਂ configs ਦੁਆਰਾ ਹਵਾਲੇ ਕੀਤੇ operational steps। ਜੇ ਕੁਝ ਕੋਡ ਵਿੱਚ ਨਹੀਂ ਮਿਲਦਾ, ਤਾਂ ਉਹ "not found" ਕਹੇ ਨਾ ਕਿ ਅਨੁਮਾਨ ਲਗਾਏ।

ਫਿਰ ਇੱਕ ਸਧਾਰਨ ਤੁਲਨਾਤਮਕ ਸਾਰਣੀ ਮੰਗੋ: doc claim, ਜੋ ਕੋਡ ਦਿਖਾਉਂਦਾ ਹੈ, ਅਤੇ ਇੱਕ ਸਥਿਤੀ (match, mismatch, missing, unclear)। ਇਹ ਗੱਲਬਾਤ ਨੂੰ ਜ਼ਮੀਨੀ ਰੱਖਦੀ ਹੈ।

ਉਸ ਤੋਂ ਬਾਅਦ, ਇੱਕ unified diff ਮੰਗੋ ਜੋ ਨਿੱਕੀਆਂ ਸੋਧਾਂ ਕਰੇ। ਦੱਸੋ ਕਿ ਸਿਰਫ਼ ਉਹ ਲਾਈਨਾਂ ਬਦਲੋ ਜੋ mismatch ਨੂੰ ਸਲਾਹਦੇ ਹਨ, doc ਦੀ ਮੌਜੂਦਾ ਸ਼ੈਲੀ ਰੱਖੋ, ਅਤੇ ਉਹ ਵਾਅਦੇ ਨਾ ਜੋੜੋ ਜੋ ਕੋਡ ਦੁਆਰਾ ਸਬੂਤਿਤ ਨਹੀਂ ਹਨ।

ਅੰਤ ਵਿੱਚ, ਇੱਕ ਛੋਟਾ ਰਿਊਵੀਅਰ ਸੰਖੇਪ ਦਿਓ: ਕੀ ਬਦਲਿਆ, ਕਿਉਂ ਬਦਲਿਆ, ਅਤੇ ਕਿਹੜੀਆਂ ਚੀਜ਼ਾਂ ਨੂੰ ਦੁਬਾਰਾ ਚੈੱਕ ਕਰਨਾ ਹੈ (ਜਿਵੇਂ renamed env var ਜਾਂ ਨਵਾਂ ਲੋੜੀਂਦਾ header)।

API docs: ਐਂਡਪਾਇੰਟ ਅਤੇ ਉਦਾਹਰਣਾਂ ਦੀ ਵੇਰੀਫਿਕੇਸ਼ਨ ਦਾ ਪ੍ਰਯੋਗਿਕ ਤਰੀਕਾ

API docs ਉਦਾਹਰਣ ਦੇ ਤੌਰ 'ਤੇ ਡਰਿਫਟ ਹੁੰਦੇ ਹਨ ਜਦੋਂ ਕੋਡ ਖਾਮੋਸ਼ੀ ਨਾਲ ਬਦਲਦਾ ਹੈ: ਇੱਕ route rename ਹੋ ਜਾਂਦਾ ਹੈ, ਇੱਕ ਫੀਲਡ required ਹੋ ਜਾਂਦੀ ਹੈ, ਜਾਂ error shape ਬਦਲ ਜਾਂਦੀ ਹੈ। ਨਤੀਜਾ ਤੋੜ-ਜੋੜ ਕਲਾਇੰਟ ਇੰਟੀਗਰੇਸ਼ਨ ਅਤੇ ਬੇਕਾਰ ਡਿਬੱਗਿੰਗ ਸਮਾਂ ਹੈ।

Claude Code documentation drift ਲਈ ਕੰਮ ਕਰਦਾ ਹੈ ਤਾਂ ਜੋ ਰੇਪੋ ਤੋਂ ਇਹ ਸਾਬਤ ਕੀਤਾ ਜਾਵੇ ਕਿ API ਕੀ ਕਰਦੀ ਹੈ, ਫਿਰ docs ਵਿੱਚ mismatch ਵਾਲੀਆਂ ਥਾਂਵਾਂ ਨੂੰ ਨੁਕਸਾਨ ਦਿਖਾਓ। ਇਸਨੂੰ routing ਅਤੇ handlers ਤੋਂ ਇਕ ਇਨਵੈਂਟਰੀ ਨਿਕਾਲਣ ਲਈ ਕਹੋ (paths, methods, request ਅਤੇ response ਮਾਡਲ) ਅਤੇ ਉਸਨੂੰ API reference ਨਾਲ ਤੁਲਨਾ ਕਰਵਾਓ।

ਉਸ 'ਤੇ ਧਿਆਨ ਦਿਓ ਜੋ ਲੋਕ ਅਸਲ ਵਿੱਚ ਕਾਪੀ-ਪੇਸਟ ਕਰਦੇ ਹਨ: curl commands, headers, sample payloads, status codes, ਅਤੇ field names। ਇਕ ਹੀ ਪ੍ਰੋਮਪਟ ਵਿੱਚ ਇਹ ਚੈੱਕ ਕਰਵਾਓ:

• Auth ਦੀਆਂ ਲੋੜਾਂ (headers, token type, public endpoints)
• Pagination params ਅਤੇ defaults
• Error status codes ਅਤੇ JSON ਫਾਰਮੈਟ
• Versioning ਵਿਵਹਾਰ (v1 vs v2)
• ਕੀ ਉਦਾਹਰਣ ਮੌਜੂਦਾ validation ਨਿਯਮਾਂ ਨਾਲ ਮਿਲਦੀਆਂ ਹਨ

ਜਦੋਂ ਇਹ mismatch ਲੱਭਦਾ ਹੈ, ਤਾਂ ਕੇਵਲ ਉਹਨਾਂ diffs ਨੂੰ ਸਵੀਕਾਰ ਕਰੋ ਜਿੱਥੇ ਇਹ ਕੋਡ ਤੋਂ ਸਬੂਤ ਦਿਖਾ ਸਕੇ (ਸਹੀ route definition, handler davranış, ਜਾਂ schema)। ਇਹ patches ਛੋਟੇ ਅਤੇ ਰਿਵਿਊਯੋਗ ਰਹਿੰਦੇ ਹਨ।

ਉਦਾਹਰਨ: ਹੁਣ ਕੋਡ POST /widgets 'ਤੇ 201 ਰਿਟਰਨ ਕਰਦਾ ਹੈ ਅਤੇ name ਫੀਲਡ required ਕਰ ਦਿੱਤੀ ਗਈ ਹੈ। docs ਹਾਲੇ ਵੀ 200 ਦੱਸ ਰਹੇ ਹਨ ਅਤੇ name ਨੂੰ ਛੱਡ ਰਹੇ ਹਨ। ਇੱਕ ਵਧੀਆ ਆਉਟਪੁੱਟ ਦੋਵਾਂ contradictions ਨੂੰ ਕਹੇਗਾ ਅਤੇ ਸਿਰਫ਼ ਉਸ ਐਂਡਪਾਇੰਟ ਦੀ status code ਅਤੇ example JSON ਅੱਪਡੇਟ ਕਰੇਗਾ, ਬਾਕੀ ਛੱਡ ਦੇਵੇਗਾ।

Runbooks: stale procedures ਕਰਕੇ ਆਉਟੇਜ਼ ਘਟਾਓ

Runbooks ਸਭ ਤੋਂ ਮਹਿੰਗੇ ਤਰੀਕੇ ਨਾਲ fail ਕਰਦੇ ਹਨ: ਉਹ ਪੂਰੇ ਦਿਖਦੇ ਹਨ, ਪਰ ਕਦਮ ਹੁਣ ਪ੍ਰਣਾਲੀ ਦੀ ਹਕੀਕਤ ਨਾਲ ਮੇਲ ਨਹੀਂ ਖਾਂਦੇ। ਇੱਕ ਛੋਟੀ ਤਬਦੀਲੀ ਜਿਵੇਂ ਇਹਨਾਂ variables ਦਾ ਨਾਂ ਬਦਲਣਾ ਜਾਂ deploy ਕਮਾਂਡ ਬਦਲਣਾ incident ਨੂੰ ਲੰਬਾ ਕਰ ਸਕਦਾ ਹੈ ਕਿਉਂਕਿ responders ਉਹਨਾਂ ਨਿਰਦੇਸ਼ਾਂ 'ਤੇ ਚੱਲਦੇ ਹਨ ਜੋ ਹੁਣ ਕੰਮ ਨਹੀਂ ਕਰਦੇ।

Runbook ਨੂੰ ਕੋਡ ਵਾਂਗTreat ਕਰੋ: ਮੌਜੂਦਾ ਰੇਪੋ ਦੇ ਖਿਲਾਫ diff ਮੰਗੋ ਅਤੇ contradiction callouts ਲੋੜੀਂਦੇ ਕਰੋ। ਇਸਨੂੰ ਉਹ ਚੀਜ਼ਾਂ ਨਾਲ ਤੁਲਨਾ ਕਰੋ ਜੋ ਸਿਸਟਮ ਅਸਲ ਵਿੱਚ ਵਰਤਦਾ ਹੈ: scripts, config defaults, ਅਤੇ ਤੁਹਾਡੀ ਮੌਜੂਦਾ ਟੂਲਿੰਗ।

ਉਹ failure points 'ਤੇ ਧਿਆਨ ਦਿਓ ਜੋ incidents ਦੌਰਾਨ ਸਭ ਤੋਂ ਜ਼ਿਆਦਾ ਥਰੈਸ਼ ਪੈਦਾ ਕਰਦੇ ਹਨ:

• ਕੀ ਲਿਖਿਆ ਕਮਾਂਡ ਮੌਜੂਦਾ ਸਕ੍ਰਿਪਟ ਅਤੇ ਫਲੈਗ ਨਾਲ ਮਿਲਦਾ ਹੈ?
• ਕੀ "default" config values ਉਸ ਨਾਲ ਮਿਲਦੇ ਹਨ ਜੋ ਐਪ ਹੁਣ ship ਕਰਦਾ ਹੈ?
• ਕੀ ਲੋੜੀਂਦੇ env vars ਅਤੇ secrets ਕੋਡ ਅਤੇ deploy config ਵਿੱਚ refer ਕੀਤੇ ਗਏ ਹਨ?
• ਕੀ deploy ਅਤੇ rollback steps ਤੁਹਾਡੇ ਮੌਜੂਦਾ release tooling ਅਤੇ naming ਨਾਲ ਮੇਲ ਖਾਂਦੇ ਹਨ?
• ਕੀ "known good" ਮੁੱਲ (ports, regions, timeouts) ਅਜੇ ਵੀ ਹਕੀਕਤ ਨਾਲ ਮਿਲਦੇ ਹਨ?

ਕੁਝ quick prechecks ਅਤੇ expected outputs ਵੀ ਜੋੜੋ ਤਾਂ ਕਿ responders ਦੱਸ ਸਕਣ ਕਿ ਉਹ ਸਹੀ ਰਸਤੇ 'ਤੇ ਹਨ। "Verify it works" ਕਾਫ਼ੀ ਨਹੀਂ; ਉਹ ਸਪੱਸ਼ਟ signal ਹੋਣਾ ਚਾਹੀਦਾ ਹੈ (ਇੱਕ status line, version string, ਜਾਂ health check response)।

ਜੇ ਤੁਸੀਂ Koder.ai ਜਿਹੇ ਪਲੇਟਫਾਰਮਾਂ 'ਤੇ ਐਪ ਬਣਾਉਂਦੇ ਅਤੇ deploy ਕਰਦੇ ਹੋ, ਤਾਂ ਇਹ ਹੋਰ ਵੀ ਜ਼ਰੂਰੀ ਹੋ ਜਾਂਦਾ ਹੈ ਕਿਉਂਕਿ snapshots ਅਤੇ rollback ਉਸ ਵੇਲੇ ਹੀ ਉਪਯੋਗੀ ਹੁੰਦੇ ਹਨ ਜਦੋਂ runbook ਸਹੀ ਕਾਰਵਾਈ ਦਾ ਨਾਂ ਦੱਸਦਾ ਹੈ ਅਤੇ ਮੌਜੂਦਾ recovery path ਨੂੰ ਦਰਸਾਉਂਦਾ ਹੈ।

ਅਕਸਰ ਹੋਣ ਵਾਲੀਆਂ ਗਲਤੀਆਂ ਜੋ ਡਰਿਫਟ ਨੂੰ ਬੁਹਾਵਾ ਦਿੰਦੀਆਂ ਹਨ

ਡਰਿਫਟ ਬਣਾਉਣ ਦਾ ਸਭ ਤੋਂ ਤੇਜ਼ ਤਰੀਕਾ ਦਸਤਾਵੇਜ਼ਾਂ ਨੂੰ "ਚੰਗੀ ਲਿਖਤ" ਵਾਂਗ ਸਮਝਣਾ ਹੈ ਨਾ ਕਿ ਉਹਨਾਂ ਦਾਅਵਿਆਂ ਦੇ ਸੈੱਟ ਜੋ ਕੋਡ ਨਾਲ ਮਿਲਦੇ ਹੋਣ।

ਉਹ ਗਲਤੀਆਂ ਜੋ ਆਹਿਸਤਾ-ਆਹਿਸਤਾ ਅਲਾਇਨਮੈਂਟ ਨੁਕਸਾਨ ਪਹੁੰਚਾਉਂਦੀਆਂ ਹਨ

ਇੱਕ ਆਮ ਗਲਤੀ ਪਹਿਲਾਂ rewrite ਮੰਗਣਾ ਹੈ। ਜਦੋਂ ਤੁਸੀਂ contradiction ਚੈੱਕ ਛੱਡ ਦਿੰਦੇ ਹੋ, ਤਾਂ ਤੁਹਾਨੂੰ चिकਨ-ਚੌਪ prose ਮਿਲ ਸਕਦੀ ਹੈ ਜੋ ਹਾਲੇ ਵੀ ਗਲਤ ਵਿਹੇਵਿਅਰ ਦਰਸਾਉਂਦੀ ਹੈ। ਹਮੇਸ਼ਾ ਪਹਿਲਾਂ ਪੁੱਛੋ ਕਿ ਦਸਤਾਵੇਜ਼ ਕੀ ਦਾਅਵਾ ਕਰਦਾ ਹੈ, ਕੋਡ ਕੀ ਕਰਦਾ ਹੈ, ਅਤੇ ਕਿੱਥੇ ਉਹ ਅਣ-ਮਿਲਦੇ ਹਨ।

ਹੋਰ ਗਲਤੀ ਮਾਡਲ ਨੂੰ ਅਨੁਮਾਨ ਲਗਾਉਣ ਦਿੰਨਾ ਹੈ। ਜੇ ਬਿਹੇਵਿਅਰ ਕੋਡ, tests, ਜਾਂ configs ਵਿੱਚ ਦਿਖਾਈ ਨਹੀਂ ਦਿੰਦਾ, ਤਾਂ ਉਸਨੂੰ uncertain ਮੰਨਾਂ। "Probably" README ਵਿੱਚ ਵਾਅਦੇ ਬਣਾਉਂਦਾ ਹੈ ਅਤੇ runbooks ਕਹਾਣੀਵੀਂ ਹੋ ਸਕਦੇ ਹਨ।

ਇਹ ਸਮੱਸਿਆਵਾਂ ਰੋਜ਼ਾਨਾ ਅਪਡੇਟਾਂ ਵਿੱਚ ਕਾਫ਼ੀ ਆਉਂਦੀਆਂ ਹਨ:

• ਇਕ ਸੈਕਸ਼ਨ ਅਪਡੇਟ ਕਰਨਾ ਪਰ examples, error messages, ਅਤੇ edge cases ਨੂੰ ਛੱਡ ਦੇਣਾ
• ਇੱਕ ਧਾਰਨਾ ਦਾ ਨਾਂ ਇਕ ਥਾਂ (README) ਵਿੱਚ ਬਦਲਣਾ ਪਰ API docs, config keys, ਜਾਂ runbooks ਵਿੱਚ ਨਹੀਂ ਬਦਲਣਾ
• endpoint ਵਰਣਨਾਂ ਫਿਕਸ ਕਰਨਾ ਪਰ request ਅਤੇ response samples ਭੁੱਲ ਜਾਣਾ
• ਵਿਹੇਵਿਅਰ ਬਦਲਣਾ ਪਰ defaults ਜਾਂ limitations notes ਨੂੰ ਅਪਡੇਟ ਨਾ ਕਰਨਾ
• doc edits ਨੂੰ merge ਕਰਨਾ ਬਿਨਾਂ ਇੱਕ ਛੋਟੀ "ਕਿਉਂ ਇਹ ਬਦਲਿਆ" ਨੋਟ ਦੇ

ਇੱਕ ਛੋਟਾ ਉਦਾਹਰਨ

ਇੱਕ handler expired tokens ਲਈ 401 ਦੀ ਥਾਂ 403 ਰਿਟਰਨ ਕਰਦਾ ਹੈ, ਅਤੇ header ਨਾਮ X-Token ਤੋਂ Authorization ਹੋ ਜਾਂਦਾ ਹੈ। ਜੇ ਤੁਸੀਂ ਸਿਰਫ਼ auth सेकਸ਼ਨ ਰੀ-ਰਾਈਟ ਕਰੋਗੇ, ਤਾਂ ਤੁਸੀਂ ਮਿਸ ਕਰ ਸਕਦੇ ਹੋ ਕਿ API doc example ਹਾਲੇ ਵੀ ਪੁਰਾਣਾ header ਦਿਖਾ ਰਿਹਾ ਹੈ, ਅਤੇ runbook ਹਾਲੇ ਵੀ on-call ਨੂੰ 401 spikes ਦੇਖਣ ਨੂੰ ਕਹਿ ਰਹੀ ਹੈ।

ਜਦੋਂ ਤੁਸੀਂ diffs ਬਣਾਉਂਦੇ ਹੋ, ਇੱਕ ਛੋਟਾ ਫੈਸਲਾ-ਲਾਈਨ ਜੋੜੋ ਜਿਵੇਂ: "Auth failures ਹੁਣ 403 ਰਿਟਰਨ ਕਰਦੇ ਹਨ ਤਾਂ ਜੋ invalid ਅਤੇ missing credentials ਨੂੰ ਫਰਕ ਕੀਤਾ ਜਾਵੇ." ਇਹ ਅਗਲੇ ਵਿਅਕਤੀ ਨੂੰ ਰੋਕਦਾ ਹੈ ਕਿ ਉਹ docs ਨੂੰ ਪੁਰਾਣੇ ਵਿਹੇਵਿਅਰ ਵੱਲ ਮੁੜ-ਵਾਪਸ ਕਰ ਦੇਵੇ।

Merge ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ ਇੱਕ ਤੇਜ਼ ਚੈੱਕਲਿਸਟ

ਹਰ doc ਅਪਡੇਟ ਨੂੰ ਇੱਕ ਛੋਟੀ ਆਡਿਟ ਵਾਂਗ ਸਮਝੋ। ਮਕਸਦ ਅਗਲੀ ਵਾਰੀ ਜਦੋਂ ਕੋਈ ਨਿਰਦੇਸ਼ ਫੋਲੋ ਕਰੇ ਤਾਂ ਘੱਟ ਹੈਰਾਨੀਆਂ ਹੋਣ।

ਪੰਜ ਜਾਂਚਾਂ ਜੋ ਬਹੁਤ ਸਾਰਾ ਡਰਿਫਟ ਫੜ ਲੈਂਦੀਆਂ ਹਨ

Merge ਕਰਨ ਤੋਂ ਪਹਿਲਾਂ README, API docs, ਅਤੇ runbook ਵਿੱਚ ਹਰ ਇਕ concrete claim ਜਿਹੜਾ ਕਮਾਂਡ, endpoint, config key, env var, port, ਜਾਂ example payload ਦੱਸਦਾ ਹੈ, ਨੂੰ ਹਾਈਲਾਈਟ ਕਰੋ।

• ਹਰ claim ਲਈ ਉਹ ਇੱਕ ਸਹੀ ਫਾਇਲ ਨੋਟ ਕਰੋ ਜੋ ਇਸ ਨੂੰ ਸਾਬਤ ਕਰਦੀ ਹੈ (source, config, schema, migration, test, ਜਾਂ CLI help output)। ਜੇ ਸਬੂਤ ਤੇਜ਼ੀ ਨਾਲ ਨਹੀਂ ਮਿਲਦਾ, ਤਾਂ guessing ਕਰਨ ਦੀ ਥਾਂ unknown ਮਾਰਕ ਕਰੋ।
• ਜਿੱਥੇ ਸਬੂਤ ਮੌਜੂਦ ਹੈ, ਕੇਵਲ ਉੱਥੇ ਇੱਕ minimal diff ਮੰਗੋ। ਜੇ claim unknown ਹੈ, ਤਾਂ ਸੋਧ ਇਕ سوال ਜਾਂ TODO ਬਣ ਜਾਣੀ ਚਾਹੀਦੀ ਹੈ, ਨਾ ਕਿ ਨਿਸ਼ਚਿਤ ਬਿਆਨ।
• Examples ਲਈ sanity-check: ਕੀ inputs ਅਜੇ ਵੀ ਕੋਡ ਦੁਆਰਾ ਮੰਨੀਆਂ ਜਾਂਦੀਆਂ ਹਨ (parameter names, required fields, headers, default values)? ਲੰਬੇ ਉਦਾਹਰਣ ਡਰਿਫਟ ਦੇ ਮੈਗਨੈਟ ਹੁੰਦੇ ਹਨ।
• Runbooks ਲਈ, ਪੱਕਾ ਕਰੋ कि steps likely failures, safe rollback, ਅਤੇ recovery verify ਕਰਨ ਦੇ ਤਰੀਕੇ ਨੂੰ cover ਕਰਦੇ ਹਨ।

ਇੱਕ ਛੋਟਾ stop rule

ਜੇ ਤੁਸੀਂ ਇੱਕੋ ਦਸਤਾਵੇਜ਼ ਵਿੱਚ ਦੋ ਜਾਂ ਵੱਧ unknown claims ਲੱਭਦੇ ਹੋ, ਤਾਂ merge ਰੋਕੋ। ਜਾਂ ਤਾਂ ਸਬੂਤ (file paths ਅਤੇ function names) ਜੋੜੋ, ਜਾਂ doc ਨੂੰ ਉਸੇ ਹਿੱਸੇ ਤੱਕ ਘਟਾ ਦਿਓ ਜੋ ਨਿਸ਼ਚਿਤ ਹੈ।

ਉਦਾਹਰਨ ਸਥਿਤੀ: ਇੱਕ ਫੀਚਰ ਬਦਲ, ਤਿੰਨ docs ਡਰਿਫਟ

ਇੱਕ ਛੋਟੀ ਟੀਮ auth ਅਪਡੇਟ ਕਰਦੀ ਹੈ: API key ਦੀ ਥਾਂ clients ਹੁਣ Authorization: Bearer <token> ਭੇਜਦੇ ਹਨ। ਕੋਡ ship ਹੁੰਦਾ ਹੈ, tests ਪਾਸ ਹੁੰਦੇ ਹਨ, ਅਤੇ ਟੀਮ ਅੱਗੇ ਵੱਧ ਜਾਂਦੀ ਹੈ।

ਦੋ ਦਿਨ ਬਾਅਦ, ਨਵਾਂ ਡਿਵੈਲਪਰ README ਫੋਲੋ ਕਰਦਾ ਹੈ। README ਹਾਲੇ ਵੀ ਕਹਿੰਦਾ ਹੈ "set X-API-Key in your environment" ਅਤੇ curl ਉਦਾਹਰਣ ਪੁਰਾਣਾ header ਦਿਖਾਂਦੀ ਹੈ। ਉਹ ਲੋਕਲ ਰਨ ਨਹੀਂ ਚਲਾ ਪਾਂਦਾ ਅਤੇ ਸੋਚਦਾ ਹੈ ਕਿ ਸੇਵਾ ਡਾਊਨ ਹੈ।

ਇਸ ਦਰਮਿਆਨ, API docs ਵੀ stale ਹਨ। ਉਹ ਪੁਰਾਣਾ header ਵਰਣਨ ਕਰਦੇ ਹਨ ਅਤੇ ਹਾਲੇ ਵੀ ਇੱਕ response field user_id ਦਿਖਾਉਂਦੇ ਹਨ, ਜਦਕਿ API ਹੁਣ userId ਰਿਟਰਨ ਕਰਦੀ ਹੈ। ਲਿਖਤ ਵਿਚ ਕੋਈ ਗਲਤੀ ਨਹੀਂ, ਪਰ ਇਹ ਕੋਡ ਨਾਲ ਟਕਰਾਉਂਦੀ ਹੈ, ਇਸ ਲਈ ਪੜ੍ਹਨ ਵਾਲੇ ਗਲਤ ਚੀਜ਼ਾਂ ਕਾਪੀ ਕਰ ਲੈਂਦੇ ਹਨ।

ਫਿਰ ਇੱਕ incident ਹੁੰਦਾ ਹੈ। On-call runbook ਦੀ ਕਦਮ "rotate the API key and restart workers" ਫੋਲੋ ਕਰਦਾ ਹੈ। ਇਹ ਮਦਦ ਨਹੀਂ ਕਰਦਾ ਕਿਉਂਕਿ ਅਸਲ ਸਮੱਸਿਆ token verification ਨਾਲ ਸੰਬੰਧਿਤ ਹੈ। runbook 20 ਮਿੰਟ ਲਈ ਉਨ੍ਹਾਂ ਨੂੰ ਗਲਤ ਰਸਤੇ ਭੇਜਦਾ ਹੈ।

ਇਥੇ Claude Code documentation drift ਦੀ ਵਰਤੋਂ ਮਦਦਗਾਰ ਹੁੰਦੀ ਹੈ ਜਦੋਂ ਇਹ diffs ਅਤੇ contradiction callouts ਤਿਆਰ ਕਰਦਾ ਹੈ, ਨਾ ਕਿ ਪੂਰੀ ਰੀ-ਰਾਈਟ। ਤੁਸੀਂ ਇਸਨੂੰ ਕਹਿ ਸਕਦੇ ਹੋ ਕਿ auth middleware ਅਤੇ route handlers ਨੂੰ README snippets, API examples, ਅਤੇ runbook steps ਨਾਲ ਤੁਲਨਾ ਕਰ ਕੇ ਘੱਟੋ-ਘੱਟ ਪੈਚ ਪ੍ਰਸਤਾਵ ਕਰੋ:

- Header: X-API-Key: <key>
+ Header: Authorization: Bearer <token>

- { "user_id": "..." }
+ { "userId": "..." }

ਅਹਮ ਗੱਲ ਇਹ ਹੈ ਕਿ ਇਹ mismatches ਨੂੰ ਨਿਸ਼ਾਨਾ ਲਗਾਉਂਦਾ ਹੈ, ਸਹੀ ਥਾਵਾਂ ਵੱਲ ਇਸ਼ਾਰਾ ਕਰਦਾ ਹੈ, ਅਤੇ ਸਿਰਫ਼ ਉਹੀ ਚੀਜ਼ਾਂ ਬਦਲਦਾ ਹੈ ਜੋ ਰੇਪੋ ਸਾਬਤ ਕਰਦਾ ਹੈ।

ਅਗਲੇ ਕਦਮ: drift checks ਨੂੰ ਰੁਟੀਨ ਬਣਾਓ

ਦਸਤਾਵੇਜ਼ ਉਸ ਸਮੇਂ ਸਹੀ ਰਹਿੰਦੇ ਹਨ ਜਦੋਂ ਉਨ੍ਹਾਂ ਦੀ ਜਾਂਚ ਬੋਰੀنگ ਅਤੇ ਦੋਹਰਾਉਣਯੋਗ ਹੋ। ਆਪਣੀ cadence ਉਹ ਅਨੁਸਾਰ ਚੁਣੋ ਕਿ ਤੁਹਾਡੇ ਬਦਲਾਅ ਕਿੰਨੇ ਖਤਰਨਾਕ ਹਨ। ਤੇਜ਼ੀ ਨਾਲ ਬਦਲਦੇ ਕੋਡ ਲਈ, ਹਰ PR 'ਤੇ ਇਹ ਕਰੋ। ਸਥਿਰ ਸਰਵਿਸਜ਼ ਲਈ, ਇੱਕ ਹਫ਼ਤੇਵਾਰ sweep ਅਤੇ pre-release check ਕਾਫੀ ਹੋ ਸਕਦਾ ਹੈ।

Docs drift ਨੂੰ ਇੱਕ test failure ਵਾਂਗ ਸਮਝੋ, ਲਿਖਣ ਦਾ ਕੰਮ ਨਹੀਂ। Claude Code documentation drift ਦੀ ਵਰਤੋਂ ਕਰਕੇ ਇੱਕ ਛੋਟਾ diff ਅਤੇ contradictions ਦੀ ਛੋਟੀ ਲਿਸਟ ਜਨਰੇਟ ਕਰੋ, ਫਿਰ ਉਹਨਾਂ ਤੋਂ ਛੋਟਾ-ਸਭ ਤੋਂ ਕੰਮ ਕਰੋ ਜੋ docs ਨੂੰ ਦੁਬਾਰਾ ਸੱਚਾ ਬਣਾ ਦੇਵੇ।

ਲੈਟ-ਵਜ਼ਨ workflow ਜੋ ਹਲਕਾ ਰਹੇ:

• PR ਪ੍ਰਤੀ: ਪ੍ਰਭਾਵਤ ਫਾਇਲਾਂ (README, API docs, runbooks) 'ਤੇ ਇੱਕ drift check ਚਲਾਓ।
• diff summary ਨੂੰ ਆਪਣੀ PR description ਜਾਂ review notes ਵਿੱਚ ਸੇਵ ਕਰੋ ਤਾਂ ਕਿ ਰਿਵਿਊਅਰ ਵੇਖ ਸਕਣ ਕਿ ਕਿਉਂ ਬਦਲਿਆ ਗਿਆ।
• ਵੱਡੀਆਂ ਰੀ-ਰਾਈਟਸ ਦੀ ਥਾਂ, ਛੋਟੀਆਂ ਸੋਧਾਂ ਪਸੰਦ ਕਰੋ ਜੋ ਆਸਾਨੀ ਨਾਲ ਰਿਵਰਟ ਕੀਤੀਆਂ ਜਾ ਸਕਣ।
• ਰਿਲੀਜ਼ ਤੋਂ ਪਹਿਲਾਂ: ਉਹ ਚੀਜ਼ਾਂ ਮੁੜ-ਚੈੱਕ ਕਰੋ ਜੋ ਯੂਜ਼ਰ ਕਾਪੀ-ਪੇਸਟ ਕਰਨਗੇ (curl examples, env vars, deployment steps)।
• ਹਫ਼ਤੇਵਾਰ: ਇੱਕ-ਦੋ ਪੁਰਾਣੀਆਂ runbooks ਖੱ਼ਰੋ ਅਤੇ ਪੱਕਾ ਕਰੋ ਕਿ ਉਹ ਅੱਜ ਦੀਆਂ ਕਮਾਂਡਾਂ ਅਤੇ ਡੈਸ਼ਬੋਰਡਾਂ ਨਾਲ ਮਿਲਦੇ ਹਨ।

ਉਹ diff summaries ਅਗਲੇ ਸਮੇਂ ਲੱਭਣ ਯੋਗ ਰੱਖੋ। ਇੱਕ ਛੋਟੀ ਨੋਟ ਜਿਵੇਂ "Docs updated to match new /v2 endpoint, removed deprecated header, updated example response" ਮਦਦ ਕਰਦੀ ਹੈ ਜਦੋਂ ਕਿਸੇ ਨੂੰ ਮਹੀਨਿਆਂ ਬਾਅਦ ਪੁੱਛਣਾ ਹੋਵੇ ਕਿ doc ਕਿਉਂ ਬਦਲਿਆ।

Docs ਤੇ ਵੀ "snapshots and rollback" ਸੋਚ ਲਗਾਓ। ਜੇ ਕੋਈ ਨਿਰਦੇਸ਼ ਅਣਿਸ਼ਚਿਤ ਹੈ, ਤਾਂ ਪਹਿਲਾਂ ਇੱਕ ਥਾਂ 'ਤੇ ਬਦਲੋ, ਤੇਜ਼ੀ ਨਾਲ ਵੈਰੀਫਾਈ ਕਰੋ, ਫਿਰ ਪੁਸ਼ਟੀ ਸੰਸਕਰਣ ਹੋਰ ਥਾਵਾਂ 'ਤੇ ਨકલ ਕਰੋ।

ਜੇ ਤੁਸੀਂ ਤੇਜ਼ੀ ਨਾਲ ਬਣਾਉਂਦੇ ਹੋ, ਤਾਂ Koder.ai (koder.ai) ਵਿੱਚ ਐਪ ਅਤੇ ਉਸ ਦੀ ਪਹਿਲੀ docs ਇੱਕਠੇ ਜਨਰੇਟ ਕਰਨ ਨਾਲ ਮਦਦ ਮਿਲ ਸਕਦੀ ਹੈ, ਫਿਰ ਸੋਲੇਅਲੇ ਸੋਰਸ ਕੋਡ export ਕਰੋ ਅਤੇ ਆਪਣੇ ਆਮ workflow ਵਿੱਚ ਸੋਧਾਂ ਰਿਵਿਊਯੋਗ ਰੱਖੋ। ਮਕਸਦ ਸ਼ਾਨਦਾਰ ਪ੍ਰੋਜ਼ ਨਹੀਂ — ਉਹ ਹੈ ਜੋ ਲੋਕ ਕਰਦੇ ਹਨ (ਕਮਾਂਡ, endpoints, steps) ਨੂੰ ਕੋਡ ਨਾਲ ਮਿਲਾਉਣਾ।